basis/math/vectors/vectors-docs.factor

   1 USING: help.markup help.syntax math math.functions sequences ;
   2 IN: math.vectors
   3
   4 ARTICLE: "math-vectors" "Vector arithmetic"
   5 "Any Factor sequence can be used to represent a mathematical vector, however for best performance, the sequences defined by the " { $vocab-link "specialized-arrays" } " and " { $vocab-link "math.vectors.simd" } " vocabularies should be used."
   6 $nl
   7 "Acting on vectors by a scalar:"
   8 { $subsection vneg }
   9 { $subsection v*n }
  10 { $subsection n*v }
  11 { $subsection v/n }
  12 { $subsection n/v }
  13 { $subsection v+n }
  14 { $subsection n+v }
  15 { $subsection v-n }
  16 { $subsection n-v }
  17 "Vector unary operations:"
  18 { $subsection vneg }
  19 { $subsection vabs }
  20 { $subsection vsqrt }
  21 { $subsection vfloor }
  22 { $subsection vceiling }
  23 { $subsection vtruncate }
  24 "Vector/vector binary operations:"
  25 { $subsection v+ }
  26 { $subsection v- }
  27 { $subsection v+- }
  28 { $subsection v* }
  29 { $subsection v/ }
  30 "Saturated arithmetic (only on " { $link "specialized-arrays" } "):"
  31 { $subsection vs+ }
  32 { $subsection vs- }
  33 { $subsection vs* }
  34 "Comparisons:"
  35 { $subsection vmax }
  36 { $subsection vmin }
  37 "Bitwise operations:"
  38 { $subsection vbitand }
  39 { $subsection vbitor }
  40 { $subsection vbitxor }
  41 { $subsection v<< }
  42 { $subsection v>> }
  43 "Inner product and norm:"
  44 { $subsection v. }
  45 { $subsection norm }
  46 { $subsection norm-sq }
  47 { $subsection normalize }
  48 "Comparing vectors:"
  49 { $subsection distance }
  50 { $subsection v~ }
  51 "Other functions:"
  52 { $subsection vsupremum }
  53 { $subsection vinfimum }
  54 { $subsection trilerp }
  55 { $subsection bilerp }
  56 { $subsection vlerp }
  57 { $subsection vnlerp }
  58 { $subsection vbilerp } ;
  59
  60 ABOUT: "math-vectors"
  61
  62 HELP: vneg
  63 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
  64 { $description "Negates each element of " { $snippet "u" } "." } ;
  65
  66 HELP: vabs
  67 { $values { "u" "a sequence of numbers" } { "v" "a sequence of non-negative real numbers" } }
  68 { $description "Takes the absolute value of each element of " { $snippet "u" } "." } ;
  69
  70 HELP: vsqrt
  71 { $values { "u" "a sequence of non-negative real numbers" } { "v" "a sequence of non-negative real numbers" } }
  72 { $description "Takes the square root of each element of " { $snippet "u" } "." }
  73 { $warning "For performance reasons, this does not work with negative inputs, unlike " { $link sqrt } "." } ;
  74
  75 HELP: vfloor
  76 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } }
  77 { $description "Takes the " { $link floor } " of each element of " { $snippet "u" } "." } ;
  78
  79 HELP: vceiling
  80 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } }
  81 { $description "Takes the " { $link ceiling } " of each element of " { $snippet "u" } "." } ;
  82
  83 HELP: vtruncate
  84 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } }
  85 { $description "Truncates each element of " { $snippet "u" } "." } ;
  86
  87 HELP: n+v
  88 { $values { "n" "a number" } { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
  89 { $description "Adds " { $snippet "n" } " to each element of " { $snippet "u" } "." } ;
  90
  91 HELP: v+n
  92 { $values { "u" "a sequence of numbers" } { "n" "a number" } { "v" "a sequence of numbers" } }
  93 { $description "Adds " { $snippet "n" } " to each element of " { $snippet "u" } "." } ;
  94
  95 HELP: n-v
  96 { $values { "n" "a number" } { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
  97 { $description "Subtracts each element of " { $snippet "u" } " from " { $snippet "n" } "." } ;
  98
  99 HELP: v-n
 100 { $values { "u" "a sequence of numbers" } { "n" "a number" } { "v" "a sequence of numbers" } }
 101 { $description "Subtracts " { $snippet "n" } " from each element of " { $snippet "u" } "." } ;
 102
 103 HELP: n*v
 104 { $values { "n" "a number" } { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
 105 { $description "Multiplies each element of " { $snippet "u" } " by " { $snippet "n" } "." } ;
 106
 107 HELP: v*n
 108 { $values { "u" "a sequence of numbers" } { "n" "a number" } { "v" "a sequence of numbers" } }
 109 { $description "Multiplies each element of " { $snippet "u" } " by " { $snippet "n" } "." } ;
 110
 111 HELP: n/v
 112 { $values { "n" "a number" } { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
 113 { $description "Divides " { $snippet "n" } " by each element of " { $snippet "u" } "." }
 114 { $errors "May throw an error if a division by zero occurs; see " { $link "division-by-zero" } "." } ;
 115
 116 HELP: v/n
 117 { $values { "u" "a sequence of numbers" } { "n" "a number" } { "v" "a sequence of numbers" } }
 118 { $description "Divides each element of " { $snippet "u" } " by " { $snippet "n" } "." }
 119 { $errors "May throw an error if a division by zero occurs; see " { $link "division-by-zero" } "." } ;
 120
 121 HELP: v+
 122 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 123 { $description "Adds " { $snippet "u" } " and " { $snippet "v" } " component-wise." } ;
 124
 125 HELP: v-
 126 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 127 { $description "Subtracts " { $snippet "v" } " from " { $snippet "u" } " component-wise." } ;
 128
 129 HELP: v+-
 130 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 131 { $description "Adds and subtracts alternate elements of " { $snippet "v" } " and " { $snippet "u" } " component-wise." }
 132 { $examples
 133     { $example
 134         "USING: math.vectors prettyprint ;"
 135         "{ 1 2 3 } { 2 3 2 } v+- ."
 136         "{ -1 5 1 }"
 137     }
 138 } ;
 139
 140 HELP: [v-]
 141 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 142 { $description "Subtracts " { $snippet "v" } " from " { $snippet "u" } " component-wise; any components which become negative are set to zero." } ;
 143
 144 HELP: v*
 145 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 146 { $description "Multiplies " { $snippet "u" } " and " { $snippet "v" } " component-wise." } ;
 147
 148 HELP: v/
 149 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 150 { $description "Divides " { $snippet "u" } " by " { $snippet "v" } " component-wise." }
 151 { $errors "May throw an error if a division by zero occurs; see " { $link "division-by-zero" } "." } ;
 152
 153 HELP: vmax
 154 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 155 { $description "Creates a sequence where each element is the maximum of the corresponding elements from " { $snippet "u" } " andd " { $snippet "v" } "." }
 156 { $examples { $example "USING: math.vectors prettyprint ;" "{ 1 2 5 } { -7 6 3 } vmax ." "{ 1 6 5 }" } } ;
 157
 158 HELP: vmin
 159 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 160 { $description "Creates a sequence where each element is the minimum of the corresponding elements from " { $snippet "u" } " andd " { $snippet "v" } "." }
 161 { $examples { $example "USING: math.vectors prettyprint ;" "{ 1 2 5 } { -7 6 3 } vmin ." "{ -7 2 3 }" } } ;
 162
 163 HELP: v.
 164 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "x" "a real number" } }
 165 { $description "Computes the real-valued dot product." }
 166 { $notes
 167     "This word can also take complex number sequences as input, however mathematically it will compute the wrong result. The complex-valued dot product is defined differently:"
 168     { $code "0 [ conjugate * + ] 2reduce" }
 169 } ;
 170
 171 HELP: vs+
 172 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 173 { $description "Adds " { $snippet "u" } " and " { $snippet "v" } " component-wise with saturation." }
 174 { $examples
 175     "With saturation:"
 176     { $example
 177         "USING: math.vectors prettyprint specialized-arrays ;"
 178         "SPECIALIZED-ARRAY: uchar"
 179         "uchar-array{ 100 200 150 } uchar-array{ 70 70 70 } vs+ ."
 180         "uchar-array{ 170 255 220 }"
 181     }
 182     "Without saturation:"
 183     { $example
 184         "USING: math.vectors prettyprint specialized-arrays ;"
 185         "SPECIALIZED-ARRAY: uchar"
 186         "uchar-array{ 100 200 150 } uchar-array{ 70 70 70 } v+ ."
 187         "uchar-array{ 170 14 220 }"
 188     }
 189 } ;
 190
 191 HELP: vs-
 192 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 193 { $description "Subtracts " { $snippet "v" } " from " { $snippet "u" } " component-wise with saturation." } ;
 194
 195 HELP: vs*
 196 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 197 { $description "Multiplies " { $snippet "u" } " and " { $snippet "v" } " component-wise with saturation." } ;
 198
 199 HELP: vbitand
 200 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 201 { $description "Takes the bitwise and of " { $snippet "u" } " and " { $snippet "v" } " component-wise." }
 202 { $notes "Unlike " { $link bitand } ", this word may be used on a specialized array of floats or doubles, in which case the bitwise representation of the floating point numbers is operated upon." } ;
 203
 204 HELP: vbitor
 205 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 206 { $description "Takes the bitwise or of " { $snippet "u" } " and " { $snippet "v" } " component-wise." }
 207 { $notes "Unlike " { $link bitor } ", this word may be used on a specialized array of floats or doubles, in which case the bitwise representation of the floating point numbers is operated upon." } ;
 208
 209 HELP: vbitxor
 210 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 211 { $description "Takes the bitwise exclusive or of " { $snippet "u" } " and " { $snippet "v" } " component-wise." }
 212 { $notes "Unlike " { $link bitxor } ", this word may be used on a specialized array of floats or doubles, in which case the bitwise representation of the floating point numbers is operated upon." } ;
 213
 214 HELP: v<<
 215 { $values { "u" "a sequence of integers" } { "n" "a non-negative integer" } { "w" "a sequence of integers" } }
 216 { $description "Shifts each element of " { $snippet "u" } " to the left by " { $snippet "n" } " bits." } ;
 217
 218 HELP: v>>
 219 { $values { "u" "a sequence of integers" } { "n" "a non-negative integer" } { "w" "a sequence of integers" } }
 220 { $description "Shifts each element of " { $snippet "u" } " to the right by " { $snippet "n" } " bits." } ;
 221
 222 HELP: norm-sq
 223 { $values { "v" "a sequence of numbers" } { "x" "a non-negative real number" } }
 224 { $description "Computes the squared length of a mathematical vector." } ;
 225
 226 HELP: norm
 227 { $values { "v" "a sequence of numbers" } { "x" "a non-negative real number" } }
 228 { $description "Computes the length of a mathematical vector." } ;
 229
 230 HELP: normalize
 231 { $values { "u" "a sequence of numbers, not all zero" } { "v" "a sequence of numbers" } }
 232 { $description "Outputs a vector with the same direction as " { $snippet "u" } " but length 1." } ;
 233
 234 HELP: distance
 235 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "x" "a non-negative real number" } }
 236 { $description "Outputs the Euclidean distance between two vectors." } ;
 237
 238 HELP: set-axis
 239 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "axis" "a sequence of 0/1" } { "w" "a sequence of numbers" } }
 240 { $description "Using " { $snippet "w" } " as a template, creates a new sequence containing corresponding elements from " { $snippet "u" } " in place of 0, and corresponding elements from " { $snippet "v" } " in place of 1." }
 241 { $examples { $example "USING: math.vectors prettyprint ;" "{ 1 2 3 } { 4 5 6 } { 0 1 0 } set-axis ." "{ 1 5 3 }" } } ;
 242
 243 { 2map v+ v- v* v/ } related-words
 244
 245 { 2reduce v. } related-words
 246
 247 { vs+ vs- vs* } related-words