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

   1 USING: alien byte-arrays help.markup help.syntax math sequences ;
   2 IN: math.blas.vectors
   3
   4 ARTICLE: "math.blas.vectors" "BLAS interface vector operations"
   5 "Slicing vectors:"
   6 { $subsections Vsub }
   7 "Taking the norm (magnitude) of a vector:"
   8 { $subsections Vnorm }
   9 "Summing and taking the maximum of elements:"
  10 { $subsections
  11     Vasum
  12     Viamax
  13     Vamax
  14 }
  15 "Scalar-vector products:"
  16 { $subsections
  17     n*V!
  18     n*V
  19     V*n
  20     V/n
  21     Vneg
  22 }
  23 "Vector addition:"
  24 { $subsections
  25     n*V+V!
  26     n*V+V
  27     V+
  28     V-
  29 }
  30 "Vector inner products:"
  31 { $subsections
  32     V.
  33     V.conj
  34 }
  35 "Literal syntax:"
  36 { $subsections
  37     POSTPONE: svector{
  38     POSTPONE: dvector{
  39     POSTPONE: cvector{
  40     POSTPONE: zvector{
  41 } ;
  42
  43 ABOUT: "math.blas.vectors"
  44
  45 HELP: blas-vector-base
  46 { $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:"
  47 { $list
  48     { { $link float-blas-vector } }
  49     { { $link double-blas-vector } }
  50     { { $link complex-float-blas-vector } }
  51     { { $link complex-double-blas-vector } }
  52 }
  53 "All of these subclasses share the same tuple layout:"
  54 { $list
  55     { { $snippet "underlying" } " contains an alien pointer referencing or byte-array containing a packed array of float, double, float complex, or double complex values;" }
  56     { { $snippet "length" } " indicates the length of the vector;" }
  57     { "and " { $snippet "inc" } " indicates the distance, in elements, between elements." }
  58 } } ;
  59
  60 HELP: float-blas-vector
  61 { $class-description "A vector of single-precision floating-point values. For details on the tuple layout, see " { $link blas-vector-base } "." } ;
  62 HELP: double-blas-vector
  63 { $class-description "A vector of double-precision floating-point values. For details on the tuple layout, see " { $link blas-vector-base } "." } ;
  64 HELP: complex-float-blas-vector
  65 { $class-description "A vector of single-precision floating-point complex values. For details on the tuple layout, see " { $link blas-vector-base } "." } ;
  66 HELP: complex-double-blas-vector
  67 { $class-description "A vector of double-precision floating-point complex values. For details on the tuple layout, see " { $link blas-vector-base } "." } ;
  68
  69 HELP: n*V+V!
  70 { $values { "alpha" number } { "x" blas-vector-base } { "y" blas-vector-base } { "y=alpha*x+y" blas-vector-base } }
  71 { $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." }
  72 { $side-effects "y" } ;
  73
  74 HELP: n*V!
  75 { $values { "alpha" number } { "x" blas-vector-base } { "x=alpha*x" blas-vector-base } }
  76 { $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." }
  77 { $side-effects "x" } ;
  78
  79 HELP: V.
  80 { $values { "x" blas-vector-base } { "y" blas-vector-base } { "x.y" number } }
  81 { $description "Calculate the inner product " { $snippet "x⋅y" } ". Corresponds to the xDOT and xDOTU routines in BLAS." } ;
  82
  83 HELP: V.conj
  84 { $values { "x" blas-vector-base } { "y" blas-vector-base } { "xconj.y" number } }
  85 { $description "Calculate the conjugate inner product " { $snippet "x̅⋅y" } ". Corresponds to the xDOTC routines in BLAS." } ;
  86
  87 HELP: Vnorm
  88 { $values { "x" blas-vector-base } { "norm" number } }
  89 { $description "Calculate the norm-2, i.e., the magnitude or absolute value, of " { $snippet "x" } " (" { $snippet "‖x‖₂" } "). Corresponds to the xNRM2 routines in BLAS." } ;
  90
  91 HELP: Vasum
  92 { $values { "x" blas-vector-base } { "sum" number } }
  93 { $description "Calculate the sum of the norm-1s of the elements of " { $snippet "x" } " (" { $snippet "Σ ‖xᵢ‖₁" } "). Corresponds to the xASUM routines in BLAS." } ;
  94
  95 HELP: Vswap
  96 { $values { "x" blas-vector-base } { "y" blas-vector-base } { "x=y" blas-vector-base } { "y=x" blas-vector-base } }
  97 { $description "Swap the contents of " { $snippet "x" } " and " { $snippet "y" } " in place. Corresponds to the xSWAP routines in BLAS." }
  98 { $side-effects "x" "y" } ;
  99
 100 HELP: Viamax
 101 { $values { "x" blas-vector-base } { "max-i" integer } }
 102 { $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." } ;
 103
 104 HELP: Vamax
 105 { $values { "x" blas-vector-base } { "max" number } }
 106 { $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 element closest to the beginning. Corresponds to the IxAMAX routines in BLAS." } ;
 107
 108 { Viamax Vamax } related-words
 109
 110 HELP: <zero-vector>
 111 { $values { "exemplar" blas-vector-base } { "zero" blas-vector-base } }
 112 { $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 <empty-vector> } "." } ;
 113
 114 HELP: n*V+V
 115 { $values { "alpha" number } { "x" blas-vector-base } { "y" blas-vector-base } { "alpha*x+y" blas-vector-base } }
 116 { $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." } ;
 117
 118 HELP: n*V
 119 { $values { "alpha" number } { "x" blas-vector-base } { "alpha*x" blas-vector-base } }
 120 { $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." } ;
 121
 122 HELP: V+
 123 { $values { "x" blas-vector-base } { "y" blas-vector-base } { "x+y" blas-vector-base } }
 124 { $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." } ;
 125
 126 HELP: V-
 127 { $values { "x" blas-vector-base } { "y" blas-vector-base } { "x-y" blas-vector-base } }
 128 { $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." } ;
 129
 130 HELP: Vneg
 131 { $values { "x" blas-vector-base } { "-x" blas-vector-base } }
 132 { $description "Negate the elements of " { $snippet "x" } " and return a freshly-allocated vector with the same length as " { $snippet "x" } " containing the result." } ;
 133
 134 HELP: V*n
 135 { $values { "x" blas-vector-base } { "alpha" number } { "x*alpha" blas-vector-base } }
 136 { $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." } ;
 137
 138 HELP: V/n
 139 { $values { "x" blas-vector-base } { "alpha" number } { "x/alpha" blas-vector-base } }
 140 { $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." } ;
 141
 142 { n*V+V! n*V! n*V+V n*V V+ V- Vneg V*n V/n } related-words
 143
 144 HELP: Vsub
 145 { $values { "v" blas-vector-base } { "start" integer } { "length" integer } { "sub" blas-vector-base } }
 146 { $description "Slice a subvector out of " { $snippet "v" } " starting at " { $snippet "start" } " with the given " { $snippet "length" } ". The subvector will share storage with the parent vector." } ;
 147
 148 HELP: svector{
 149 { $syntax "svector{ 1.0 -2.0 3.0 }" }
 150 { $description "Construct a literal " { $link float-blas-vector } "." } ;
 151
 152 HELP: dvector{
 153 { $syntax "dvector{ 1.0 -2.0 3.0 }" }
 154 { $description "Construct a literal " { $link double-blas-vector } "." } ;
 155
 156 HELP: cvector{
 157 { $syntax "cvector{ 1.0 -2.0 C{ 3.0 -1.0 } }" }
 158 { $description "Construct a literal " { $link complex-float-blas-vector } "." } ;
 159
 160 HELP: zvector{
 161 { $syntax "dvector{ 1.0 -2.0 C{ 3.0 -1.0 } }" }
 162 { $description "Construct a literal " { $link complex-double-blas-vector } "." } ;
 163
 164 {
 165     POSTPONE: svector{ POSTPONE: dvector{
 166     POSTPONE: cvector{ POSTPONE: zvector{
 167 } related-words