2 Matrices

(require (planet wmfarr/plt-linalg:1:9/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.1 The Matrix Structrue

(make-matrix rows cols init) → real?

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.2 Matrix 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)     #:transparent)

elt : natural-number/c

Thrown by LU-decomposition routines. elt is the diagonal element of U which is zero.

2.3 Single-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 used the matrix-solve or matrix-solve-many procedures.

2.4 Matrix-Matrix and Matrix-Vector Operations

(matrix-add m1 m2) → matrix?

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.5 Solving 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.