#lang scribble/doc 

@(require scribble/manual
          (for-label scheme)
          (for-label "matrix.ss")
          (for-label "matrix-base.ss"))

@title{The @scheme[simple-matrix] Library}

@table-of-contents[]

This library contains basic functions for manipulating matrices and
vectors.  The functions come in two modules: @filepath{matrix-base.ss}
for manipulating two-dimensional collections of objects, and
@filepath{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
@filepath{matrix-base.ss} module; otherwise, use the
@filepath{matrix.ss} module.  The @filepath{matrix.ss} module
re-exports all the definitions from @filepath{matrix-base.ss}.

The functions provided from the @filepath{matrix-base.ss} library
include: iterators and looping constructs, getters and setters, and
matrix-transpose.  The functions provided from the
@filepath{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, @filepath{matrix-lang.ss}, which re-defines
the standard scheme functions @scheme[+], @scheme[-], @scheme[*],
@scheme[/] to operate on numbers, vectors and matrices, and
re-provides all of @scheme['scheme] and @filepath{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
@seclink["License"]{License} section for details.

@section[#:tag "matrix-base"]{The @filepath{matrix-base.ss} Module}

@defmodule[(planet wmfarr/simple-matrix:1:1/matrix-base)]

@defstruct[matrix ((rows natural-number/c)
                   (cols natural-number/c)
                   (elts (vectorof number?))) #:inspector #f]{

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

}


@defproc[(matrix* (rows natural-number/c) (cols natural-number/c)
                  (elt number?) ...) matrix?]{

Constructs a matrix from the given @scheme[elt ...], in row-major
order.

}


@defproc[(matrix-ref (m matrix?)
                     (i (and/c natural-number/c 
                               (</c (matrix-rows m))))
                     (j (and/c natural-number/c 
                               (</c (matrix-cols m))))) matrix?]{

Get the @scheme[i], @scheme[j] entry in @scheme[m].

}


@defproc[(matrix-set! (m matrix?)
                      (i (and/c natural-number/c 
                                (</c (matrix-rows m))))
                      (j (and/c natural-number/c 
                                (</c (matrix-cols m))))
                      (x number?)) any]{

Set the @scheme[i], @scheme[j] entry in @scheme[m] to @scheme[x].

}


@defproc[(matrix-transpose (m matrix?)) (matrix-of-dimensions/c (matrix-cols m) (matrix-rows m))]{

The transpose of @scheme[m].

}


@subsection[#:tag "contracts"]{Contracts}

@defproc[(matrix-of-dimensions/c (ni natural-number/c) (nj
natural-number/c)) flat-contract?]
@defproc[(matrix-of-rows/c (ni natural-number/c)) flat-contract?]
@defproc[(matrix-of-cols/c (nj natural-number/c)) flat-contract?]
@defproc[(vector-of-length/c (n natural-number/c)) flat-contract?]
@defproc[(matrix-same-dimensions/c (m matrix?)) flat-contract?]
@defproc[(matrix-mul-compatible/c (m matrix?)) flat-contract?]{

Contract for matrices which can be multiplied on the left my
@scheme[m].

}
@defproc[(matrix-mul-result/c (m1 matrix?) (m2 matrix?)) flat-contract?]
@defproc[(list-of-length/c (n natural-number/c)) flat-contract?]

@subsection[#:tag "iteration-forms"]{Iteration Forms}

The @filepath{matrix-base.ss} library provides many iteration forms
which make manipulating vectors and matrices much more convenient.
This subsection documents these forms.

@defproc[(in-matrix (m matrix?)) sequence?]{

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

@schemeblock[
(for/list ((x (in-matrix m))) 
  x)
] 

(which collects all the elements of @scheme[m] in a list), or

@schemeblock[
(for/list (((i j x) (in-matrix m))) 
  (list i j x))
] 

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

}

@defform[(for/vector length-expr (for-clause ...) body)]
@defform[(for*/vector length-expr (for-clause ...) body)]{

Creates a vector of length @scheme[length-expr], filled with the
successive values of @scheme[body].

}


@defform[(for/matrix row-expr col-expr (for-clause ...) body)]
@defform[(for*/matrix row-expr col-expr (for-clause ...) body)]{

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

}




@section[#:tag "matrix-functions"]{The @filepath{matrix.ss} Module}

@defmodule[(planet wmfarr/simple-matrix:1:1/matrix)]

The @filepath{matrix.ss} module re-exports all the definitions from
the @filepath{matrix-base.ss} module, in addition to the following
definitions.

@defproc[(matrix-identity (n natural-number/c)) (matrix-of-dimensions/c n n)]{

The @scheme[n] by @scheme[n] identity matrix.

}

@subsection[#:tag "basic-arithmetic"]{Basic Arithmetic}

The @filepath{matrix.ss} library provides functions to perform basic
arithmetic on vectors and matrices.

@defproc[
(vector-add (v1 (vectorof number?))
            (v2 (and/c (vectorof number?)
                       (vector-of-length/c (vector-length v1)))))
(vector-of-length/c (vector-length v1))
]{

Adds together, elementwise, @scheme[v1], and @scheme[v2].  If you use
the @filepath{matrix-lang.ss} module, this operation is represented by
@scheme[(+ v1 v2)].

}


@defproc[
(vector-sub (v1 (vectorof number?))
            (v2 (and/c (vectorof number?)
                       (vector-of-length/c (vector-length v1)))))
(vector-of-length/c (vector-length v1))
]{

Subtracts @scheme[v1] from @scheme[v2].  Also @scheme[(- v1 v2)] in
@filepath{matrix-lang.ss}.

}


@defproc[
(vector-scale (v (vectorof number?))
              (s number?))
(vector-of-length/c (vector-length v))
]{

Scales @scheme[v] by the scalar @scheme[s].  @scheme[(* v s)],
@scheme[(* s v)], or @scheme[(/ v (/ s))] in
@filepath{matrix-lang.ss}.

}


@defproc[
(vector-dot (v1 (vectorof number?))
            (v2 (and/c (vectorof number?)
                       (vector-of-length/c (vector-length v1)))))
number?
]{

Dot product of @scheme[v1] and @scheme[v2].  @scheme[(* v1 v2)] in
@filepath{matrix-lang.ss}.

}



@defproc[
(matrix-add (m1 matrix?)
            (m2 (matrix-same-dimensions/c m1)))
(matrix-same-dimensions/c m1)
]{

Elementwise sum of @scheme[m1] and @scheme[m2].  @scheme[(+ m1 m2)] in
@filepath{matrix-lang.ss}.

}


@defproc[
(matrix-sub (m1 matrix?)
            (m2 (matrix-same-dimensions/c m1)))
(matrix-same-dimensions/c m1)
]{

Elementwise difference of @scheme[m1] and @scheme[m2].  @scheme[(- m1
m2)] in @filepath{matrix-lang.ss}.

}


@defproc[
(matrix-scale (m matrix?)
              (s number?))
(matrix-same-dimensions/c m)
]{

Scales @scheme[m] by the scalar @scheme[s].  @scheme[(* m s)],
@scheme[(* s m)], or @scheme[(/ m (/ s))] in
@filepath{matrix-lang.ss}.

}


@subsection[#:tag "matrix-vector-matrix-matrix-ops"]{Matrix-vector and
Matrix-matrix Operations}


@defproc[
(matrix-vector-mul (m matrix?)
                   (v (and/c (vectorof number?)
                             (vector-of-length/c (matrix-cols m)))))
(and/c (vectorof number?)
       (vector-of-length/c (matrix-rows m)))
]{

Basic left multiplication by a matrix.  Also @scheme[(* m v)] in
@filepath{matrix-lang.ss}.

}


@defproc[
(vector-matrix-mul (v (vectorof number?))
                   (m (matrix-of-rows/c (vector-length v))))
(and/c (vectorof number?)
       (vector-of-length/c (matrix-cols m)))
]{

Basic right multiplication by a matrix.  Also @scheme[(* v m)] in
@filepath{matrix-lang.ss}.

}


@defproc[
(matrix-mul (m1 matrix?)
            (m2 (matrix-mul-compatible/c m1)))
(matrix-mul-result/c m1 m2)
]{

Matrix-matrix multiplication.  Also @scheme[(* m1 m2)] in
@filepath{matrix-lang.ss}.

}


@section[#:tag "License"]{License} 

This software is released under the GNU General Public License,
version 3.  You can find a copy of the GPL as
@filepath{gpl-3.0-standalone.html} in the root directory of this
PLaneT package, or @link["http://www.gnu.org/licenses/gpl.html"]{on
the web}.