Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

matrix-utils

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

  1. Outdated egg!
  2. matrix-utils
  3. Usage
  4. Documentation
    1. Procedures
    2. Macros
  5. Examples
  6. About this egg
    1. Author
    2. Version history
    3. License

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

Ivan Raikov

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