## matrix-utils

Generation of special utility matrices that are represented as SRFI-4 vectors.

## Usage

(require-extension matrix-utils)

## Documentation

`matrix-utils` contains a set of procedures that allow the convenient creation of utility matrices, such as identity matrices, diagonal matrices, zero matrices, and so on. It uses a representation of matrices as SRFI-4 vectors, where the matrix can be in row-major or column-major layout.

`matrix-utils` defines a procedure `(MAKE-FILL-MATRIX)` which takes as an argument an SRFI-4 vector setter and returns a `FILL-MATRIX!` procedure, which fills a given matrix with the values returned by applying a user-specified procedure to every pair of indices in the matrix, in a manner similar to fold. All other procedures in the library use the `FILL-MATRIX!` abstraction, and are constructed in a similar way, with SRFI-4 procedures and `FILL-MATRIX!` as parameters.

### Procedures

*[procedure]*

`make-matrix-map:: VECTOR-REF * VECTOR-SET! -> (ORDER * M * N * A * F * [IX * IY * EX * EY] -> A)`

Given procedures `VECTOR-REF` and `FILL-MATRIX!`, returns a procedure `MATRIX-MAP` of the form `MATRIX-MAP:: M * N * A * F * [IX * IY * EX * EY] -> B`

Where procedure `MATRIX-MAP` applies the map operation on a matrix `A` of size `M x N` with the values returned by applying procedure `F` to each pair of indices and the corresponding value at that position in the matrix.

Procedure `F` is of the form `LAMBDA I J V -> U`, where `V` is a matrix element at position `(I,J)` and `U` is corresponding element in the return matrix.

Optional arguments `IX IY EX EY` may specify a sub-matrix in matrix `A`.

`VECTOR-REF` is one of the homogeneous vector accessor procedures from SRFI-4.

*[procedure]*

`make-matrix-fold:: VECTOR-REF -> (ORDER * M * N * A * F * X0 * [IX * IY * EX * EY] -> A)`

Given a procedure `VECTOR-REF`, returns a procedure `MATRIX-FOLD` of the form `MATRIX-FOLD:: M * N * A * F * X0 * [IX * IY * EX * EY] -> XN`

Where procedure `MATRIX-FOLD` applies the fold operation on a matrix `A` of size `M x N` with the values returned by applying procedure `F` to each pair of indices and the corresponding value at that position in the matrix.

Procedure `F` is of the form `LAMBDA I J V AX -> AX1`, where `V` is a matrix element at position `(I,J)` and `AX` is accumulator value. The initial value of `AX` is given by `X0`. Procedure `F` is expected to return the new accumulator value.

Optional arguments `IX IY EX EY` may specify a sub-matrix in matrix `A`.

`VECTOR-REF` is one of the homogeneous vector accessor procedures from SRFI-4.

*[procedure]*

`make-matrix-fold-partial:: VECTOR-REF -> (ORDER * M * N * A * F * P * X0 * [IX * IY * EX * EY] -> A)`

Given a procedure `VECTOR-REF`, returns a procedure `MATRIX-FOLD-PARTIAL` of the form `MATRIX-FOLD-PARTIAL:: M * N * A * F * P * X0 * [IX * IY * EX * EY] -> XN`

Where procedure `MATRIX-FOLD-PARTIAL` applies the fold operation on a matrix `A` of size `M x N` with the values returned by applying procedure `F` to each pair of indices and the corresponding value at that position in the matrix. `MATRIX-FOLD-PARTIAL` first applies the predicate `P` to the current pair of indices, and if the result is true, then `F` is applied.

Procedure `F` is of the form `LAMBDA V AX -> AX1`, where `V` is a matrix element at position `(I,J)` and `AX` is accumulator value. The initial value of `AX` is given by `X0`. Procedure `F` is expected to return the new accumulator value.

Procedure `P` is of the form `LAMBDA I J -> boolean`, where `I,J` are matrix indices.

Optional arguments `IX IY EX EY` may specify a sub-matrix in matrix `A`.

`VECTOR-REF` is one of the homogeneous vector accessor procedures from SRFI-4.

*[procedure]*

`make-fill-matrix:: VECTOR-SET! -> (ORDER * M * N * A * F * F0 * [IX * IY * EX * EY] -> A)`

Given a procedure `VECTOR-SET!`, returns a procedure `FILL-MATRIX!` of the form `FILL-MATRIX!:: M * N * A * F * F0 * [IX * IY * EX * EY] -> A`

