((section 2 "Outdated egg!" (p "This is an egg for CHICKEN 4, the unsupported old release.  You're almost certainly looking for " (int-link "/eggref/5/matrix-utils" "the CHICKEN 5 version of this egg") ", if it exists.") (p "If it does not exist, there may be equivalent functionality provided by another egg; have a look at the " (link "https://wiki.call-cc.org/chicken-projects/egg-index-5.html" "egg index") ". Otherwise, please consider porting this egg to the current version of CHICKEN.") (tags "egg")) (section 2 "matrix-utils" (p "Generation of special utility matrices that are represented as SRFI-4 vectors.") (toc)) (section 2 "Usage" (p "(require-extension matrix-utils)")) (section 2 "Documentation" (p (tt "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 " (link "http://srfi.schemers.org/srfi-4/srfi-4.html" "SRFI-4") " vectors, where the matrix can be in row-major or column-major layout.") (p (tt "matrix-utils") " defines a procedure " (tt "(MAKE-FILL-MATRIX)") " which takes as an argument an SRFI-4 vector setter and returns a " (tt "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 " (tt "FILL-MATRIX!") " abstraction, and are constructed in a similar way, with SRFI-4 procedures and " (tt "FILL-MATRIX!") " as parameters.") (section 3 "Procedures" (def (sig (procedure "make-matrix-map:: VECTOR-REF * VECTOR-SET! -> (ORDER * M * N * A * F * [IX * IY * EX * EY] -> A)" (id make-matrix-map))) (p "Given procedures " (tt "VECTOR-REF") " and " (tt "FILL-MATRIX!") ", returns a procedure " (tt "MATRIX-MAP") " of the form " (tt "MATRIX-MAP:: M * N * A * F * [IX * IY * EX * EY] -> B")) (p "Where procedure " (tt "MATRIX-MAP") " applies the map operation on a matrix " (tt "A") " of size " (tt "M x N") " with the values returned by applying procedure " (tt "F") " to each pair of indices and the corresponding value at that position in the matrix.") (p "Procedure " (tt "F") " is of the form " (tt "LAMBDA I J V -> U") ", where " (tt "V") " is a matrix element at position " (tt "(I,J)") " and " (tt "U") " is corresponding element in the return matrix.") (p "Optional arguments " (tt "IX IY EX EY") " may specify a sub-matrix in matrix " (tt "A") ".") (p (tt "VECTOR-REF") " is one of the homogeneous vector accessor procedures from SRFI-4.")) (def (sig (procedure "make-matrix-fold:: VECTOR-REF -> (ORDER * M * N * A * F * X0 * [IX * IY * EX * EY] -> A)" (id make-matrix-fold))) (p "Given a procedure " (tt "VECTOR-REF") ", returns a procedure " (tt "MATRIX-FOLD") " of the form " (tt "MATRIX-FOLD:: M * N * A * F * X0 * [IX * IY * EX * EY] -> XN")) (p "Where procedure " (tt "MATRIX-FOLD") " applies the fold operation on a matrix " (tt "A") " of size " (tt "M x N") " with the values returned by applying procedure " (tt "F") " to each pair of indices and the corresponding value at that position in the matrix.") (p "Procedure " (tt "F") " is of the form " (tt "LAMBDA I J V AX -> AX1") ", where " (tt "V") " is a matrix element at position " (tt "(I,J)") " and " (tt "AX") " is accumulator value. The initial value of " (tt "AX") " is given by " (tt "X0") ". Procedure " (tt "F") " is expected to return the new accumulator value.") (p "Optional arguments " (tt "IX IY EX EY") " may specify a sub-matrix in matrix " (tt "A") ".") (p (tt "VECTOR-REF") " is one of the homogeneous vector accessor procedures from SRFI-4.")) (def (sig (procedure "make-matrix-fold-partial:: VECTOR-REF -> (ORDER * M * N * A * F * P * X0 * [IX * IY * EX * EY] -> A)" (id make-matrix-fold-partial))) (p "Given a procedure " (tt "VECTOR-REF") ", returns a procedure " (tt "MATRIX-FOLD-PARTIAL") " of the form " (tt "MATRIX-FOLD-PARTIAL:: M * N * A * F * P * X0 * [IX * IY * EX * EY] -> XN")) (p "Where procedure " (tt "MATRIX-FOLD-PARTIAL") " applies the fold operation on a matrix " (tt "A") " of size " (tt "M x N") " with the values returned by applying procedure " (tt "F") " to each pair of indices and the corresponding value at that position in the matrix. " (tt "MATRIX-FOLD-PARTIAL") " first applies the predicate " (tt "P") " to the current pair of indices, and if the result is true, then " (tt "F") " is applied.") (p "Procedure " (tt "F") " is of the form " (tt "LAMBDA V AX -> AX1") ", where " (tt "V") " is a matrix element at position " (tt "(I,J)") " and " (tt "AX") " is accumulator value. The initial value of " (tt "AX") " is given by " (tt "X0") ". Procedure " (tt "F") " is expected to return the new accumulator value.") (p "Procedure " (tt "P") " is of the form " (tt "LAMBDA I J -> boolean") ", where " (tt "I,J") " are matrix indices.") (p "Optional arguments " (tt "IX IY EX EY") " may specify a sub-matrix in matrix " (tt "A") ".") (p (tt "VECTOR-REF") " is one of the homogeneous vector accessor procedures from SRFI-4.")) (def (sig (procedure "make-fill-matrix:: VECTOR-SET! -> (ORDER * M * N * A * F * F0 * [IX * IY * EX * EY] -> A)" (id make-fill-matrix))) (p "Given a procedure " (tt "VECTOR-SET!") ", returns a procedure " (tt "FILL-MATRIX!") " of the form " (tt "FILL-MATRIX!:: M * N * A * F * F0 * [IX * IY * EX * EY] -> A")) (p "Where procedure " (tt "FILL-MATRIX!") " fills matrix " (tt "A") " of size " (tt "M x N") " with the values returned by applying procedure " (tt "F") " to each pair of indices in the matrix.") (p "Procedure " (tt "F") " is of the form " (tt "LAMBDA I J AX -> VAL * AX1") ", where " (tt "I, J") " are matrix indices, and " (tt "AX") " is accumulator value (like in fold). The initial value of " (tt "AX") " is given by " (tt "F0") ". Procedure " (tt "F") " is expected to return two values: the value to be placed in matrix " (tt "A") " at position " (tt "[I,J]") ", and the new accumulator value (or " (tt "#f") ").") (p "Optional arguments " (tt "IX IY EX EY") " may specify a sub-matrix in matrix " (tt "A") " to be filled. These arguments are checked to make sure they specify a valid sub-matrix.") (p (tt "VECTOR-SET!") " is one of the homogeneous vector setting procedures from SRFI-4. Procedure " (tt "F") " must ensure that it returns values that are within the range of the SRFI-4 type used.")) (def (sig (procedure "make-matrix-ones:: MAKE-VECTOR * FILL-MATRIX! -> (M * N [* ORDER] -> A)" (id make-matrix-ones))) (p "Given procedures " (tt "MAKE-VECTOR") " and " (tt "FILL-MATRIX!") ", returns a procedure " (tt "ONES") " of the form " (tt "ONES:: M * N [* ORDER] -> A")) (p "Where procedure " (tt "ONES") " returns a matrix " (tt "A") " of size " (tt "M x N") ", in which all elements are 1. Optional argument " (tt "ORDER") " specifies the matrix layout: " (tt "ColMajor") " or " (tt "RowMajor") ", default is " (tt "RowMajor") ".") (p (tt "MAKE-VECTOR") " is one of the homogeneous vector creation procedures from SRFI-4, and " (tt "FILL-MATRIX!") " is a procedure created by " (tt "MAKE-FILL-MATRIX") ", above. " (tt "FILL-MATRIX!") " must operate on the same type of vector as " (tt "MAKE-VECTOR") ".")) (def (sig (procedure "make-matrix-zeros:: MAKE-VECTOR * FILL-MATRIX! -> (M * N [* ORDER] -> A)" (id make-matrix-zeros))) (p "Given procedures " (tt "MAKE-VECTOR") " and " (tt "FILL-MATRIX!") ", returns a procedure " (tt "ZEROS") " of the form " (tt "ZEROS:: M * N [* ORDER] -> A")) (p "Where procedure " (tt "ZEROS") " returns a matrix " (tt "A") " of size " (tt "M x N") ", in which all elements are 0. Optional argument " (tt "ORDER") " specifies the matrix layout: " (tt "ColMajor") " or " (tt "RowMajor") ", default is " (tt "RowMajor") ".") (p (tt "MAKE-VECTOR") " is one of the homogeneous vector creation procedures from SRFI-4, and " (tt "FILL-MATRIX!") " is a procedure created by " (tt "MAKE-FILL-MATRIX") ", above. " (tt "FILL-MATRIX!") " must operate on the same type of vector as " (tt "MAKE-VECTOR") ".")) (def (sig (procedure "make-matrix-eye:: MAKE-VECTOR * FILL-MATRIX! -> (M * N [* ORDER] -> I)" (id make-matrix-eye))) (p "Given procedures " (tt "MAKE-VECTOR") " and " (tt "FILL-MATRIX!") ", returns a procedure " (tt "EYE") " of the form " (tt "EYE:: M * N [* ORDER] -> I")) (p "Where procedure " (tt "EYE") " returns an identity matrix of size " (tt "M x N") ". Optional argument " (tt "ORDER") " specifies the matrix layout: " (tt "ColMajor") " or " (tt "RowMajor") ", default is " (tt "RowMajor") ".") (p (tt "MAKE-VECTOR") " is one of the homogeneous vector creation procedures from SRFI-4, and " (tt "FILL-MATRIX!") " is a procedure created by " (tt "MAKE-FILL-MATRIX") ", above. " (tt "FILL-MATRIX!") " must operate on the same type of vector as " (tt "MAKE-VECTOR") ".")) (def (sig (procedure "make-matrix-diag:: VECTOR-REF * MAKE-VECTOR * FILL-MATRIX! -> (M * N * V [K * ORDER] -> D)" (id make-matrix-diag))) (p "Given procedures " (tt "VECTOR-REF") ", " (tt "MAKE-VECTOR") " and " (tt "FILL-MATRIX!") ", returns a procedure " (tt "DIAG") " of the form " (tt "DIAG:: M * N * V [K * ORDER] -> D")) (p "Where procedure " (tt "DIAG") " returns a diagonal matrix " (tt "D") " of size " (tt "M x N") ", with vector " (tt "V") " on diagonal " (tt "K") ". Argument " (tt "K") " is optional. If it is positive, the vector is placed on the " (tt "K") "-th super-diagonal of matrix " (tt "D") ".  If it is negative, it is placed on the -" (tt "K") "-th sub-diagonal of matrix " (tt "D") ".  The default value of " (tt "K") " is 0, and the vector is placed on the main diagonal of matrix " (tt "D") ". Optional argument " (tt "ORDER") " specifies the matrix layout: " (tt "ColMajor") " or " (tt "RowMajor") ", default is " (tt "RowMajor") ". Vector " (tt "V") " is always assumed to be a row vector.") (p (tt "VECTOR-REF") " and " (tt "MAKE-VECTOR") " are two of the homogeneous vector procedures from SRFI-4, and " (tt "FILL-MATRIX!") " is a procedure created by " (tt "MAKE-FILL-MATRIX") ", above. " (tt "FILL-MATRIX!") " must operate on the same type of vector as " (tt "VECTOR-REF") " and " (tt "MAKE-VECTOR") ".")) (def (sig (procedure "make-linspace:: MAKE-VECTOR * FILL-MATRIX! -> (N * BASE * LIMIT -> V)" (id make-linspace))) (p "Given procedures " (tt "MAKE-VECTOR") " and " (tt "FILL-MATRIX!") ", returns a procedure " (tt "LINSPACE") " of the form " (tt "LINSPACE:: N * BASE * LIMIT -> V")) (p "Where " (tt "LINSPACE") " returns a row vector with " (tt "N") " linearly spaced elements between " (tt "BASE") " and " (tt "LIMIT") ".  The number of elements, " (tt "N") ", must be greater than 1. The " (tt "BASE") " and " (tt "LIMIT") " are always included in the range. If " (tt "BASE") " is greater than " (tt "LIMIT") ", the elements are stored in decreasing order.") (p (tt "MAKE-VECTOR") " is one of the homogeneous vector creation procedures from SRFI-4, and " (tt "FILL-MATRIX!") " is a procedure created by " (tt "MAKE-FILL-MATRIX") ", above. " (tt "FILL-MATRIX!") " must operate on the same type of vector as " (tt "MAKE-VECTOR") ".")) (def (sig (procedure "make-logspace:: VECTOR-REF * MAKE-VECTOR * FILL-MATRIX! -> (N * BASE * LIMIT -> V)" (id make-logspace))) (p "Given procedures " (tt "VECTOR-REF") ", " (tt "MAKE-VECTOR") " and " (tt "FILL-MATRIX!") ", returns a procedure " (tt "LOGSPACE") " of the form " (tt "LOGSPACE:: N * BASE * LIMIT -> V")) (p "Where " (tt "LOGSPACE") " returns a row vector with " (tt "N") " logarithmically spaced elements between " (tt "10^BASE") " and " (tt "10^LIMIT") ". The number of elements, " (tt "N") ", must be greater than 1. The " (tt "BASE") " and " (tt "LIMIT") " are always included in the range. If " (tt "BASE") " is greater than " (tt "LIMIT") ", the elements are stored in decreasing order.") (p (tt "VECTOR-REF") " and " (tt "MAKE-VECTOR") " are two of the homogeneous vector procedures from SRFI-4, and " (tt "FILL-MATRIX!") " is a procedure created by " (tt "MAKE-FILL-MATRIX") ", above. " (tt "FILL-MATRIX!") " must operate on the same type of vector as " (tt "VECTOR-REF") " and " (tt "MAKE-VECTOR") ".")) (def (sig (procedure "f64vector-repmat:: SRC * DIMS * REPS -> A" (id f64vector-repmat))) (p "Constructs a block matrix of size " (tt "DIMS") ", with a copy of matrix " (tt "SRC") " as each element.")) (def (sig (procedure "f64vector-meshgrid:: X * Y [* Z] -> XX * YY [* ZZ]" (id f64vector-meshgrid))) (p "Given " (tt "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."))) (section 3 "Macros" (def (sig (syntax "(define-utility-matrices type)" (id define-utility-matrices))) (p "Creates utility matrix procedures that create matrices of the specified type. " (tt "TYPE") " is one of the following:") (table (@ (class "symbol-table")) (tr (td "f64") (td "Double precision IEEE floating point")) "\n" (tr (td "f32") (td "Single precision IEEE floating point")) "\n" (tr (td "s32") (td "Signed 32-bit integer")) "\n" (tr (td "u32") (td "Unsigned 32-bit integer")) "\n" (tr (td "alist") (td "An association list of the form " (tt "((vector-ref . proc) (make-vector . proc) (vector-set! . proc))")))) (p "The following procedures are created:") (table (@ (class "symbol-table")) (tr (td "fill-matrix!") (td)) "\n" (tr (td "ones") (td)) "\n" (tr (td "zeros") (td)) "\n" (tr (td "eye") (td)) "\n" (tr (td "diag") (td)) "\n" (tr (td "linspace") (td)) "\n" (tr (td "logspace") (td)))) (def (sig (syntax "(with-utility-matrices type expr)" (id with-utility-matrices))) (p "As the above macro, except that it creates local bindings for the utility matrix procedures, and evaluates " (tt "EXPR") " with those bindings.")) (def (sig (syntax "(define-matrix-map type)" (id define-matrix-map))) (p "Creates procedure " (tt "MATRIX-MAP:: F * M -> A") " that, given an input matrix " (tt "M") " and procedure " (tt "F") ", returns a new matrix " (tt "A") " such that " (tt "A(i,j) = F(M(i,j))") ". " (tt "TYPE") " is one of the following:") (dl (dt "f64") (dd "Double precision IEEE floating point") (dt "f32") (dd "Single precision IEEE floating point") (dt "s32") (dd "Signed 32-bit integer") (dt "u32") (dd "Unsigned 32-bit integer"))))) (section 2 "Examples") (section 2 "About this egg" (section 3 "Author" (p (int-link "/users/ivan-raikov" "Ivan Raikov"))) (section 3 "Version history" (dl (dt "1.14-1.15") (dd "Added repmat and meshgrid") (dt "1.12") (dd "Updated use of blas") (dt "1.11") (dd "Documentation converted to wiki format") (dt "1.10") (dd "Ported to Chicken 4") (dt "1.9") (dd "Build script updated for better cross-platform compatibility") (dt "1.8") (dd "Added procedure make-matrix-map") (dt "1.7") (dd "Added procedure make-matrix-fold") (dt "1.6") (dd "Added procedure make-matrix-fold-partial") (dt "1.5") (dd "Migrated matrix-fold/map to srfi-4-utils") (dt "1.4") (dd "Added define-matrix-fold") (dt "1.3") (dd "Added define-matrix-map") (dt "1.2") (dd "Bug fix in the definition of make-matrix-zeros") (dt "1.1") (dd "Fixes in the setup file") (dt "1.0") (dd "Initial release"))) (section 3 "License" (pre "Copyright 2007-2014 Ivan Raikov and the Okinawa Institute of Science and Technology.\n\nThis program is free software: you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or (at\nyour option) any later version.\n\nThis program is distributed in the hope that it will be useful, but\nWITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU\nGeneral Public License for more details.\n\nA full copy of the GPL license can be found at\n<http://www.gnu.org/licenses/>."))))