## matrix-utils

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

## TOC »

## 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

`make-matrix-map:: VECTOR-REF * VECTOR-SET! -> (ORDER * M * N * A * F * [IX * IY * EX * EY] -> A)`procedureGiven 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.

`make-matrix-fold:: VECTOR-REF -> (ORDER * M * N * A * F * X0 * [IX * IY * EX * EY] -> A)`procedureGiven 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.

`make-matrix-fold-partial:: VECTOR-REF -> (ORDER * M * N * A * F * P * X0 * [IX * IY * EX * EY] -> A)`procedureGiven 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.

`make-fill-matrix:: VECTOR-SET! -> (ORDER * M * N * A * F * F0 * [IX * IY * EX * EY] -> A)`procedureGiven 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.

`make-matrix-ones:: MAKE-VECTOR * FILL-MATRIX! -> (M * N [* ORDER] -> A)`procedureGiven 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`.

`make-matrix-zeros:: MAKE-VECTOR * FILL-MATRIX! -> (M * N [* ORDER] -> A)`procedureGiven 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`.

`make-matrix-eye:: MAKE-VECTOR * FILL-MATRIX! -> (M * N [* ORDER] -> I)`procedureGiven 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`.

`make-matrix-diag:: VECTOR-REF * MAKE-VECTOR * FILL-MATRIX! -> (M * N * V [K * ORDER] -> D)`procedureGiven 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`.

`make-linspace:: MAKE-VECTOR * FILL-MATRIX! -> (N * BASE * LIMIT -> V)`procedureGiven 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`.

`make-logspace:: VECTOR-REF * MAKE-VECTOR * FILL-MATRIX! -> (N * BASE * LIMIT -> V)`procedureGiven 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`.

`f64vector-repmat:: SRC * DIMS * REPS -> A`procedureConstructs a block matrix of size

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

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

`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

`(define-utility-matrices type)`syntaxCreates 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

`(with-utility-matrices type expr)`syntaxAs the above macro, except that it creates local bindings for the utility matrix procedures, and evaluates

`EXPR`with those bindings.

`(define-matrix-map type)`syntaxCreates 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/>.