Structural Informatics Group (SIG) logo
Home | Projects | Demos | Downloads | Publications | Local Info | About Us | New site
Go to the first, previous, next, last section, table of contents.

XMTH-MULT

source files: xmth.[ch]

SYNTAX

(XMTH-MULT
  :LEFT <float-array>
  :RIGHT <float-array>
[ :TRANSPOSE-LEFT  t ]
[ :TRANSPOSE-RIGHT t ]
[ :RESULT-IN <float-array> ]
)

DESCRIPTION

This function provides a reasonably general matrix-multiply facility. The two input arrays are given by the :LEFT and :RIGHT keyword arguments. Both must be two-dimensional float arrays (although one of the dimensions may be of size one if desired, making the array effectively one-dimensional).

The number of columns (second dimension) in the :LEFT matrix must be equal to the number of rows (first dimension) in the :RIGHT matrix: The resulting array, which is returned as the result value of the function, will have as many rows as the :LEFT matrix and as many columns as the :RIGHT matrix.

It is frequently the case that to obtain the desired result matrix, one or both of the input matrices need to be transposed. To avoid the need to explicitly create a transposed version of the input matrix in such cases, xmth-mult accepts optional keyword arguments :transpose-left and :transpose-right which invoke specially hacked versions of the multiplication algorithm which behave as though the indicated input matrixes had been transposed, without actually taking the time or space to do so.

It is also frequently the case that one would like to repeatedly multiply matrices without having to allocate a new output matrix each time, thrashing the garbage collector. As an efficiency hack, therefor, xmth-mult accepts an optional :result-in keyword supplying a matrix to hold the result. If the specified value is of the correct type and shape, it is used to hold the result value; Otherwise, it is ignored and a new result value created. Thus, a simple and efficient coding habit in many cases is:

(defvar *my-result* nil)
...
   (setq *my-result*
     (xmth-mult
       :left  input1
       :right input2
       :result-in *my-result*
   ) )

This will re-use the previous result matrix when sensible, and otherwise allocate a new one. Obviously, this makes no sense if there is any possibility that the old value of *my-result* is still in use in the program.


Go to the first, previous, next, last section, table of contents.