Where procedure `FILL-MATRIX!` fills matrix `A` of size `M x N` with the values returned by applying procedure `F` to each pair of indices in the matrix.

Procedure `F` is of the form `LAMBDA I J AX -> VAL * AX1`, where `I, J` are matrix indices, and `AX` is accumulator value (like in fold). The initial value of `AX` is given by `F0`. Procedure `F` is expected to return two values: the value to be placed in matrix `A` at position `[I,J]`, and the new accumulator value (or `#f`).

Optional arguments `IX IY EX EY` may specify a sub-matrix in matrix `A` to be filled. These arguments are checked to make sure they specify a valid sub-matrix.

`VECTOR-SET!` is one of the homogeneous vector setting procedures from SRFI-4. Procedure `F` must ensure that it returns values that are within the range of the SRFI-4 type used.

*[procedure]*

`make-matrix-ones:: MAKE-VECTOR * FILL-MATRIX! -> (M * N [* ORDER] -> A)`

Given procedures `MAKE-VECTOR` and `FILL-MATRIX!`, returns a procedure `ONES` of the form `ONES:: M * N [* ORDER] -> A`

Where procedure `ONES` returns a matrix `A` of size `M x N`, in which all elements are 1. Optional argument `ORDER` specifies the matrix layout: `ColMajor` or `RowMajor`, default is `RowMajor`.

`MAKE-VECTOR` is one of the homogeneous vector creation procedures from SRFI-4, and `FILL-MATRIX!` is a procedure created by `MAKE-FILL-MATRIX`, above. `FILL-MATRIX!` must operate on the same type of vector as `MAKE-VECTOR`.

*[procedure]*

`make-matrix-zeros:: MAKE-VECTOR * FILL-MATRIX! -> (M * N [* ORDER] -> A)`

Given procedures `MAKE-VECTOR` and `FILL-MATRIX!`, returns a procedure `ZEROS` of the form `ZEROS:: M * N [* ORDER] -> A`

Where procedure `ZEROS` returns a matrix `A` of size `M x N`, in which all elements are 0. Optional argument `ORDER` specifies the matrix layout: `ColMajor` or `RowMajor`, default is `RowMajor`.

`MAKE-VECTOR` is one of the homogeneous vector creation procedures from SRFI-4, and `FILL-MATRIX!` is a procedure created by `MAKE-FILL-MATRIX`, above. `FILL-MATRIX!` must operate on the same type of vector as `MAKE-VECTOR`.

*[procedure]*

`make-matrix-eye:: MAKE-VECTOR * FILL-MATRIX! -> (M * N [* ORDER] -> I)`

Given procedures `MAKE-VECTOR` and `FILL-MATRIX!`, returns a procedure `EYE` of the form `EYE:: M * N [* ORDER] -> I`

Where procedure `EYE` returns an identity matrix of size `M x N`. Optional argument `ORDER` specifies the matrix layout: `ColMajor` or `RowMajor`, default is `RowMajor`.

`MAKE-VECTOR` is one of the homogeneous vector creation procedures from SRFI-4, and `FILL-MATRIX!` is a procedure created by `MAKE-FILL-MATRIX`, above. `FILL-MATRIX!` must operate on the same type of vector as `MAKE-VECTOR`.

*[procedure]*

`make-matrix-diag:: VECTOR-REF * MAKE-VECTOR * FILL-MATRIX! -> (M * N * V [K * ORDER] -> D)`

Given procedures `VECTOR-REF`, `MAKE-VECTOR` and `FILL-MATRIX!`, returns a procedure `DIAG` of the form `DIAG:: M * N * V [K * ORDER] -> D`

Where procedure `DIAG` returns a diagonal matrix `D` of size `M x N`, with vector `V` on diagonal `K`. Argument `K` is optional. If it is positive, the vector is placed on the `K`-th super-diagonal of matrix `D`. If it is negative, it is placed on the -`K`-th sub-diagonal of matrix `D`. The default value of `K` is 0, and the vector is placed on the main diagonal of matrix `D`. Optional argument `ORDER` specifies the matrix layout: `ColMajor` or `RowMajor`, default is `RowMajor`. Vector `V` is always assumed to be a row vector.

`VECTOR-REF` and `MAKE-VECTOR` are two of the homogeneous vector procedures from SRFI-4, and `FILL-MATRIX!` is a procedure created by `MAKE-FILL-MATRIX`, above. `FILL-MATRIX!` must operate on the same type of vector as `VECTOR-REF` and `MAKE-VECTOR`.

*[procedure]*

