The simple-matrix Library

This library contains basic functions for manipulating matrices and vectors. These include: iterators and looping constructs, arithmetic, and matrix-vector operations. The library does not include any functions from traditional linear algebra (such as solving linear equations, finding eigenvalues, etc). The library comes with an initial module language, "matrix-lang.ss", which re-defines the standard scheme functions +, -, *, / to operate on numbers, vectors and matrices, and re-provides all of 'scheme and "matrix.ss" as well. Use this module language when you are more concerned with clarity than speed – basic arithmetic operations on scalars will no longer be inlined, and performance will suffer.

This library is released under the GNU GPL; see the License section for details.

1 The "matrix.ss" Module

(require (planet wmfarr/simple-matrix:1:0/matrix))

(struct   matrix   (rows cols elts))     #:transparent)

rows : natural-number/c

cols : natural-number/c

elts : (vectorof number?)

A matrix with the given dimensions. The elts are stored in row-major order.

(matrix* rows cols elt ...) → matrix?

rows : natural-number/c

cols : natural-number/c

elt : number?

Constructs a matrix from the given elt ..., in row-major order.

(matrix-ref m i j) → matrix?

m : matrix?

i   :   (and/c natural-number/c        (</c (matrix-rows m)))

j   :   (and/c natural-number/c        (</c (matrix-cols m)))

Get the i, j entry in m.

(matrix-set! m i j x) → any

m : matrix?

i   :   (and/c natural-number/c        (</c (matrix-rows m)))

j   :   (and/c natural-number/c        (</c (matrix-cols m)))

x : number?

Set the i, j entry in m to x.

(matrix-transpose m)

→ (matrix-of-dimensions/c (matrix-cols m) (matrix-rows m))

m : matrix?

The transpose of m.

(matrix-identity n) → (matrix-of-dimensions/c n n)

n : natural-number/c

The n by n identity matrix.

1.1 Contracts

(matrix-of-dimensions/c ni nj) → flat-contract?

ni : natural-number/c

nj : natural-number/c

(matrix-of-rows/c ni) → flat-contract?

ni : natural-number/c

(matrix-of-cols/c nj) → flat-contract?

nj : natural-number/c

(vector-of-length/c n) → flat-contract?

n : natural-number/c

(matrix-same-dimensions/c m) → flat-contract?

m : matrix?

(matrix-mul-compatible/c m) → flat-contract?

m : matrix?

Contract for matrices which can be multiplied on the left my m.

(matrix-mul-result/c m1 m2) → flat-contract?

m1 : matrix?

m2 : matrix?

(list-of-length/c n) → flat-contract?

n : natural-number/c

1.2 Iteration Forms

The "matrix.ss" library provides many iteration forms which make manipulating vectors and matrices much more convenient. This subsection documents these forms.

(in-matrix m) → sequence?

m : matrix?

Sequence enumerating the elements of m, in row-major order. Can also be used as a fast for-clause, as in either

(for/list ((x (in-matrix m)))

x)

(which collects all the elements of m in a list), or

(for/list (((i j x) (in-matrix m)))

(list i j x))

which collects a list of row, column, element lists.

(for/vector length-expr (for-clause ...) body)

(for*/vector length-expr (for-clause ...) body)

Creates a vector of length length-expr, filled with the successive values of body.

(for/matrix row-expr col-expr (for-clause ...) body)

(for*/matrix row-expr col-expr (for-clause ...) body)

Creates a matrix of dimensions row-expr by col-expr, whose elements are the successive values of body, in row-major order.

1.3 Basic Arithmetic

The "matrix.ss" library provides functions to perform basic arithmetic on vectors and matrices.

(vector-add v1 v2) → (vector-of-length/c (vector-length v1))

v1 : (vectorof number?)

v2   :   (and/c (vectorof number?)        (vector-of-length/c (vector-length v1)))

Adds together, elementwise, v1, and v2. If you use the "matrix-lang.ss" module, this operation is represented by (+ v1 v2).

(vector-sub v1 v2) → (vector-of-length/c (vector-length v1))

v1 : (vectorof number?)

v2   :   (and/c (vectorof number?)        (vector-of-length/c (vector-length v1)))

Subtracts v1 from v2. Also (- v1 v2) in "matrix-lang.ss".

(vector-scale v s) → (vector-of-length/c (vector-length v))

v : (vectorof number?)

s : number?

Scales v by the scalar s. (* v s), (* s v), or (/ v (/ s)) in "matrix-lang.ss".

(vector-dot v1 v2) → number?

v1 : (vectorof number?)

v2   :   (and/c (vectorof number?)        (vector-of-length/c (vector-length v1)))

Dot product of v1 and v2. (* v1 v2) in "matrix-lang.ss".

(matrix-add m1 m2) → (matrix-same-dimensions/c m1)

m1 : matrix?

m2 : (matrix-same-dimensions/c m1)

Elementwise sum of m1 and m2. (+ m1 m2) in "matrix-lang.ss".

(matrix-sub m1 m2) → (matrix-same-dimensions/c m1)

m1 : matrix?

m2 : (matrix-same-dimensions/c m1)

Elementwise difference of m1 and m2. (- m1 m2) in "matrix-lang.ss".

(matrix-scale m s) → (matrix-same-dimensions/c m)

m : matrix?

s : number?

Scales m by the scalar s. (* m s), (* s m), or (/ m (/ s)) in "matrix-lang.ss".

1.4 Matrix-vector and Matrix-matrix Operations

(matrix-vector-mul m v)

→   (and/c (vectorof number?)        (vector-of-length/c (matrix-rows m)))

m : matrix?

v   :   (and/c (vectorof number?)        (vector-of-length/c (matrix-cols m)))

Basic left multiplication by a matrix. Also (* m v) in "matrix-lang.ss".

(vector-matrix-mul v m)

→   (and/c (vectorof number?)        (vector-of-length/c (matrix-cols m)))

v : (vectorof number?)

m : (matrix-of-rows/c (vector-length v))

Basic right multiplication by a matrix. Also (* v m) in "matrix-lang.ss".

(matrix-mul m1 m2) → (matrix-mul-result/c m1 m2)

m1 : matrix?

m2 : (matrix-mul-compatible/c m1)

Matrix-matrix multiplication. Also (* m1 m2) in "matrix-lang.ss".

2 License

This software is released under the GNU General Public License, version 3. You can find a copy of the GPL here, or on the web.