;; 
;;
;; matrix-utils documentation for the Chicken Scheme module system.
;;

(use eggdoc)

(define doc
  `((eggdoc:begin
     (name "matrix-utils")
     (description "Generation of special utility matrices that are represented as SRFI-4 vectors.")
     (author (url "http://chicken.wiki.br/users/ivan-raikov" "Ivan Raikov"))

     (history 
      (version "1.10" "Ported to Chicken 4")
      (version "1.9" "Build script updated for better cross-platform compatibility")
      (version "1.8" "Added procedure make-matrix-map")
      (version "1.7" "Added procedure make-matrix-fold")
      (version "1.6" "Added procedure make-matrix-fold-partial")
      (version "1.5" "Migrated matrix-fold/map to srfi-4-utils")
      (version "1.4" "Added define-matrix-fold")
      (version "1.3" "Added define-matrix-map")
      (version "1.2" "Bug fix in the definition of make-matrix-zeros")
      (version "1.1" "Fixes in the setup file")
      (version "1.0" "Initial release"))

     (requires (url "blas.html" "blas")
	       (url "srfi-42.html" "srfi-42")
	       (url "srfi-4-comprehensions.html" "srfi-4-comprehensions")
	       (url "syntax-case.html" "syntax-case"))


     (usage "(require-extension matrix-utils)")

     (download "matrix-utils.egg")

     (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 " 
	 (url "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.")
      

      (subsection "Procedures" 
		  (procedure "make-matrix-map:: VECTOR-REF * VECTOR-SET! -> (ORDER * M * N * A * F * [IX * IY * EX * EY] -> A)"
			     (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. "))
;;
		  (procedure "make-matrix-fold:: VECTOR-REF -> (ORDER * M * N * A * F * X0 * [IX * IY * EX * EY] -> A)"
			     (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. "))
;;
		  (procedure "make-matrix-fold-partial:: VECTOR-REF -> (ORDER * M * N * A * F * P * X0 * [IX * IY * EX * EY] -> A)"
			     (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. "))
;;

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

		  (procedure "make-matrix-ones:: MAKE-VECTOR * FILL-MATRIX! -> (M * N [* ORDER] -> A)"
			     (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 "blas:ColMajor") " or " (tt "blas:RowMajor")
				", default is " (tt "blas: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") ". "))

		  (procedure "make-matrix-zeros:: MAKE-VECTOR * FILL-MATRIX! -> (M * N [* ORDER] -> A)"
			     (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 "blas:ColMajor") " or " (tt "blas:RowMajor")
				", default is " (tt "blas: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") ". "))

		  (procedure "make-matrix-eye:: MAKE-VECTOR * FILL-MATRIX! -> (M * N [* ORDER] -> I)"
			     (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 "blas:ColMajor") " or " (tt "blas:RowMajor")
				", default is " (tt "blas: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") ". "))

		  (procedure "make-matrix-diag:: VECTOR-REF * MAKE-VECTOR * FILL-MATRIX! -> (M * N * V [K * ORDER] -> D)"
			     (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 "blas:ColMajor") 
				 " or " (tt "blas:RowMajor") ", default is " (tt "blas: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") ". "))

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

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

      (subsection "Macros"
		  (macro "(define-utility-matrices type)"
		    (p "Creates utility matrix procedures that create matrices of the specified type. "
		       (tt "TYPE") " is one of the following: "
		       (symbol-table 
			(describe "f64" 
				  ("Double precision IEEE floating point"))
			(describe "f32" 
				  ("Single precision IEEE floating point"))
			(describe "s32" 
				  ("Signed 32-bit integer"))
			(describe "u32" 
				  ("Unsigned 32-bit integer"))
			(describe "alist"
				  ("An association list of the form "
				   (tt "((vector-ref . proc) (make-vector . proc) (vector-set! . proc))")))))
		    (p "The following procedures are created: "
		       (symbol-table 
			(describe "fill-matrix!" "")
			(describe "ones" "")
			(describe "zeros" "")
			(describe "eye" "")
			(describe "diag" "")
			(describe "linspace" "")
			(describe "logspace" ""))))
		  
		       
		  (macro "(with-utility-matrices type expr)"
		    (p "As the above macro, except that it creates local bindings for the utility "
		       "matrix procedures, and evaluates " (tt "EXPR") " with those bindings. "))

		  (macro "(define-matrix-map type)"
		    (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: "
		       (symbol-table 
			(describe "f64"  ("Double precision IEEE floating point"))
			(describe "f32"  ("Single precision IEEE floating point"))
			(describe "s32"  ("Signed 32-bit integer"))
			(describe "u32"  ("Unsigned 32-bit integer")))))

		  ))


     (examples)

     (license
"Copyright 2007-2009 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/>."))))


(if (eggdoc->html doc) (void))