You are looking at historical revision 23483 of this page. It may differ significantly from its current revision.

• egg

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

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

Ivan Raikov

### Version history

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
1.7
1.6
1.5
Migrated matrix-fold/map to srfi-4-utils
1.4
1.3
1.2
Bug fix in the definition of make-matrix-zeros
1.1
Fixes in the setup file
1.0
Initial release

```Copyright 2007-2011 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