From 761fbfeb8f0216925bbf9015d7fb1af93467366f Mon Sep 17 00:00:00 2001 From: Joe Groff Date: Sat, 5 Jul 2008 18:28:53 -0700 Subject: [PATCH] Vsub word for slicing BLAS vectors. Documentation improvements --- extra/math/blas/matrices/matrices-docs.factor | 65 ++++++++++++++----- extra/math/blas/vectors/vectors-docs.factor | 30 ++++++++- extra/math/blas/vectors/vectors-tests.factor | 7 ++ extra/math/blas/vectors/vectors.factor | 12 +++- 4 files changed, 95 insertions(+), 19 deletions(-) diff --git a/extra/math/blas/matrices/matrices-docs.factor b/extra/math/blas/matrices/matrices-docs.factor index 12cc579610..0d9ac69171 100644 --- a/extra/math/blas/matrices/matrices-docs.factor +++ b/extra/math/blas/matrices/matrices-docs.factor @@ -1,8 +1,17 @@ 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" +ARTICLE: "math.blas-summary" "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 "math.blas-types" } +"Scalar-vector and vector-vector operations are available in the " { $vocab-link "math.blas.vectors" } " vocabulary:" +{ $subsection "math.blas.vectors" } +"Vector-matrix and matrix-matrix operations are available in the " { $vocab-link "math.blas.matrices" } " vocabulary:" +{ $subsection "math.blas.matrices" } +"The low-level BLAS C interface can be accessed directly through the " { $vocab-link "math.blas.cblas" } " vocabulary." ; + +ARTICLE: "math.blas-types" "BLAS interface types" +"BLAS vectors come in single- and double-precision, real and complex flavors:" { $subsection float-blas-vector } { $subsection double-blas-vector } { $subsection float-complex-blas-vector } @@ -11,30 +20,54 @@ ARTICLE: "math.blas" "Basic Linear Algebra Subroutines (BLAS) interface" { $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 double-complex-blas-matrix } +"Syntax words are provided for constructing literal vectors and matrices in the " { $vocab-link "math.blas.syntax" } " vocabulary:" +{ $subsection "math.blas.syntax" } +"There are BOA constructors for all vector and matrix types, which provide the most flexibility in specifying memory layout:" +{ $subsection } +{ $subsection } +{ $subsection } +{ $subsection } +{ $subsection } +{ $subsection } +{ $subsection } +{ $subsection } +"For the simple case of creating a dense, zero-filled vector or matrix, simple empty object constructors are provided:" +{ $subsection } +{ $subsection } ; + +ARTICLE: "math.blas.matrices" "BLAS interface matrix operations" +"Transposing and slicing matrices:" { $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:" +"Matrix-vector products:" +{ $subsection n*M.V+n*V-in-place } +{ $subsection n*M.V+n*V } +{ $subsection n*M.V } { $subsection M.V } +"Vector outer products:" +{ $subsection n*V(*)V+M-in-place } +{ $subsection n*V(*)Vconj+M-in-place } +{ $subsection n*V(*)V+M } +{ $subsection n*V(*)Vconj+M } +{ $subsection n*V(*)V } +{ $subsection n*V(*)Vconj } { $subsection V(*) } { $subsection V(*)conj } +"Matrix products:" +{ $subsection n*M.M+n*M-in-place } +{ $subsection n*M.M+n*M } +{ $subsection n*M.M } { $subsection M. } +"Scalar-matrix products:" +{ $subsection n*M-in-place } { $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." ; +{ $subsection M*n } +{ $subsection M/n } ; + +ABOUT: "math.blas.matrices" 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:" diff --git a/extra/math/blas/vectors/vectors-docs.factor b/extra/math/blas/vectors/vectors-docs.factor index 1518bffd95..4fad9c7378 100644 --- a/extra/math/blas/vectors/vectors-docs.factor +++ b/extra/math/blas/vectors/vectors-docs.factor @@ -1,6 +1,32 @@ USING: alien byte-arrays help.markup help.syntax sequences ; IN: math.blas.vectors +ARTICLE: "math.blas.vectors" "BLAS interface vector operations" +"Slicing vectors:" +{ $subsection Vsub } +"Taking the norm (magnitude) of a vector:" +{ $subsection Vnorm } +"Summing and taking the maximum of elements:" +{ $subsection Vasum } +{ $subsection Viamax } +{ $subsection Vamax } +"Scalar-vector products:" +{ $subsection n*V-in-place } +{ $subsection n*V } +{ $subsection V*n } +{ $subsection V/n } +{ $subsection Vneg } +"Vector addition:" +{ $subsection n*V+V-in-place } +{ $subsection n*V+V } +{ $subsection V+ } +{ $subsection V- } +"Vector inner products:" +{ $subsection V. } +{ $subsection V.conj } ; + +ABOUT: "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 @@ -100,4 +126,6 @@ HELP: V/n { n*V+V-in-place n*V-in-place n*V+V n*V V+ V- Vneg V*n V/n } related-words - +HELP: Vsub +{ $values { "v" "a BLAS vector inheriting from " { $link blas-vector-base } } { "start" "The index of the first element of the slice" } { "length" "The length of the slice" } } +{ $description "Slice a subvector out of " { $snippet "v" } " with the given length. The subvector will share storage with the parent vector." } ; diff --git a/extra/math/blas/vectors/vectors-tests.factor b/extra/math/blas/vectors/vectors-tests.factor index e059d2943d..d4cff82e50 100644 --- a/extra/math/blas/vectors/vectors-tests.factor +++ b/extra/math/blas/vectors/vectors-tests.factor @@ -171,3 +171,10 @@ unit-test [ -6.0 ] [ dvector{ 1.0 -5.0 4.0 -6.0 -1.0 } Vamax ] unit-test [ C{ 2.0 -5.0 } ] [ cvector{ C{ 2.0 -5.0 } 4.0 -6.0 -1.0 } Vamax ] unit-test [ C{ 2.0 -5.0 } ] [ zvector{ C{ 2.0 -5.0 } 4.0 -6.0 -1.0 } Vamax ] unit-test + +! Vsub + +[ svector{ -5.0 4.0 -6.0 } ] [ svector{ 1.0 -5.0 4.0 -6.0 -1.0 } 1 3 Vsub ] unit-test +[ dvector{ -5.0 4.0 -6.0 } ] [ dvector{ 1.0 -5.0 4.0 -6.0 -1.0 } 1 3 Vsub ] unit-test +[ cvector{ -5.0 C{ 4.0 3.0 } -6.0 } ] [ cvector{ 1.0 -5.0 C{ 4.0 3.0 } -6.0 -1.0 } 1 3 Vsub ] unit-test +[ zvector{ -5.0 C{ 4.0 3.0 } -6.0 } ] [ zvector{ 1.0 -5.0 C{ 4.0 3.0 } -6.0 -1.0 } 1 3 Vsub ] unit-test diff --git a/extra/math/blas/vectors/vectors.factor b/extra/math/blas/vectors/vectors.factor index bd3b54c7eb..3c927318a6 100644 --- a/extra/math/blas/vectors/vectors.factor +++ b/extra/math/blas/vectors/vectors.factor @@ -135,7 +135,7 @@ PRIVATE> [ length>> 0 ] [ (blas-vector-like) ] tri ; -: ( length exemplar -- ) +: ( length exemplar -- vector ) [ element-type ] [ 1 swap ] 2bi (blas-vector-like) ; @@ -285,5 +285,13 @@ METHOD: Viamax { float-complex-blas-vector } METHOD: Viamax { double-complex-blas-vector } (prepare-nrm2) cblas_izamax ; -: Vamax ( v -- max ) +: Vamax ( x -- max ) [ Viamax ] keep nth ; inline + +: Vsub ( v start length -- vsub ) + rot [ + [ + nip [ inc>> ] [ element-type heap-size ] [ data>> ] tri + [ * * ] dip + ] [ swap 2nip ] [ 2nip inc>> ] 3tri + ] keep (blas-vector-like) ;