The simple-matrix Library

This library contains basic functions for manipulating matrices and vectors. The functions come in two modules: "matrix-base.ss" for manipulating two-dimensional collections of objects, and "matrix.ss" for matipulating two-dimensional collections of numbers. If you do not need the numerical operations on matrices (matrix addition, multiplication, etc), use the "matrix-base.ss" module; otherwise, use the "matrix.ss" module. The "matrix.ss" module re-exports all the definitions from "matrix-base.ss".

The functions provided from the "matrix-base.ss" library include: iterators and looping constructs, getters and setters, and matrix-transpose. The functions provided from the "matrix.ss" library include: basic algebraic operations on matrices (addition, subtraction, ...), matrix-matrix-multiplication, matrix-vector multiplication, etc. 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 v3; see the License section for details.

1 The "matrix-base.ss" Module

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

(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.

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-base.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.

2 The "matrix.ss" Module

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

The "matrix.ss" module re-exports all the definitions from the "matrix-base.ss" module, in addition to the following definitions.

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

n : natural-number/c

The n by n identity matrix.

2.1 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".

2.2 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".

3 License

This software is released under the GNU General Public License, version 3. You can find a copy of the GPL as "gpl-3.0-standalone.html" in the root directory of this PLaneT package, or on the web.