From aa269f14caaa5a5b9502f2493d9c648de260e9d4 Mon Sep 17 00:00:00 2001 From: Joe Groff Date: Sat, 5 Jul 2008 11:24:01 -0700 Subject: [PATCH] Documentation for math.blas --- extra/math/blas/matrices/matrices-docs.factor | 193 ++++++++++++++++++ extra/math/blas/matrices/matrices.factor | 8 +- extra/math/blas/vectors/vectors-docs.factor | 111 ++++++++++ extra/math/blas/vectors/vectors.factor | 36 ++-- 4 files changed, 326 insertions(+), 22 deletions(-) create mode 100644 extra/math/blas/matrices/matrices-docs.factor create mode 100644 extra/math/blas/vectors/vectors-docs.factor diff --git a/extra/math/blas/matrices/matrices-docs.factor b/extra/math/blas/matrices/matrices-docs.factor new file mode 100644 index 0000000000..7ac72af58f --- /dev/null +++ b/extra/math/blas/matrices/matrices-docs.factor @@ -0,0 +1,193 @@ +USING: alien byte-arrays help.markup help.syntax math.blas.vectors sequences ; +IN: math.blas.matrices + +ARTICLE: "math.blas" "Basic Linear Algebra Subroutines (BLAS) interface" +"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:" +{ $subsection float-blas-vector } +{ $subsection double-blas-vector } +{ $subsection float-complex-blas-vector } +{ $subsection double-complex-blas-vector } +"These vector types all follow the " { $link sequence } " protocol. In addition, there are corresponding types for matrix data:" +{ $subsection float-blas-matrix } +{ $subsection double-blas-matrix } +{ $subsection float-complex-blas-matrix } +{ $subsection double-complex-blas-matrix } +"Matrices can be transposed, broken down into sequences of row or column vectors, or sliced into rectangular submatrices:" +{ $subsection Mtranspose } +{ $subsection Mrows } +{ $subsection Mcols } +{ $subsection Msub } +"Scalar-vector and vector-vector operations are available in the " { $vocab-link "math.blas.vectors" } " vocabulary:" +{ $subsection Vnorm } +{ $subsection Vasum } +{ $subsection Viamax } +{ $subsection n*V } +{ $subsection V+ } +{ $subsection V- } +{ $subsection V. } +{ $subsection V.conj } +"Vector-matrix and matrix-matrix operations are available in the " { $vocab-link "math.blas.matrices" } " vocabulary:" +{ $subsection M.V } +{ $subsection V(*) } +{ $subsection V(*)conj } +{ $subsection M. } +{ $subsection n*M } +"The above operations only operate on the BLAS vector and matrix types. You cannot mix element types in a BLAS operation; for example, you can't use " { $link V. } " to take the dot product of a " { $link float-blas-vector } " and " { $link double-blas-vector } "." +$nl +"The low-level BLAS C interface can be accessed directly through the " { $vocab-link "math.blas.cblas" } " vocabulary." ; + +HELP: blas-matrix-base +{ $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:" +{ $list + { { $link float-blas-matrix } } + { { $link double-blas-matrix } } + { { $link float-complex-blas-matrix } } + { { $link double-complex-blas-matrix } } +} +"All of these subclasses share the same tuple layout:" +{ $list + { { $snippet "data" } " contains an alien pointer referencing or byte-array containing a packed, column-major array of float, double, float complex, or double complex values;" } + { { $snippet "ld" } " indicates the distance, in elements, between matrix columns;" } + { { $snippet "rows" } " and " { $snippet "cols" } " indicate the number of significant rows and columns in the matrix;" } + { "and " { $snippet "transpose" } ", if set to a true value, indicates that the matrix should be treated as transposed relative to its in-memory representation." } +} } ; + +{ blas-vector-base blas-matrix-base } related-words + +HELP: float-blas-matrix +{ $class-description "A matrix of single-precision floating-point values. For details on the tuple layout, see " { $link blas-matrix-base } "." } ; +HELP: double-blas-matrix +{ $class-description "A matrix of double-precision floating-point values. For details on the tuple layout, see " { $link blas-matrix-base } "." } ; +HELP: float-complex-blas-matrix +{ $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 } "." } ; +HELP: double-complex-blas-matrix +{ $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 } "." } ; + +{ + float-blas-matrix double-blas-matrix float-complex-blas-matrix double-complex-blas-matrix + float-blas-vector double-blas-vector float-complex-blas-vector double-complex-blas-vector +} related-words + +HELP: Mwidth +{ $values { "matrix" "a BLAS matrix inherited from " { $link blas-matrix-base } } { "width" "The number of columns" } } +{ $description "Returns the number of columns in " { $snippet "matrix" } "." } ; + +HELP: Mheight +{ $values { "matrix" "a BLAS matrix inherited from " { $link blas-matrix-base } } { "width" "The number of columns" } } +{ $description "Returns the number of rows in " { $snippet "matrix" } "." } ; + +{ Mwidth Mheight } related-words + +HELP: n*M.V+n*V-in-place +{ $values { "alpha" "a number" } { "A" "an M-row, N-column BLAS matrix inherited from " { $link blas-matrix-base } } { "x" "an N-element BLAS vector inherited from " { $link blas-vector-base } } { "beta" "a number" } { "y" "an M-element BLAS vector inherited from " { $link blas-vector-base } } } +{ $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." } +{ $side-effects "The memory used by " { $snippet "y" } " is overwritten with the result." } ; + +HELP: n*V(*)V+M-in-place +{ $values { "alpha" "a number" } { "x" "an M-element BLAS vector inherited from " { $link blas-vector-base } } { "y" "an N-element BLAS vector inherited from " { $link blas-vector-base } } { "A" "an M-row, N-column BLAS matrix inherited from " { $link blas-matrix-base } } } +{ $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." } +{ $side-effects "The memory used by " { $snippet "A" } " is overwritten with the result." } ; + +HELP: n*V(*)Vconj+M-in-place +{ $values { "alpha" "a number" } { "x" "an M-element complex BLAS vector inherited from " { $link blas-vector-base } } { "y" "an N-element complex BLAS vector inherited from " { $link blas-vector-base } } { "A" "an M-row, N-column complex BLAS matrix inherited from " { $link blas-matrix-base } } } +{ $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." } +{ $side-effects "The memory used by " { $snippet "A" } " is overwritten with the result." } ; + +HELP: n*M.M+n*M-in-place +{ $values { "alpha" "a number" } { "A" "an M-row, K-column BLAS matrix inherited from " { $link blas-matrix-base } } { "B" "a K-row, N-column BLAS matrix inherited from " { $link blas-matrix-base } } { "beta" "a number" } { "C" "an M-row, N-column BLAS matrix inherited from " { $link blas-matrix-base } } } +{ $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." } ; + +HELP: +{ $values { "rows" "the number of rows the new matrix will have" } { "cols" "the number of columns the new matrix will have" } { "exemplar" "A BLAS vector inherited from " { $link blas-vector-base } " or BLAS matrix inherited from " { $link blas-matrix-base } } } +{ $description "Create a matrix of all zeros with the given dimensions and the same element type as " { $snippet "exemplar" } "." } ; + +{ } related-words + +HELP: n*M.V+n*V +{ $values { "alpha" "a number" } { "A" "an M-row, N-column BLAS matrix inherited from " { $link blas-matrix-base } } { "x" "an N-element BLAS vector inherited from " { $link blas-vector-base } } { "beta" "a number" } { "y" "an M-element BLAS vector inherited from " { $link blas-vector-base } } } +{ $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." } ; + +HELP: n*V(*)V+M +{ $values { "alpha" "a number" } { "x" "an M-element BLAS vector inherited from " { $link blas-vector-base } } { "y" "an N-element BLAS vector inherited from " { $link blas-vector-base } } { "A" "an M-row, N-column BLAS matrix inherited from " { $link blas-matrix-base } } } +{ $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." } ; + +HELP: n*V(*)Vconj+M +{ $values { "alpha" "a number" } { "x" "an M-element complex BLAS vector inherited from " { $link blas-vector-base } } { "y" "an N-element complex BLAS vector inherited from " { $link blas-vector-base } } { "A" "an M-row, N-column complex BLAS matrix inherited from " { $link blas-matrix-base } } } +{ $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." } ; + +HELP: n*M.M+n*M +{ $values { "alpha" "a number" } { "A" "an M-row, K-column BLAS matrix inherited from " { $link blas-matrix-base } } { "B" "a K-row, N-column BLAS matrix inherited from " { $link blas-matrix-base } } { "beta" "a number" } { "C" "an M-row, N-column BLAS matrix inherited from " { $link blas-matrix-base } } } +{ $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." } ; + +HELP: n*M.V +{ $values { "alpha" "a number" } { "A" "an M-row, N-column BLAS matrix inherited from " { $link blas-matrix-base } } { "x" "an N-element BLAS vector inherited from " { $link blas-vector-base } } } +{ $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." } ; + +HELP: M.V +{ $values { "A" "an M-row, N-column BLAS matrix inherited from " { $link blas-matrix-base } } { "x" "an N-element BLAS vector inherited from " { $link blas-vector-base } } } +{ $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." } ; + +{ n*M.V+n*V-in-place n*M.V+n*V n*M.V M.V } related-words + +HELP: n*V(*)V +{ $values { "alpha" "a number" } { "x" "an M-element BLAS vector inherited from " { $link blas-vector-base } } { "y" "an N-element BLAS vector inherited from " { $link blas-vector-base } } } +{ $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." } ; + +HELP: n*V(*)Vconj +{ $values { "alpha" "a number" } { "x" "an M-element BLAS vector inherited from " { $link blas-vector-base } } { "y" "an N-element BLAS vector inherited from " { $link blas-vector-base } } } +{ $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." } ; + +HELP: V(*) +{ $values { "x" "an M-element BLAS vector inherited from " { $link blas-vector-base } } { "y" "an N-element BLAS vector inherited from " { $link blas-vector-base } } } +{ $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." } ; + +HELP: V(*)conj +{ $values { "x" "an M-element BLAS vector inherited from " { $link blas-vector-base } } { "y" "an N-element BLAS vector inherited from " { $link blas-vector-base } } } +{ $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." } ; + +{ n*V(*)V+M-in-place n*V(*)Vconj+M-in-place n*V(*)V+M n*V(*)Vconj+M n*V(*)V n*V(*)Vconj V(*) V(*)conj V. V.conj } related-words + +HELP: n*M.M +{ $values { "alpha" "a number" } { "A" "an M-row, K-column BLAS matrix inherited from " { $link blas-matrix-base } } { "B" "a K-row, N-column BLAS matrix inherited from " { $link blas-matrix-base } } } +{ $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." } ; + +HELP: M. +{ $values { "A" "an M-row, K-column BLAS matrix inherited from " { $link blas-matrix-base } } { "B" "a K-row, N-column BLAS matrix inherited from " { $link blas-matrix-base } } } +{ $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." } ; + +{ n*M.M+n*M-in-place n*M.M+n*M n*M.M M. } related-words + +HELP: Msub +{ $values { "matrix" "A BLAS matrix inheriting from " { $link blas-matrix-base } } { "row" "The topmost row of the slice" } { "col" "The leftmost column of the slice" } { "height" "The height of the slice" } { "width" "The width of the slice" } } +{ $description "Select a rectangular submatrix of " { $snippet "matrix" } " with the given dimensions. The returned submatrix will share the parent matrix's storage." } ; + +HELP: Mrows +{ $values { "matrix" "A BLAS matrix inheriting from " { $link blas-matrix-base } } } +{ $description "Return a sequence of BLAS vectors representing the rows of " { $snippet "matrix" } ". Each vector will share the parent matrix's storage." } ; + +HELP: Mcols +{ $values { "matrix" "A BLAS matrix inheriting from " { $link blas-matrix-base } } } +{ $description "Return a sequence of BLAS vectors representing the columns of " { $snippet "matrix" } ". Each vector will share the parent matrix's storage." } ; + +HELP: n*M-in-place +{ $values { "n" "a number" } { "A" "A BLAS matrix inheriting from " { $link blas-matrix-base } } } +{ $description "Calculate the scalar-matrix product " { $snippet "nA" } " and overwrite the current contents of A with the result." } +{ $side-effects "The memory used by " { $snippet "A" } " is overwritten with the result." } ; + +HELP: n*M +{ $values { "n" "a number" } { "A" "A BLAS matrix inheriting from " { $link blas-matrix-base } } } +{ $description "Calculate the scalar-matrix product " { $snippet "nA" } " and return a freshly allocated matrix with the same dimensions as " { $snippet "A" } " containing the result." } ; + +HELP: M*n +{ $values { "A" "A BLAS matrix inheriting from " { $link blas-matrix-base } } { "n" "a number" } } +{ $description "Calculate the scalar-matrix product " { $snippet "nA" } " and return a freshly allocated matrix with the same dimensions as " { $snippet "A" } " containing the result." } ; + +HELP: M/n +{ $values { "A" "A BLAS matrix inheriting from " { $link blas-matrix-base } } { "n" "a number" } } +{ $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." } ; + +{ n*M-in-place n*M M*n M/n } related-words + +HELP: Mtranspose +{ $values { "matrix" "A BLAS matrix inheriting from " { $link blas-matrix-base } } } +{ $description "Returns the transpose of " { $snippet "matrix" } ". The returned matrix shares storage with the original matrix." } ; diff --git a/extra/math/blas/matrices/matrices.factor b/extra/math/blas/matrices/matrices.factor index aa172c954b..965eda813d 100644 --- a/extra/math/blas/matrices/matrices.factor +++ b/extra/math/blas/matrices/matrices.factor @@ -200,7 +200,7 @@ syntax:M: blas-matrix-base clone ] keep (blas-matrix-like) ; ! XXX try rounding stride to next 128 bit bound for better vectorizin' -: empty-matrix ( rows cols exemplar -- matrix ) +: ( rows cols exemplar -- matrix ) [ element-type [ * ] dip ] [ 2drop ] [ f swap (blas-matrix-like) ] 3tri ; @@ -222,10 +222,10 @@ syntax:M: blas-matrix-base clone 1.0 -rot n*M.V ; inline : n*V(*)V ( n x y -- n*x(*)y ) - 2dup [ length>> ] bi@ pick empty-matrix + 2dup [ length>> ] bi@ pick n*V(*)V+M-in-place ; : n*V(*)Vconj ( n x y -- n*x(*)yconj ) - 2dup [ length>> ] bi@ pick empty-matrix + 2dup [ length>> ] bi@ pick n*V(*)Vconj+M-in-place ; : V(*) ( x y -- x(*)y ) @@ -234,7 +234,7 @@ syntax:M: blas-matrix-base clone 1.0 -rot n*V(*)Vconj ; inline : n*M.M ( n A B -- n*A.B ) - 2dup [ Mheight ] [ Mwidth ] bi* pick empty-matrix + 2dup [ Mheight ] [ Mwidth ] bi* pick 1.0 swap n*M.M+n*M-in-place ; : M. ( A B -- A.B ) diff --git a/extra/math/blas/vectors/vectors-docs.factor b/extra/math/blas/vectors/vectors-docs.factor new file mode 100644 index 0000000000..9ebfd40d1c --- /dev/null +++ b/extra/math/blas/vectors/vectors-docs.factor @@ -0,0 +1,111 @@ +USING: alien byte-arrays help.markup help.syntax sequences ; +IN: math.blas.vectors + +HELP: blas-vector-base +{ $class-description "The base class for all BLAS vector types. Objects of this type should not be created directly; instead, instantiate one of the typed subclasses:" +{ $list + { { $link float-blas-vector } } + { { $link double-blas-vector } } + { { $link float-complex-blas-vector } } + { { $link double-complex-blas-vector } } +} +"All of these subclasses share the same tuple layout:" +{ $list + { { $snippet "data" } " contains an alien pointer referencing or byte-array containing a packed array of float, double, float complex, or double complex values;" } + { { $snippet "length" } " indicates the length of the vector;" } + { "and " { $snippet "inc" } " indicates the distance, in elements, between elements." } +} } ; + +HELP: float-blas-vector +{ $class-description "A vector of single-precision floating-point values. For details on the tuple layout, see " { $link blas-vector-base } "." } ; +HELP: double-blas-vector +{ $class-description "A vector of double-precision floating-point values. For details on the tuple layout, see " { $link blas-vector-base } "." } ; +HELP: float-complex-blas-vector +{ $class-description "A vector 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 } "." } ; +HELP: double-complex-blas-vector +{ $class-description "A vector 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 } "." } ; + +HELP: n*V+V-in-place +{ $values { "alpha" "a number" } { "x" "a BLAS vector inheriting from " { $link blas-vector-base } } { "y" "a BLAS vector inheriting from " { $link blas-vector-base } } } +{ $description "Calculate the vector sum " { $snippet "αx + y" } " and replace the existing contents of y with the result. Corresponds to the xAXPY routines in BLAS." } +{ $side-effects "The memory used by y is overwritten with the result." } ; + +HELP: n*V-in-place +{ $values { "alpha" "a number" } { "x" "a BLAS vector inheriting from " { $link blas-vector-base } } } +{ $description "Calculate the scalar-vector product " { $snippet "αx" } " and replace the existing contents of x with the result. Corresponds to the xSCAL routines in BLAS." } +{ $side-effects "The memory used by x is overwritten with the result." } ; + +HELP: V. +{ $values { "x" "a BLAS vector inheriting from " { $link blas-vector-base } } { "y" "a BLAS vector inheriting from " { $link blas-vector-base } } } +{ $description "Calculate the inner product " { $snippet "x⋅y" } ". Corresponds to the xDOT and xDOTU routines in BLAS." } ; + +HELP: V.conj +{ $values { "x" "a complex BLAS vector inheriting from " { $link blas-vector-base } } { "y" "a complex BLAS vector inheriting from " { $link blas-vector-base } } } +{ $description "Calculate the conjugate inner product " { $snippet "x̅⋅y" } ". Corresponds to the xDOTC routines in BLAS." } ; + +HELP: Vnorm +{ $values { "x" "a BLAS vector inheriting from " { $link blas-vector-base } } } +{ $description "Calculate the norm-2, i.e., the magnitude or absolute value, of " { $snippet "x" } " (" { $snippet "‖x‖₂" } "). Corresponds to the xNRM2 routines in BLAS." } ; + +HELP: Vasum +{ $values { "x" "a BLAS vector inheriting from " { $link blas-vector-base } } } +{ $description "Calculate the sum of the norm-1s of the elements of " { $snippet "x" } " (" { $snippet "Σ ‖xᵢ‖₁" } "). Corresponds to the xASUM routines in BLAS." } ; + +HELP: Vswap +{ $values { "x" "a BLAS vector inheriting from " { $link blas-vector-base } } { "y" "a BLAS vector inheriting from " { $link blas-vector-base } } } +{ $description "Swap the contents of " { $snippet "x" } " and " { $snippet "y" } " in place. Corresponds to the xSWAP routines in BLAS." } +{ $side-effects "The memory contents of the two vectors are exchanged." } ; + +HELP: Viamax +{ $values { "x" "a BLAS vector inheriting from " { $link blas-vector-base } } } +{ $description "Return the index of the element in " { $snippet "x" } " with the largest norm-1. If more than one element has the same norm-1, returns the smallest index. Corresponds to the IxAMAX routines in BLAS." } ; + +HELP: Vamax +{ $values { "x" "a BLAS vector inheriting from " { $link blas-vector-base } } } +{ $description "Return the value of the element in " { $snippet "x" } " with the largest norm-1. If more than one element has the same norm-1, returns the first element. Corresponds to the IxAMAX routines in BLAS." } ; + +{ Viamax Vamax } related-words + +HELP: element-type +{ $values { "v" "a BLAS vector inheriting from " { $link blas-vector-base } ", or a BLAS matrix inheriting from " { $link blas-matrix-base } } } +{ $description "Return the C type of the elements in the given BLAS vector or matrix." } ; + +HELP: +{ $values { "exemplar" "a BLAS vector inheriting from " { $link blas-vector-base } " } } +{ $description "Return a vector of zeros with the same length and element type as " { $snippet "v" } ". The vector is constructed with an " { $snippet "inc" } " of zero, so it is not suitable for receiving results from BLAS functions; it is intended to be used as a term in other vector calculations. To construct an empty vector that can be used to receive results, see " { $link } "." } ; + +HELP: +{ $values { "length" "The length of the new vector" } { "exemplar" "a BLAS vector inheriting from " { $link blas-vector-base } " } } +{ $description "Return a vector of zeros with the given length and the same element type as " { $snippet "v" } "." } ; + +HELP: n*V+V +{ $values { "alpha" "a number" } { "x" "a BLAS vector inheriting from " { $link blas-vector-base } } { "y" "a BLAS vector inheriting from " { $link blas-vector-base } } } +{ $description "Calculate the vector sum " { $snippet "αx + y" } " and return a freshly-allocated vector with the same length as " { $snippet "x" } " and " { $snippet "y" } " containing the result. Corresponds to the xAXPY routines in BLAS." } ; + +HELP: n*V +{ $values { "alpha" "a number" } { "x" "a BLAS vector inheriting from " { $link blas-vector-base } } } +{ $description "Calculate the scalar-vector product " { $snippet "αx" } " and return a freshly-allocated vector with the same length as " { $snippet "x" } " containing the result. Corresponds to the xSCAL routines in BLAS." } ; + +HELP: V+ +{ $values { "x" "a BLAS vector inheriting from " { $link blas-vector-base } } { "y" "a BLAS vector inheriting from " { $link blas-vector-base } } } +{ $description "Calculate the vector sum " { $snippet "x + y" } " and return a freshly-allocated vector with the same length as " { $snippet "x" } " and " { $snippet "y" } " containing the result. Corresponds to the xAXPY routines in BLAS." } ; + +HELP: V- +{ $values { "x" "a BLAS vector inheriting from " { $link blas-vector-base } } { "y" "a BLAS vector inheriting from " { $link blas-vector-base } } } +{ $description "Calculate the vector difference " { $snippet "x – y" } " and return a freshly-allocated vector with the same length as " { $snippet "x" } " and " { $snippet "y" } " containing the result. Corresponds to the xAXPY routines in BLAS." } ; + +HELP: Vneg +{ $values { "x" "a BLAS vector inheriting from " { $link blas-vector-base } } { "y" "a BLAS vector inheriting from " { $link blas-vector-base } } } +{ $description "Negate the elements of " { $snippet "x" } " and return a freshly-allocated vector with the same length as " { $snippet "x" } " and " { $snippet "y" } " containing the result." } ; + +HELP: V*n +{ $values { "x" "a BLAS vector inheriting from " { $link blas-vector-base } } { "alpha" "a number" } } +{ $description "Calculate the scalar-vector product " { $snippet "αx" } " and return a freshly-allocated vector with the same length as " { $snippet "x" } " containing the result. Corresponds to the xSCAL routines in BLAS." } ; + +HELP: V/n +{ $values { "x" "a BLAS vector inheriting from " { $link blas-vector-base } } { "alpha" "a number" } } +{ $description "Calculate the scalar-vector product " { $snippet "(1/α)x" } " and return a freshly-allocated vector with the same length as " { $snippet "x" } " containing the result. Corresponds to the xSCAL routines in BLAS." } ; + +{ n*V+V-in-place n*V-in-place n*V+V n*V V+ V- Vneg V*n V/n } related-words + + diff --git a/extra/math/blas/vectors/vectors.factor b/extra/math/blas/vectors/vectors.factor index 3da95f3079..b8b8283781 100644 --- a/extra/math/blas/vectors/vectors.factor +++ b/extra/math/blas/vectors/vectors.factor @@ -21,16 +21,16 @@ C: double-blas-vector C: float-complex-blas-vector C: double-complex-blas-vector -GENERIC: n*V+V-in-place ( n v1 v2 -- v2=n*v1+v2 ) -GENERIC: n*V-in-place ( n v -- v=n*v ) +GENERIC: n*V+V-in-place ( alpha x y -- y=alpha*x+y ) +GENERIC: n*V-in-place ( alpha x -- x=alpha*x ) -GENERIC: V. ( v1 v2 -- v1.v2 ) -GENERIC: V.conj ( v1 v2 -- v1^H.v2 ) -GENERIC: Vnorm ( v -- norm ) -GENERIC: Vasum ( v -- abs-sum ) -GENERIC: Vswap ( v1 v2 -- v1=v2 v2=v1 ) +GENERIC: V. ( x y -- x.y ) +GENERIC: V.conj ( x y -- xconj.y ) +GENERIC: Vnorm ( x -- norm2(x) ) +GENERIC: Vasum ( x -- sum(norm1(x[i])) +GENERIC: Vswap ( x y -- x=y y=x ) -GENERIC: Viamax ( v -- abs-max-index ) +GENERIC: Viamax ( x -- i-where-x[i]=max(norm1(x[i])) ) GENERIC: element-type ( v -- type ) @@ -130,12 +130,12 @@ MACRO: (set-complex-nth) ( set-nth-quot -- ) PRIVATE> -: zero-vector ( exemplar -- zero ) +: ( exemplar -- zero ) [ element-type ] [ length>> 0 ] [ (blas-vector-like) ] tri ; -: empty-vector ( length exemplar -- empty-vector ) +: ( length exemplar -- ) [ element-type ] [ 1 swap ] 2bi (blas-vector-like) ; @@ -224,20 +224,20 @@ METHOD: n*V-in-place { number double-complex-blas-vector } [ (>z-complex) ] dip (prepare-scal) [ cblas_zscal ] dip ; -: n*V+V ( n v1 v2 -- n*v1+v2 ) clone n*V+V-in-place ; inline -: n*V ( n v1 -- n*v1 ) clone n*V-in-place ; inline +: n*V+V ( alpha x y -- alpha*x+y ) clone n*V+V-in-place ; inline +: n*V ( alpha x -- alpha*x ) clone n*V-in-place ; inline -: V+ ( v1 v2 -- v1+v2 ) +: V+ ( x y -- x+y ) 1.0 -rot n*V+V ; inline -: V- ( v1 v2 -- v1-v2 ) +: V- ( x y -- x-y ) -1.0 spin n*V+V ; inline -: Vneg ( v1 -- -v1 ) - [ zero-vector ] keep V- ; inline +: Vneg ( x -- -x ) + -1.0 swap n*V ; inline -: V*n ( v n -- v*n ) +: V*n ( x alpha -- x*alpha ) swap n*V ; inline -: V/n ( v n -- v*n ) +: V/n ( x alpha -- x/alpha ) recip swap n*V ; inline METHOD: V. { float-blas-vector float-blas-vector }