external/clem/doc/clem.sexp

   1 (#.
   2  (cons
   3   :p
   4   (progn
   5     (in-package :clem)
   6     (defparameter smarkup::*document-thesis* nil)
   7     (smarkup::setup-headings)
   8     nil))
   9
  10  (:smarkup-metadata
  11   (:copyright
  12    "Copyright 2006, Cyrus Harmon. All Rights Reserved.")
  13   (:title "clem: A common-lisp matrix package")
  14   (:author "Cyrus L. Harmon")
  15   (:bibtex-database
  16    "(\"asdf:/ch-bib/lisp\" \"asdf:/ch-bib/bio\")")
  17   (:bibtex-style "Science"))
  18  (:html-metadata (:htmlcss "simple.css") )
  19
  20  (:lisp-silent
  21   "(asdf:operate 'asdf:load-op 'clem)"
  22   "(setf smarkup::*baseline-skip* \"14pt\")"
  23   "(setf smarkup::*par-skip* \"0pt\")")
  24
  25  (:span
  26   (:h1 "Abstract")
  27
  28   (:p "CLEM is an open-source Common Lisp library for the
  29  representation and manipulation of matrices. CLEM is designed to
  30  be a flexible and extensible system for the representation of
  31  arbitrary 2-dimensional matrices."))
  32
  33  (:h1 "Introduction")
  34
  35  (:p "The Common Lisp language"
  36      (:bibcite "steele1990common")
  37      " offers a rich, dynamic environment for programming and
  38 data analysis. Common Lisp contains a powerful object system, the
  39 Common Lisp Object System (CLOS)"
  40      (:bibcite "keene1989object")
  41      ", and most modern implementations support a protocol for
  42 the generation not just of new classes and objects, but to extend
  43 the object system itself using the Meta-object Protocol"
  44      (:bibcite "kiczales1991art")
  45      ".")
  46
  47  (:p "CLEM uses CLOS and the Meta-object protocol (MOP) to define a"
  48      (:code "standard-matrix-class")
  49      " that serves as the metaclass for classes that represent
  50 matrices with elements of specific types. The typed matrices can
  51 represent matrices containing values of specific types in the
  52 Common Lisp type system, starting with type "
  53      (:code "t")
  54      " as the most general data type, and becoming more restrictive by using more specific types such"
  55      (:code "double-float")
  56      ", "
  57      (:code "fixnum")
  58      ", or "
  59      (:code "(unsigned-byte 8)")
  60      ". By using the most specific type that can represent the values of a given matrix, the lisp system can optimize for better performance and memory usage requirements. For example, a "
  61      (:code "bit-matrix")
  62      " will use 1 bit per matrix element, rather than 32-bits on 32-bit systems for a "
  63      (:code "t-matrix")
  64      ".")
  65
  66  (:h2 "Matrix Types")
  67
  68  (:h2 "Matrix Representation")
  69
  70  (:p "Common Lisp provides a rich built-in array type which serves as
  71  the storage for CLEM matrices. Given that Common Lisp has built-in
  72  arrays, why do we need CLEM and what value is provided by creating a
  73  set of classses around arrays? First, the Common Lisp arrays have a
  74  limited set of operations defined on them. While there is a built-in
  75  (scalar) addition operator, there is no built-in way to perform an
  76  element-wise addition of two arrays. CLEM addresses these by defining
  77  a set of generic functions that operate on matrices that provide a
  78  number of commonly used matrix operations such as matrix
  79  arithmetic. Second, there is no way to define methods on arrays based
  80  on their element types. Therefore, we define subclasses of matrix
  81  whose underlying arrays are specialized to distinct types. We can
  82  then define methods to operate specifically on these subclasses,
  83  affording the opportunity to treat, say, floating point and integer
  84  matrices differently and to provide declarations to the compiler
  85  based on the array element type, which can, in Common Lisp
  86  implementations with sufficiently smart compilers, lead to much
  87  improved performance.")
  88
  89  (:h1 "Defining CLEM Classes and Making CLEM Instances")
  90
  91  (:h2 "Creating CLEM Instances with make-instance")
  92
  93  (:p "The following code creates a 16-row by 16-column matrix of type"
  94      (:code "double-float-matrix")
  95      " and assigns it to the dynamic variable"
  96      (:code "*m1*")
  97      ".")
  98  (:lisp
  99   "(defparameter *m1*
 100  (make-instance 'clem:double-float-matrix :rows 16 :cols 16))"
 101   "*m1*")
 102
 103  (:p "The default is to only show the first 7 and the last rows
 104  and columns of each matrix. The number of rows and columns can
 105  be changed by setting the "
 106      (:code "*matrix-print-row-limit*")
 107      " and"
 108      (:code "*matrix-print-col-limit*")
 109      " variables.")
 110
 111  (:h2 "standard-matrix-class")
 112  (:h2 "CLEM Matrix Types")
 113
 114  (:h3 "Number matrices")
 115
 116  (:p "The most general class of numerical matrix is the number matrix.")
 117
 118  (:h3 "Integer Matrices")
 119
 120  (:h3 "Floating-point Matrices")
 121
 122  (:h3 "Complex-value Matrices")
 123
 124  (:h1 "Working with CLEM Matrices")
 125
 126  (:h2 "Matrix Dimensions and Values")
 127
 128  (:h2 "Typed matrix operations")
 129
 130  (:h2 "Matrix Copying")
 131
 132  (:h2 "matrix-move")
 133
 134  (:h1 "Matrix Arithmetic")
 135
 136  (:h2 "Matrix Addition and Subtraction")
 137
 138  (:h2 "Matrix Multiplication")
 139
 140  (:h2 "Hadamard Product")
 141
 142  (:h2 "Scalar Arithmetic")
 143
 144  (:h2 "Other Mathematical Functions")
 145
 146  (:p "Discuss mat-log, mat-abs, min, and max.")
 147
 148  (:h1 "Matrix Operations")
 149
 150  (:h2 "Matrix Inversion")
 151
 152  (:h2 "Matrix Normalization")
 153
 154  (:h2 "Discrete Convolution")
 155
 156  (:h3 "Derivatives")
 157
 158  (:h3 "Gradient Magnitude")
 159
 160  (:h3 "Gaussian Blur")
 161
 162  (:h2 "Affine Transformations")
 163
 164  (:h3 "Interpolation")
 165
 166  (:h2 "Morphological Operations")
 167
 168  (:h3 "Dilation and Erosion")
 169
 170  (:h3 "Variance")
 171
 172  (:h3 "Thresholding")
 173
 174  (:h1 "CLEM Implementation Details")
 175
 176  (:h2 "Type-specific matrix functions")
 177
 178  (:p "The general strategy has been to 1) make things work and
 179  then make them work quickly.  To this end, I have been writing
 180  functions for matrix operations in a general manner first and
 181  then recoding type-specific versions to make certain operations
 182  go faster.  This is done via liberal use of macros to generate
 183  type-specific functions and methods for matrix operations that
 184  go much faster than the general versions.")
 185
 186  (:p "The convention is that a generic function such as sum-range
 187  will have a generic version that works with all matrices and
 188  type specific versions thaqt work with specific matrices. g In
 189  order to support these functions there may be internal methods,
 190  prefixed with a %, that implement certain type-specific
 191  functionality.  Macros that generate the code used for the
 192  type-specific methods will be prefixed with a %%.  In theory,
 193  the %%-macros can be called from other code that need to
 194  generate in-place code where the overhead of the method-call to
 195  the %-method would be too expensive. This convention is not yet
 196  widely enforced and certainly untested. Hopefully this situation
 197  will improve.")
 198
 199  (:h2 "Hacking the SBCL compiler to improve performance")
 200
 201  (:bibliography))