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 implementations of the BLAS math library. A set of specialized types are provided for handling packed, unboxed vector data:"
   6 { $subsections "math.blas-types" }
   7 "Scalar-vector and vector-vector operations are available in the " { $vocab-link "math.blas.vectors" } " vocabulary:"
   8 { $subsections "math.blas.vectors" }
   9 "Vector-matrix and matrix-matrix operations are available in the " { $vocab-link "math.blas.matrices" } " vocabulary:"
  10 { $subsections "math.blas.matrices" }
  11 "The low-level BLAS Fortran interface can be accessed directly through the " { $vocab-link "math.blas.ffi" } " vocabulary. The BLAS interface can be configured to use different underlying BLAS implementations:"
  12 { $subsections "math.blas.config" } ;
  13
  14 ARTICLE: "math.blas-types" "BLAS interface types"
  15 "BLAS vectors come in single- and double-precision, real and complex flavors:"
  16 { $subsections
  17     float-blas-vector
  18     double-blas-vector
  19     complex-float-blas-vector
  20     complex-double-blas-vector
  21 }
  22 "These vector types all follow the " { $link sequence } " protocol. In addition, there are corresponding types for matrix data:"
  23 { $subsections
  24     float-blas-matrix
  25     double-blas-matrix
  26     complex-float-blas-matrix
  27     complex-double-blas-matrix
  28 }
  29 "There are BOA constructors for all vector and matrix types, which provide the most flexibility in specifying memory layout:"
  30 { $subsections
  31     <float-blas-vector>
  32     <double-blas-vector>
  33     <complex-float-blas-vector>
  34     <complex-double-blas-vector>
  35     <float-blas-matrix>
  36     <double-blas-matrix>
  37     <complex-float-blas-matrix>
  38     <complex-double-blas-matrix>
  39 }
  40 "For the simple case of creating a dense, zero-filled vector or matrix, simple empty object constructors are provided:"
  41 { $subsections
  42     <empty-vector>
  43     <empty-matrix>
  44 }
  45 "BLAS vectors and matrices can also be constructed from other Factor sequences:"
  46 { $subsections
  47     >float-blas-vector
  48     >double-blas-vector
  49     >complex-float-blas-vector
  50     >complex-double-blas-vector
  51     >float-blas-matrix
  52     >double-blas-matrix
  53     >complex-float-blas-matrix
  54     >complex-double-blas-matrix
  55 } ;
  56
  57 ARTICLE: "math.blas.matrices" "BLAS interface matrix operations"
  58 "Transposing and slicing matrices:"
  59 { $subsections
  60     Mtranspose
  61     Mrows
  62     Mcols
  63     Msub
  64 }
  65 "Matrix-vector products:"
  66 { $subsections
  67     n*M.V+n*V!
  68     n*M.V+n*V
  69     n*M.V
  70     M.V
  71 }
  72 "Vector outer products:"
  73 { $subsections
  74     n*V(*)V+M!
  75     n*V(*)Vconj+M!
  76     n*V(*)V+M
  77     n*V(*)Vconj+M
  78     n*V(*)V
  79     n*V(*)Vconj
  80     V(*)
  81     V(*)conj
  82 }
  83 "Matrix products:"
  84 { $subsections
  85     n*M.M+n*M!
  86     n*M.M+n*M
  87     n*M.M
  88     M.
  89 }
  90 "Scalar-matrix products:"
  91 { $subsections
  92     n*M!
  93     n*M
  94     M*n
  95     M/n
  96 }
  97 "Literal syntax:"
  98 { $subsections
  99     POSTPONE: smatrix{
 100     POSTPONE: dmatrix{
 101     POSTPONE: cmatrix{
 102     POSTPONE: zmatrix{
 103 } ;
 104
 105
 106 ABOUT: "math.blas.matrices"
 107
 108 HELP: blas-matrix-base
 109 { $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:"
 110 { $list
 111     { { $link float-blas-matrix } }
 112     { { $link double-blas-matrix } }
 113     { { $link complex-float-blas-matrix } }
 114     { { $link complex-double-blas-matrix } }
 115 }
 116 "All of these subclasses share the same tuple layout:"
 117 { $list
 118     { { $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;" }
 119     { { $snippet "ld" } " indicates the distance, in elements, between matrix columns;" }
 120     { { $snippet "rows" } " and " { $snippet "cols" } " indicate the number of significant rows and columns in the matrix;" }
 121     { "and " { $snippet "transpose" } ", if set to a true value, indicates that the matrix should be treated as transposed relative to its in-memory representation." }
 122 } } ;
 123
 124 { blas-vector-base blas-matrix-base } related-words
 125
 126 HELP: float-blas-matrix
 127 { $class-description "A matrix of single-precision floating-point values. For details on the tuple layout, see " { $link blas-matrix-base } "." } ;
 128 HELP: double-blas-matrix
 129 { $class-description "A matrix of double-precision floating-point values. For details on the tuple layout, see " { $link blas-matrix-base } "." } ;
 130 HELP: complex-float-blas-matrix
 131 { $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 } "." } ;
 132 HELP: complex-double-blas-matrix
 133 { $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 } "." } ;
 134
 135 {
 136     float-blas-matrix double-blas-matrix complex-float-blas-matrix complex-double-blas-matrix
 137     float-blas-vector double-blas-vector complex-float-blas-vector complex-double-blas-vector
 138 } related-words
 139
 140 HELP: Mwidth
 141 { $values { "matrix" blas-matrix-base } { "width" integer } }
 142 { $description "Returns the number of columns in " { $snippet "matrix" } "." } ;
 143
 144 HELP: Mheight
 145 { $values { "matrix" blas-matrix-base } { "height" integer } }
 146 { $description "Returns the number of rows in " { $snippet "matrix" } "." } ;
 147
 148 { Mwidth Mheight } related-words
 149
 150 HELP: n*M.V+n*V!
 151 { $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 } }
 152 { $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." }
 153 { $side-effects "y" } ;
 154
 155 HELP: n*V(*)V+M!
 156 { $values { "alpha" number } { "x" blas-vector-base } { "y" blas-vector-base } { "A" blas-matrix-base } { "A=alpha*x(*)y+A" blas-matrix-base } }
 157 { $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." }
 158 { $side-effects "A" } ;
 159
 160 HELP: n*V(*)Vconj+M!
 161 { $values { "alpha" number } { "x" blas-vector-base } { "y" blas-vector-base } { "A" blas-matrix-base } { "A=alpha*x(*)yconj+A" blas-matrix-base } }
 162 { $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." }
 163 { $side-effects "A" } ;
 164
 165 HELP: n*M.M+n*M!
 166 { $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 } }
 167 { $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." }
 168 { $side-effects "C" } ;
 169
 170 HELP: <empty-matrix>
 171 { $values { "rows" integer } { "cols" integer } { "exemplar" blas-vector-base blas-matrix-base } { "matrix" blas-matrix-base } }
 172 { $description "Create a matrix of all zeros with the given dimensions and the same element type as " { $snippet "exemplar" } "." } ;
 173
 174 { <zero-vector> <empty-vector> <empty-matrix> } related-words
 175
 176 HELP: n*M.V+n*V
 177 { $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 } }
 178 { $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." } ;
 179
 180 HELP: n*V(*)V+M
 181 { $values { "alpha" number } { "x" blas-vector-base } { "y" blas-vector-base } { "A" blas-matrix-base } { "alpha*x(*)y+A" blas-matrix-base } }
 182 { $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." } ;
 183
 184 HELP: n*V(*)Vconj+M
 185 { $values { "alpha" number } { "x" blas-vector-base } { "y" blas-vector-base } { "A" blas-matrix-base } { "alpha*x(*)yconj+A" blas-matrix-base } }
 186 { $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." } ;
 187
 188 HELP: n*M.M+n*M
 189 { $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 } }
 190 { $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." } ;
 191
 192 HELP: n*M.V
 193 { $values { "alpha" number } { "A" blas-matrix-base } { "x" blas-vector-base } { "alpha*A.x" blas-vector-base } }
 194 { $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." } ;
 195
 196 HELP: M.V
 197 { $values { "A" blas-matrix-base } { "x" blas-vector-base } { "A.x" blas-vector-base } }
 198 { $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." } ;
 199
 200 { n*M.V+n*V! n*M.V+n*V n*M.V M.V } related-words
 201
 202 HELP: n*V(*)V
 203 { $values { "alpha" number } { "x" blas-vector-base } { "y" blas-vector-base } { "alpha*x(*)y" blas-matrix-base } }
 204 { $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." } ;
 205
 206 HELP: n*V(*)Vconj
 207 { $values { "alpha" number } { "x" blas-vector-base } { "y" blas-vector-base } { "alpha*x(*)yconj" blas-matrix-base } }
 208 { $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." } ;
 209
 210 HELP: V(*)
 211 { $values { "x" blas-vector-base } { "y" blas-vector-base } { "x(*)y" blas-matrix-base } }
 212 { $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." } ;
 213
 214 HELP: V(*)conj
 215 { $values { "x" blas-vector-base } { "y" blas-vector-base } { "x(*)yconj" blas-matrix-base } }
 216 { $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." } ;
 217
 218 { 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
 219
 220 HELP: n*M.M
 221 { $values { "alpha" number } { "A" blas-matrix-base } { "B" blas-matrix-base } { "alpha*A.B" blas-matrix-base } }
 222 { $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." } ;
 223
 224 HELP: M.
 225 { $values { "A" blas-matrix-base } { "B" blas-matrix-base } { "A.B" blas-matrix-base } }
 226 { $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." } ;
 227
 228 { n*M.M+n*M! n*M.M+n*M n*M.M M. } related-words
 229
 230 HELP: Msub
 231 { $values { "matrix" blas-matrix-base } { "row" integer } { "col" integer } { "height" integer } { "width" integer } { "sub" blas-matrix-base } }
 232 { $description "Select a rectangular submatrix of " { $snippet "matrix" } " with the given dimensions. The returned submatrix will share the parent matrix's storage." } ;
 233
 234 HELP: Mrows
 235 { $values { "A" blas-matrix-base } { "rows" sequence } }
 236 { $description "Return a sequence of BLAS vectors representing the rows of " { $snippet "matrix" } ". Each vector will share the parent matrix's storage." } ;
 237
 238 HELP: Mcols
 239 { $values { "A" blas-matrix-base } { "cols" sequence } }
 240 { $description "Return a sequence of BLAS vectors representing the columns of " { $snippet "matrix" } ". Each vector will share the parent matrix's storage." } ;
 241
 242 HELP: n*M!
 243 { $values { "n" number } { "A" blas-matrix-base } { "A=n*A" blas-matrix-base } }
 244 { $description "Calculate the scalar-matrix product " { $snippet "nA" } " and overwrite the current contents of A with the result." }
 245 { $side-effects "A" } ;
 246
 247 HELP: n*M
 248 { $values { "n" number } { "A" blas-matrix-base } { "n*A" blas-matrix-base } }
 249 { $description "Calculate the scalar-matrix product " { $snippet "nA" } " and return a freshly allocated matrix with the same dimensions as " { $snippet "A" } " containing the result." } ;
 250
 251 HELP: M*n
 252 { $values { "A" blas-matrix-base } { "n" number } { "A*n" blas-matrix-base } }
 253 { $description "Calculate the scalar-matrix product " { $snippet "nA" } " and return a freshly allocated matrix with the same dimensions as " { $snippet "A" } " containing the result." } ;
 254
 255 HELP: M/n
 256 { $values { "A" blas-matrix-base } { "n" number } { "A/n" blas-matrix-base } }
 257 { $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." } ;
 258
 259 { n*M! n*M M*n M/n } related-words
 260
 261 HELP: Mtranspose
 262 { $values { "matrix" blas-matrix-base } { "matrix^T" blas-matrix-base } }
 263 { $description "Returns the transpose of " { $snippet "matrix" } ". The returned matrix shares storage with the original matrix." } ;
 264
 265 HELP: element-type
 266 { $values { "v" blas-vector-base blas-matrix-base } { "type" string } }
 267 { $description "Return the C type of the elements in the given BLAS vector or matrix." } ;
 268
 269 HELP: <empty-vector>
 270 { $values { "length" "The length of the new vector" } { "exemplar" blas-vector-base blas-matrix-base } { "vector" blas-vector-base } }
 271 { $description "Return a vector of zeros with the given " { $snippet "length" } " and the same element type as " { $snippet "v" } "." } ;
 272
 273 HELP: smatrix{
 274 { $syntax "smatrix{
 275     { 1.0 0.0 0.0 1.0 }
 276     { 0.0 1.0 0.0 2.0 }
 277     { 0.0 0.0 1.0 3.0 }
 278     { 0.0 0.0 0.0 1.0 }
 279 }" }
 280 { $description "Construct a literal " { $link float-blas-matrix } ". Note that although BLAS matrices are stored in column-major order, the literal is specified in row-major order." } ;
 281
 282 HELP: dmatrix{
 283 { $syntax "dmatrix{
 284     { 1.0 0.0 0.0 1.0 }
 285     { 0.0 1.0 0.0 2.0 }
 286     { 0.0 0.0 1.0 3.0 }
 287     { 0.0 0.0 0.0 1.0 }
 288 }" }
 289 { $description "Construct a literal " { $link double-blas-matrix } ". Note that although BLAS matrices are stored in column-major order, the literal is specified in row-major order." } ;
 290
 291 HELP: cmatrix{
 292 { $syntax "cmatrix{
 293     { 1.0 0.0           0.0 1.0           }
 294     { 0.0 C{ 0.0 1.0 }  0.0 2.0           }
 295     { 0.0 0.0          -1.0 3.0           }
 296     { 0.0 0.0           0.0 C{ 0.0 -1.0 } }
 297 }" }
 298 { $description "Construct a literal " { $link complex-float-blas-matrix } ". Note that although BLAS matrices are stored in column-major order, the literal is specified in row-major order." } ;
 299
 300 HELP: zmatrix{
 301 { $syntax "zmatrix{
 302     { 1.0 0.0           0.0 1.0           }
 303     { 0.0 C{ 0.0 1.0 }  0.0 2.0           }
 304     { 0.0 0.0          -1.0 3.0           }
 305     { 0.0 0.0           0.0 C{ 0.0 -1.0 } }
 306 }" }
 307 { $description "Construct a literal " { $link complex-double-blas-matrix } ". Note that although BLAS matrices are stored in column-major order, the literal is specified in row-major order." } ;
 308
 309 {
 310     POSTPONE: smatrix{ POSTPONE: dmatrix{
 311     POSTPONE: cmatrix{ POSTPONE: zmatrix{
 312 } related-words