### 2Matrices

 (require (planet wmfarr/plt-linalg:1:12/matrix))

A matrix is represented in the "plt-linalg.plt" package by a special datastructure: (make-matrix rows cols init). It contains a contiguous block of memory to hold (* rows cols) double-precision floating-point numbers. Operations on matrices (and vectors) are implemented by interfacing to native BLAS and LAPACK libraries.

#### 2.1The Matrix Structrue

 (make-matrix rows cols init) → matrix? rows : natural-number/c cols : natural-number/c init : real?
Constructs a matrix with rows rows and cols columns. The elements of this matrix are all init.

 (matrix rows cols elt ...) → matrix? rows : natural-number/c cols : natural-number/c elt : real?
Constructs a matrix with the given elt ... as elements. There must be exactly (* rows cols) elements given; the matrix is constructed in column-major order (note this is not left-to-right order). Column-major order is sometimes also called "FORTRAN" order, as opposed to "C" order.

 (matrix-identity n) → matrix? n : natural-number/c
Constructs an n by n identity matrix.

 (matrix? obj) → boolean? obj : any/c
Type predicate for matrices.

 (matrix-rows m) → natural-number/c m : matrix? (matrix-cols m) → natural-number/c m : matrix?
Selectors.

 (matrix-ref m i j) → real? m : matrix? i : (matrix-valid-row-index/c m) j : (matrix-valid-col-index/c m) (matrix-set! m i j x) → any m : matrix? i : (matrix-valid-row-index/c m) j : (matrix-valid-col-index/c m) x : real?
Returns or sets the i-j-th element of m.

 struct:matrix : any/c
Struture type descriptor for matrix structs.

 s:matrix : any/c
Transformer binding for matrix struct.

 _matrix : any/c
Foreign type for matrices. Translates to a pointer to a column-major (i.e. "FORTRAN", not "C" order) block of memory containing the elements of the matrix. Can be used inside _fun syntax in input, output, or input-output forms. In output form, the syntax is (_matrix o row-expr col-expr).

#### 2.2Matrix Contracts

Some contracts.

 (matrix-multiplication-compatible/c m) → flat-contract? m : matrix?
Contract matching matrices which can be left-multiplied by m.

 (matrix-valid-row-index/c m) → flat-contract? m : matrix? (matrix-valid-col-index/c m) → flat-contract? m : matrix?
Contracts which matches natural numbers which are valid row/col indices for m. (That is, xs such that (<= 0 x (sub1 (matrix-rows m))) or (<= 0 x (sub1 (matrix-cols m))).)

 matrix-square/c : flat-contract?
Matches square matrices.

 (matrix-same-dimensions/c m) → flat-contract? m : matrix?
Matches matrices with the same dimensions as m.

 (matrix-col-vector-compatible/c m) → flat-contract? m : matrix?
Matches f64vectors which are compatible for multiplication on the left by m.

 (matrix-row-vector-compatible/c m) → flat-contract? m : matrix?
Matches f64vectors which are compatible for multiplication on the right by m.

 (struct exn:singular-matrix exn (elt) #:extra-constructor-name make-exn:singular-matrix #:transparent)
elt : natural-number/c
Thrown by LU-decomposition routines. elt is the diagonal element of U which is zero.

#### 2.3Single-Matrix Operations

 (matrix-norm m) → (>=/c 0) m : matrix?
Returns the two-norm of a given matrix.

 (matrix-transpose m) → matrix? m : matrix?
Returns a new matrix which is the transpose of m.

 (matrix-inverse m) → matrix? m : square-matrix/c
Returns the matrix inverse of m. If you are trying to solve linear equations, it is much more stable (and efficient) to use the matrix-solve or matrix-solve-many procedures.

#### 2.4Matrix-Matrix and Matrix-Vector Operations

m1 : matrix?
m2 :
 (matrix-same-dimensions/c m1)
(matrix-sub m1 m2)  matrix?
m1 : matrix?
m2 :
 (matrix-same-dimensions/c m1)
Matrix addition and subtraction. Does not modify arguments.

 (matrix-scale m x) → matrix? m : matrix? x : real?
Returns a matrix whose elements are those of m scaled by x.

 (matrix-mul m1 m2) → matrix? m1 : matrix? m2 : (matrix-multiplication-compatible/c m1)
Matrix multiplication; does not modify its arguments.

#### 2.5Solving Linear Systems

 (matrix-solve m b) → (matrix-col-vector-compatible/c m) m : matrix-square/c b : (matrix-row-vector-compatible/c m)
Solves the system m*x = b for x.

 (matrix-solve-many m b) → (matrix-multiplication-compatible/c m) m : matrix-square/c b : (matrix-multiplication-compatible/c m)
Solves simultaneously many linear systems of the form m*x = b for x.

 (matrix-solve-least-squares m b) → (matrix-col-vector-compatible/c m) m : matrix? b : (matrix-row-vector-compatible/c m)
Solves m*x = b for x in a least-squares sense using SVD.