extra/math/blas/matrices/matrices-docs.factor

   1 USING: alien byte-arrays help.markup help.syntax math math.blas.vectors sequences strings ;
   2 IN: math.blas.matrices
   3
   4 ARTICLE: "math.blas-summary" "Basic Linear Algebra Subroutines (BLAS) interface"
   5 "Factor provides an interface to high-performance vector and matrix math routines available in the system's BLAS library. A set of specialized types are provided for handling packed, unboxed vector data:"
   6 { $subsection "math.blas-types" }
   7 "Scalar-vector and vector-vector operations are available in the " { $vocab-link "math.blas.vectors" } " vocabulary:"
   8 { $subsection "math.blas.vectors" }
   9 "Vector-matrix and matrix-matrix operations are available in the " { $vocab-link "math.blas.matrices" } " vocabulary:"
  10 { $subsection "math.blas.matrices" }
  11 "The low-level BLAS C interface can be accessed directly through the " { $vocab-link "math.blas.cblas" } " vocabulary." ;
  12
  13 ARTICLE: "math.blas-types" "BLAS interface types"
  14 "BLAS vectors come in single- and double-precision, real and complex flavors:"
  15 { $subsection float-blas-vector }
  16 { $subsection double-blas-vector }
  17 { $subsection float-complex-blas-vector }
  18 { $subsection double-complex-blas-vector }
  19 "These vector types all follow the " { $link sequence } " protocol. In addition, there are corresponding types for matrix data:"
  20 { $subsection float-blas-matrix }
  21 { $subsection double-blas-matrix }
  22 { $subsection float-complex-blas-matrix }
  23 { $subsection double-complex-blas-matrix }
  24 "Syntax words are provided for constructing literal vectors and matrices in the " { $vocab-link "math.blas.syntax" } " vocabulary:"
  25 { $subsection "math.blas.syntax" }
  26 "There are BOA constructors for all vector and matrix types, which provide the most flexibility in specifying memory layout:"
  27 { $subsection <float-blas-vector> }
  28 { $subsection <double-blas-vector> }
  29 { $subsection <float-complex-blas-vector> }
  30 { $subsection <double-complex-blas-vector> }
  31 { $subsection <float-blas-matrix> }
  32 { $subsection <double-blas-matrix> }
  33 { $subsection <float-complex-blas-matrix> }
  34 { $subsection <double-complex-blas-matrix> }
  35 "For the simple case of creating a dense, zero-filled vector or matrix, simple empty object constructors are provided:"
  36 { $subsection <empty-vector> }
  37 { $subsection <empty-matrix> }
  38 "BLAS vectors and matrices can also be constructed from other Factor sequences:"
  39 { $subsection >float-blas-vector }
  40 { $subsection >double-blas-vector }
  41 { $subsection >float-complex-blas-vector }
  42 { $subsection >double-complex-blas-vector }
  43 { $subsection >float-blas-matrix }
  44 { $subsection >double-blas-matrix }
  45 { $subsection >float-complex-blas-matrix }
  46 { $subsection >double-complex-blas-matrix } ;
  47
  48 ARTICLE: "math.blas.matrices" "BLAS interface matrix operations"
  49 "Transposing and slicing matrices:"
  50 { $subsection Mtranspose }
  51 { $subsection Mrows }
  52 { $subsection Mcols }
  53 { $subsection Msub }
  54 "Matrix-vector products:"
  55 { $subsection n*M.V+n*V! }
  56 { $subsection n*M.V+n*V }
  57 { $subsection n*M.V }
  58 { $subsection M.V }
  59 "Vector outer products:"
  60 { $subsection n*V(*)V+M! }
  61 { $subsection n*V(*)Vconj+M! }
  62 { $subsection n*V(*)V+M }
  63 { $subsection n*V(*)Vconj+M }
  64 { $subsection n*V(*)V }
  65 { $subsection n*V(*)Vconj }
  66 { $subsection V(*) }
  67 { $subsection V(*)conj }
  68 "Matrix products:"
  69 { $subsection n*M.M+n*M! }
  70 { $subsection n*M.M+n*M }
  71 { $subsection n*M.M }
  72 { $subsection M. }
  73 "Scalar-matrix products:"
  74 { $subsection n*M! }
  75 { $subsection n*M }
  76 { $subsection M*n }
  77 { $subsection M/n } ;
  78
  79 ABOUT: "math.blas.matrices"
  80
  81 HELP: blas-matrix-base
  82 { $class-description "The base class for all BLAS matrix types. Objects of this type should not be created directly; instead, instantiate one of the typed subclasses:"
  83 { $list
  84     { { $link float-blas-matrix } }
  85     { { $link double-blas-matrix } }
  86     { { $link float-complex-blas-matrix } }
  87     { { $link double-complex-blas-matrix } }
  88 }
  89 "All of these subclasses share the same tuple layout:"
  90 { $list
  91     { { $snippet "underlying" } " contains an alien pointer referencing or byte-array containing a packed, column-major array of float, double, float complex, or double complex values;" }
  92     { { $snippet "ld" } " indicates the distance, in elements, between matrix columns;" }
  93     { { $snippet "rows" } " and " { $snippet "cols" } " indicate the number of significant rows and columns in the matrix;" }
  94     { "and " { $snippet "transpose" } ", if set to a true value, indicates that the matrix should be treated as transposed relative to its in-memory representation." }
  95 } } ;
  96
  97 { blas-vector-base blas-matrix-base } related-words
  98
  99 HELP: float-blas-matrix
 100 { $class-description "A matrix of single-precision floating-point values. For details on the tuple layout, see " { $link blas-matrix-base } "." } ;
 101 HELP: double-blas-matrix
 102 { $class-description "A matrix of double-precision floating-point values. For details on the tuple layout, see " { $link blas-matrix-base } "." } ;
 103 HELP: float-complex-blas-matrix
 104 { $class-description "A matrix of single-precision floating-point complex values. Complex values are stored in memory as two consecutive float values, real part then imaginary part. For details on the tuple layout, see " { $link blas-matrix-base } "." } ;
 105 HELP: double-complex-blas-matrix
 106 { $class-description "A matrix of double-precision floating-point complex values. Complex values are stored in memory as two consecutive float values, real part then imaginary part. For details on the tuple layout, see " { $link blas-matrix-base } "." } ;
 107
 108 {
 109     float-blas-matrix double-blas-matrix float-complex-blas-matrix double-complex-blas-matrix
 110     float-blas-vector double-blas-vector float-complex-blas-vector double-complex-blas-vector
 111 } related-words
 112
 113 HELP: Mwidth
 114 { $values { "matrix" blas-matrix-base } { "width" integer } }
 115 { $description "Returns the number of columns in " { $snippet "matrix" } "." } ;
 116
 117 HELP: Mheight
 118 { $values { "matrix" blas-matrix-base } { "height" integer } }
 119 { $description "Returns the number of rows in " { $snippet "matrix" } "." } ;
 120
 121 { Mwidth Mheight } related-words
 122
 123 HELP: n*M.V+n*V!
 124 { $values { "alpha" number } { "A" blas-matrix-base } { "x" blas-vector-base } { "beta" number } { "y" blas-vector-base } { "y=alpha*A.x+b*y" blas-vector-base } }
 125 { $description "Calculate the matrix-vector product " { $snippet "αAx + βy" } ", and overwrite the current contents of " { $snippet "y" } " with the result. The width of " { $snippet "A" } " must match the length of " { $snippet "x" } ", and the height must match the length of " { $snippet "y" } ". Corresponds to the xGEMV routines in BLAS." }
 126 { $side-effects "y" } ;
 127
 128 HELP: n*V(*)V+M!
 129 { $values { "alpha" number } { "x" blas-vector-base } { "y" blas-vector-base } { "A" blas-matrix-base } { "A=alpha*x(*)y+A" blas-matrix-base } }
 130 { $description "Calculate the outer product " { $snippet "αx⊗y + A" } " and overwrite the current contents of A with the result. The width of " { $snippet "A" } " must match the length of " { $snippet "y" } ", and its height must match the length of " { $snippet "x" } ". Corresponds to the xGER and xGERU routines in BLAS." }
 131 { $side-effects "A" } ;
 132
 133 HELP: n*V(*)Vconj+M!
 134 { $values { "alpha" number } { "x" blas-vector-base } { "y" blas-vector-base } { "A" blas-matrix-base } { "A=alpha*x(*)yconj+A" blas-matrix-base } }
 135 { $description "Calculate the conjugate outer product " { $snippet "αx⊗y̅ + A" } " and overwrite the current contents of A with the result. The width of " { $snippet "A" } " must match the length of " { $snippet "y" } ", and its height must match the length of " { $snippet "x" } ". Corresponds to the xGERC routines in BLAS." }
 136 { $side-effects "A" } ;
 137
 138 HELP: n*M.M+n*M!
 139 { $values { "alpha" number } { "A" blas-matrix-base } { "B" blas-matrix-base } { "beta" number } { "C" blas-matrix-base } { "C=alpha*A.B+beta*C" blas-matrix-base } }
 140 { $description "Calculate the matrix product " { $snippet "αAB + βC" } " and overwrite the current contents of C with the result. The width of " { $snippet "A" } " and the height of " { $snippet "B" } " must match, as must the heights of " { $snippet "A" } " and " { $snippet "C" } ", and the widths of " { $snippet "B" } " and " { $snippet "C" } ". Corresponds to the xGEMM routines in BLAS." }
 141 { $side-effects "C" } ;
 142
 143 HELP: <empty-matrix>
 144 { $values { "rows" integer } { "cols" integer } { "exemplar" blas-vector-base blas-matrix-base } { "matrix" blas-matrix-base } }
 145 { $description "Create a matrix of all zeros with the given dimensions and the same element type as " { $snippet "exemplar" } "." } ;
 146
 147 { <zero-vector> <empty-vector> <empty-matrix> } related-words
 148
 149 HELP: n*M.V+n*V
 150 { $values { "alpha" number } { "A" blas-matrix-base } { "x" blas-vector-base } { "beta" number } { "y" blas-vector-base } { "alpha*A.x+b*y" blas-vector-base } }
 151 { $description "Calculate the matrix-vector product " { $snippet "αAx + βy" } " and return a freshly allocated vector containing the result. The width of " { $snippet "A" } " must match the length of " { $snippet "x" } ", and the height must match the length of " { $snippet "y" } ". The returned vector will have the same length as " { $snippet "y" } ". Corresponds to the xGEMV routines in BLAS." } ;
 152
 153 HELP: n*V(*)V+M
 154 { $values { "alpha" number } { "x" blas-vector-base } { "y" blas-vector-base } { "A" blas-matrix-base } { "alpha*x(*)y+A" blas-matrix-base } }
 155 { $description "Calculate the outer product " { $snippet "αx⊗y + A" } " and return a freshly allocated matrix containing the result. The width of " { $snippet "A" } " must match the length of " { $snippet "y" } ", and its height must match the length of " { $snippet "x" } ". The returned matrix will have the same dimensions as " { $snippet "A" } ". Corresponds to the xGER and xGERU routines in BLAS." } ;
 156
 157 HELP: n*V(*)Vconj+M
 158 { $values { "alpha" number } { "x" blas-vector-base } { "y" blas-vector-base } { "A" blas-matrix-base } { "alpha*x(*)yconj+A" blas-matrix-base } }
 159 { $description "Calculate the conjugate outer product " { $snippet "αx⊗y̅ + A" } " and return a freshly allocated matrix containing the result. The width of " { $snippet "A" } " must match the length of " { $snippet "y" } ", and its height must match the length of " { $snippet "x" } ". The returned matrix will have the same dimensions as " { $snippet "A" } ". Corresponds to the xGERC routines in BLAS." } ;
 160
 161 HELP: n*M.M+n*M
 162 { $values { "alpha" number } { "A" blas-matrix-base } { "B" blas-matrix-base } { "beta" number } { "C" blas-matrix-base } { "alpha*A.B+beta*C" blas-matrix-base } }
 163 { $description "Calculate the matrix product " { $snippet "αAB + βC" } " and overwrite the current contents of C with the result. The width of " { $snippet "A" } " and the height of " { $snippet "B" } " must match, as must the heights of " { $snippet "A" } " and " { $snippet "C" } ", and the widths of " { $snippet "B" } " and " { $snippet "C" } ". Corresponds to the xGEMM routines in BLAS." } ;
 164
 165 HELP: n*M.V
 166 { $values { "alpha" number } { "A" blas-matrix-base } { "x" blas-vector-base } { "alpha*A.x" blas-vector-base } }
 167 { $description "Calculate the matrix-vector product " { $snippet "αAx" } " and return a freshly allocated vector containing the result. The width of " { $snippet "A" } " must match the length of " { $snippet "x" } ". The length of the returned vector will match the height of " { $snippet "A" } ". Corresponds to the xGEMV routines in BLAS." } ;
 168
 169 HELP: M.V
 170 { $values { "A" blas-matrix-base } { "x" blas-vector-base } { "A.x" blas-vector-base } }
 171 { $description "Calculate the matrix-vector product " { $snippet "Ax" } " and return a freshly allocated vector containing the result. The width of " { $snippet "A" } " must match the length of " { $snippet "x" } ". The length of the returned vector will match the height of " { $snippet "A" } ". Corresponds to the xGEMV routines in BLAS." } ;
 172
 173 { n*M.V+n*V! n*M.V+n*V n*M.V M.V } related-words
 174
 175 HELP: n*V(*)V
 176 { $values { "alpha" number } { "x" blas-vector-base } { "y" blas-vector-base } { "alpha*x(*)y" blas-matrix-base } }
 177 { $description "Calculate the outer product " { $snippet "αx⊗y" } " and return a freshly allocated matrix containing the result. The returned matrix's height will match the length of " { $snippet "x" } ", and its width will match the length of " { $snippet "y" } ". Corresponds to the xGER and xGERU routines in BLAS." } ;
 178
 179 HELP: n*V(*)Vconj
 180 { $values { "alpha" number } { "x" blas-vector-base } { "y" blas-vector-base } { "alpha*x(*)yconj" blas-matrix-base } }
 181 { $description "Calculate the outer product " { $snippet "αx⊗y̅" } " and return a freshly allocated matrix containing the result. The returned matrix's height will match the length of " { $snippet "x" } ", and its width will match the length of " { $snippet "y" } ". Corresponds to the xGERC routines in BLAS." } ;
 182
 183 HELP: V(*)
 184 { $values { "x" blas-vector-base } { "y" blas-vector-base } { "x(*)y" blas-matrix-base } }
 185 { $description "Calculate the outer product " { $snippet "x⊗y" } " and return a freshly allocated matrix containing the result. The returned matrix's height will match the length of " { $snippet "x" } ", and its width will match the length of " { $snippet "y" } ". Corresponds to the xGER and xGERU routines in BLAS." } ;
 186
 187 HELP: V(*)conj
 188 { $values { "x" blas-vector-base } { "y" blas-vector-base } { "x(*)yconj" blas-matrix-base } }
 189 { $description "Calculate the conjugate outer product " { $snippet "x⊗y̅" } " and return a freshly allocated matrix containing the result. The returned matrix's height will match the length of " { $snippet "x" } ", and its width will match the length of " { $snippet "y" } ". Corresponds to the xGERC routines in BLAS." } ;
 190
 191 { n*V(*)V+M! n*V(*)Vconj+M! n*V(*)V+M n*V(*)Vconj+M n*V(*)V n*V(*)Vconj V(*) V(*)conj V. V.conj } related-words
 192
 193 HELP: n*M.M
 194 { $values { "alpha" number } { "A" blas-matrix-base } { "B" blas-matrix-base } { "alpha*A.B" blas-matrix-base } }
 195 { $description "Calculate the matrix product " { $snippet "αAB" } " and return a freshly allocated matrix containing the result. The width of " { $snippet "A" } " and the height of " { $snippet "B" } " must match. The returned matrix's height will be the same as " { $snippet "A" } "'s, and its width will match " { $snippet "B" } "'s. Corresponds to the xGEMM routines in BLAS." } ;
 196
 197 HELP: M.
 198 { $values { "A" blas-matrix-base } { "B" blas-matrix-base } { "A.B" blas-matrix-base } }
 199 { $description "Calculate the matrix product " { $snippet "AB" } " and return a freshly allocated matrix containing the result. The width of " { $snippet "A" } " and the height of " { $snippet "B" } " must match. The returned matrix's height will be the same as " { $snippet "A" } "'s, and its width will match " { $snippet "B" } "'s. Corresponds to the xGEMM routines in BLAS." } ;
 200
 201 { n*M.M+n*M! n*M.M+n*M n*M.M M. } related-words
 202
 203 HELP: Msub
 204 { $values { "matrix" blas-matrix-base } { "row" integer } { "col" integer } { "height" integer } { "width" integer } { "sub" blas-matrix-base } }
 205 { $description "Select a rectangular submatrix of " { $snippet "matrix" } " with the given dimensions. The returned submatrix will share the parent matrix's storage." } ;
 206
 207 HELP: Mrows
 208 { $values { "A" blas-matrix-base } { "rows" sequence } }
 209 { $description "Return a sequence of BLAS vectors representing the rows of " { $snippet "matrix" } ". Each vector will share the parent matrix's storage." } ;
 210
 211 HELP: Mcols
 212 { $values { "A" blas-matrix-base } { "cols" sequence } }
 213 { $description "Return a sequence of BLAS vectors representing the columns of " { $snippet "matrix" } ". Each vector will share the parent matrix's storage." } ;
 214
 215 HELP: n*M!
 216 { $values { "n" number } { "A" blas-matrix-base } { "A=n*A" blas-matrix-base } }
 217 { $description "Calculate the scalar-matrix product " { $snippet "nA" } " and overwrite the current contents of A with the result." }
 218 { $side-effects "A" } ;
 219
 220 HELP: n*M
 221 { $values { "n" number } { "A" blas-matrix-base } { "n*A" blas-matrix-base } }
 222 { $description "Calculate the scalar-matrix product " { $snippet "nA" } " and return a freshly allocated matrix with the same dimensions as " { $snippet "A" } " containing the result." } ;
 223
 224 HELP: M*n
 225 { $values { "A" blas-matrix-base } { "n" number } { "A*n" blas-matrix-base } }
 226 { $description "Calculate the scalar-matrix product " { $snippet "nA" } " and return a freshly allocated matrix with the same dimensions as " { $snippet "A" } " containing the result." } ;
 227
 228 HELP: M/n
 229 { $values { "A" blas-matrix-base } { "n" number } { "A/n" blas-matrix-base } }
 230 { $description "Calculate the scalar-matrix product " { $snippet "(1/n)A" } " and return a freshly allocated matrix with the same dimensions as " { $snippet "A" } " containing the result." } ;
 231
 232 { n*M! n*M M*n M/n } related-words
 233
 234 HELP: Mtranspose
 235 { $values { "matrix" blas-matrix-base } { "matrix^T" blas-matrix-base } }
 236 { $description "Returns the transpose of " { $snippet "matrix" } ". The returned matrix shares storage with the original matrix." } ;
 237
 238 HELP: element-type
 239 { $values { "v" blas-vector-base blas-matrix-base } { "type" string } }
 240 { $description "Return the C type of the elements in the given BLAS vector or matrix." } ;
 241
 242 HELP: <empty-vector>
 243 { $values { "length" "The length of the new vector" } { "exemplar" blas-vector-base blas-matrix-base } { "vector" blas-vector-base } }
 244 { $description "Return a vector of zeros with the given " { $snippet "length" } " and the same element type as " { $snippet "v" } "." } ;
 245