`make-linspace:: MAKE-VECTOR * FILL-MATRIX! -> (N * BASE * LIMIT -> V)`

Given procedures `MAKE-VECTOR` and `FILL-MATRIX!`, returns a procedure `LINSPACE` of the form `LINSPACE:: N * BASE * LIMIT -> V`

Where `LINSPACE` returns a row vector with `N` linearly spaced elements between `BASE` and `LIMIT`. The number of elements, `N`, must be greater than 1. The `BASE` and `LIMIT` are always included in the range. If `BASE` is greater than `LIMIT`, the elements are stored in decreasing order.

`MAKE-VECTOR` is one of the homogeneous vector creation procedures from SRFI-4, and `FILL-MATRIX!` is a procedure created by `MAKE-FILL-MATRIX`, above. `FILL-MATRIX!` must operate on the same type of vector as `MAKE-VECTOR`.

*[procedure]*

`make-logspace:: VECTOR-REF * MAKE-VECTOR * FILL-MATRIX! -> (N * BASE * LIMIT -> V)`

Given procedures `VECTOR-REF`, `MAKE-VECTOR` and `FILL-MATRIX!`, returns a procedure `LOGSPACE` of the form `LOGSPACE:: N * BASE * LIMIT -> V`

Where `LOGSPACE` returns a row vector with `N` logarithmically spaced elements between `10^BASE` and `10^LIMIT`. The number of elements, `N`, must be greater than 1. The `BASE` and `LIMIT` are always included in the range. If `BASE` is greater than `LIMIT`, the elements are stored in decreasing order.

`VECTOR-REF` and `MAKE-VECTOR` are two of the homogeneous vector procedures from SRFI-4, and `FILL-MATRIX!` is a procedure created by `MAKE-FILL-MATRIX`, above. `FILL-MATRIX!` must operate on the same type of vector as `VECTOR-REF` and `MAKE-VECTOR`.

*[procedure]*

`f64vector-repmat:: SRC * DIMS * REPS -> A`

Constructs a block matrix of size `DIMS`, with a copy of matrix `SRC` as each element.

*[procedure]*

`f64vector-meshgrid:: X * Y [* Z] -> XX * YY [* ZZ]`

Given `f64vector` objects of X, Y, and Z coordinates, constructs matrices XX, YY, ZZ corresponding to a full 3-D grid. If optional argument Z is not given, then matrices XX and YY corresponding to a 2-D grid are constructed.

### Macros

*[syntax]*

`(define-utility-matrices type)`

Creates utility matrix procedures that create matrices of the specified type. `TYPE` is one of the following:

f64 | Double precision IEEE floating point |

f32 | Single precision IEEE floating point |

s32 | Signed 32-bit integer |

u32 | Unsigned 32-bit integer |

alist | An association list of the form ((vector-ref . proc) (make-vector . proc) (vector-set! . proc)) |

The following procedures are created:

fill-matrix! | |

ones | |

zeros | |

eye | |

diag | |

linspace | |

logspace |

*[syntax]*

`(with-utility-matrices type expr)`

As the above macro, except that it creates local bindings for the utility matrix procedures, and evaluates `EXPR` with those bindings.

*[syntax]*

`(define-matrix-map type)`

Creates procedure `MATRIX-MAP:: F * M -> A` that, given an input matrix `M` and procedure `F`, returns a new matrix `A` such that `A(i,j) = F(M(i,j))`. `TYPE` is one of the following:

- f64
- Double precision IEEE floating point
- f32
- Single precision IEEE floating point
- s32
- Signed 32-bit integer
- u32
- Unsigned 32-bit integer

## Examples

## About this egg

### Author

### Version history

- 1.14-1.15
- Added repmat and meshgrid
- 1.12
- Updated use of blas
- 1.11
- Documentation converted to wiki format
- 1.10
- Ported to Chicken 4
- 1.9
- Build script updated for better cross-platform compatibility
- 1.8
- Added procedure make-matrix-map
- 1.7
- Added procedure make-matrix-fold
- 1.6
- Added procedure make-matrix-fold-partial
- 1.5
- Migrated matrix-fold/map to srfi-4-utils
- 1.4
- Added define-matrix-fold
- 1.3
- Added define-matrix-map
- 1.2
- Bug fix in the definition of make-matrix-zeros
- 1.1
- Fixes in the setup file
- 1.0
- Initial release

### License

Copyright 2007-2014 Ivan Raikov and the Okinawa Institute of Science and Technology. This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. A full copy of the GPL license can be found at <http://www.gnu.org/licenses/>.