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 "Componentwise vector operations:"
  35 { $subsection v< }
  36 { $subsection v<= }
  37 { $subsection v= }
  38 { $subsection v>= }
  39 { $subsection v> }
  40 { $subsection vunordered? }
  41 { $subsection vmax }
  42 { $subsection vmin }
  43 "Bitwise operations:"
  44 { $subsection vbitand }
  45 { $subsection vbitandn }
  46 { $subsection vbitor }
  47 { $subsection vbitxor }
  48 { $subsection vlshift }
  49 { $subsection vrshift }
  50 "Componentwise logical operations:"
  51 { $subsection vand }
  52 { $subsection vor }
  53 { $subsection vxor }
  54 { $subsection vmask }
  55 { $subsection v? }
  56 "Shuffling:"
  57 { $subsection vshuffle }
  58 "Inner product and norm:"
  59 { $subsection v. }
  60 { $subsection norm }
  61 { $subsection norm-sq }
  62 { $subsection normalize }
  63 "Comparing entire vectors:"
  64 { $subsection distance }
  65 { $subsection v~ }
  66 "Other functions:"
  67 { $subsection vsupremum }
  68 { $subsection vinfimum }
  69 { $subsection trilerp }
  70 { $subsection bilerp }
  71 { $subsection vlerp }
  72 { $subsection vnlerp }
  73 { $subsection vbilerp } ;
  74
  75 ABOUT: "math-vectors"
  76
  77 HELP: vneg
  78 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
  79 { $description "Negates each element of " { $snippet "u" } "." } ;
  80
  81 HELP: vabs
  82 { $values { "u" "a sequence of numbers" } { "v" "a sequence of non-negative real numbers" } }
  83 { $description "Takes the absolute value of each element of " { $snippet "u" } "." } ;
  84
  85 HELP: vsqrt
  86 { $values { "u" "a sequence of non-negative real numbers" } { "v" "a sequence of non-negative real numbers" } }
  87 { $description "Takes the square root of each element of " { $snippet "u" } "." }
  88 { $warning "For performance reasons, this does not work with negative inputs, unlike " { $link sqrt } "." } ;
  89
  90 HELP: vfloor
  91 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } }
  92 { $description "Takes the " { $link floor } " of each element of " { $snippet "u" } "." } ;
  93
  94 HELP: vceiling
  95 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } }
  96 { $description "Takes the " { $link ceiling } " of each element of " { $snippet "u" } "." } ;
  97
  98 HELP: vtruncate
  99 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } }
 100 { $description "Truncates each element of " { $snippet "u" } "." } ;
 101
 102 HELP: n+v
 103 { $values { "n" "a number" } { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
 104 { $description "Adds " { $snippet "n" } " to each element of " { $snippet "u" } "." } ;
 105
 106 HELP: v+n
 107 { $values { "u" "a sequence of numbers" } { "n" "a number" } { "v" "a sequence of numbers" } }
 108 { $description "Adds " { $snippet "n" } " to each element of " { $snippet "u" } "." } ;
 109
 110 HELP: n-v
 111 { $values { "n" "a number" } { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
 112 { $description "Subtracts each element of " { $snippet "u" } " from " { $snippet "n" } "." } ;
 113
 114 HELP: v-n
 115 { $values { "u" "a sequence of numbers" } { "n" "a number" } { "v" "a sequence of numbers" } }
 116 { $description "Subtracts " { $snippet "n" } " from each element of " { $snippet "u" } "." } ;
 117
 118 HELP: n*v
 119 { $values { "n" "a number" } { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
 120 { $description "Multiplies each element of " { $snippet "u" } " by " { $snippet "n" } "." } ;
 121
 122 HELP: v*n
 123 { $values { "u" "a sequence of numbers" } { "n" "a number" } { "v" "a sequence of numbers" } }
 124 { $description "Multiplies each element of " { $snippet "u" } " by " { $snippet "n" } "." } ;
 125
 126 HELP: n/v
 127 { $values { "n" "a number" } { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
 128 { $description "Divides " { $snippet "n" } " by each element of " { $snippet "u" } "." }
 129 { $errors "May throw an error if a division by zero occurs; see " { $link "division-by-zero" } "." } ;
 130
 131 HELP: v/n
 132 { $values { "u" "a sequence of numbers" } { "n" "a number" } { "v" "a sequence of numbers" } }
 133 { $description "Divides each element of " { $snippet "u" } " by " { $snippet "n" } "." }
 134 { $errors "May throw an error if a division by zero occurs; see " { $link "division-by-zero" } "." } ;
 135
 136 HELP: v+
 137 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 138 { $description "Adds " { $snippet "u" } " and " { $snippet "v" } " component-wise." } ;
 139
 140 HELP: v-
 141 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 142 { $description "Subtracts " { $snippet "v" } " from " { $snippet "u" } " component-wise." } ;
 143
 144 HELP: v+-
 145 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 146 { $description "Adds and subtracts alternate elements of " { $snippet "v" } " and " { $snippet "u" } " component-wise." }
 147 { $examples
 148     { $example
 149         "USING: math.vectors prettyprint ;"
 150         "{ 1 2 3 } { 2 3 2 } v+- ."
 151         "{ -1 5 1 }"
 152     }
 153 } ;
 154
 155 HELP: [v-]
 156 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 157 { $description "Subtracts " { $snippet "v" } " from " { $snippet "u" } " component-wise; any components which become negative are set to zero." } ;
 158
 159 HELP: v*
 160 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 161 { $description "Multiplies " { $snippet "u" } " and " { $snippet "v" } " component-wise." } ;
 162
 163 HELP: v/
 164 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 165 { $description "Divides " { $snippet "u" } " by " { $snippet "v" } " component-wise." }
 166 { $errors "May throw an error if a division by zero occurs; see " { $link "division-by-zero" } "." } ;
 167
 168 HELP: vmax
 169 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 170 { $description "Creates a sequence where each element is the maximum of the corresponding elements from " { $snippet "u" } " and " { $snippet "v" } "." }
 171 { $examples { $example "USING: math.vectors prettyprint ;" "{ 1 2 5 } { -7 6 3 } vmax ." "{ 1 6 5 }" } } ;
 172
 173 HELP: vmin
 174 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 175 { $description "Creates a sequence where each element is the minimum of the corresponding elements from " { $snippet "u" } " and " { $snippet "v" } "." }
 176 { $examples { $example "USING: math.vectors prettyprint ;" "{ 1 2 5 } { -7 6 3 } vmin ." "{ -7 2 3 }" } } ;
 177
 178 HELP: v.
 179 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "x" "a real number" } }
 180 { $description "Computes the dot product of two vectors." } ;
 181
 182 HELP: vs+
 183 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 184 { $description "Adds " { $snippet "u" } " and " { $snippet "v" } " component-wise with saturation." }
 185 { $examples
 186     "With saturation:"
 187     { $example
 188         "USING: alien.c-types math.vectors prettyprint specialized-arrays ;"
 189         "SPECIALIZED-ARRAY: uchar"
 190         "uchar-array{ 100 200 150 } uchar-array{ 70 70 70 } vs+ ."
 191         "uchar-array{ 170 255 220 }"
 192     }
 193     "Without saturation:"
 194     { $example
 195         "USING: alien.c-types math.vectors prettyprint specialized-arrays ;"
 196         "SPECIALIZED-ARRAY: uchar"
 197         "uchar-array{ 100 200 150 } uchar-array{ 70 70 70 } v+ ."
 198         "uchar-array{ 170 14 220 }"
 199     }
 200 } ;
 201
 202 HELP: vs-
 203 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 204 { $description "Subtracts " { $snippet "v" } " from " { $snippet "u" } " component-wise with saturation." } ;
 205
 206 HELP: vs*
 207 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 208 { $description "Multiplies " { $snippet "u" } " and " { $snippet "v" } " component-wise with saturation." } ;
 209
 210 HELP: vbitand
 211 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 212 { $description "Takes the bitwise and of " { $snippet "u" } " and " { $snippet "v" } " component-wise." }
 213 { $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." } ;
 214
 215 HELP: vbitandn
 216 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 217 { $description "Takes the bitwise and-not of " { $snippet "u" } " and " { $snippet "v" } " component-wise, where " { $snippet "x and-not y" } " is defined as " { $snippet "not(x) and y" } "." }
 218 { $notes "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." } ;
 219
 220 HELP: vbitor
 221 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 222 { $description "Takes the bitwise or of " { $snippet "u" } " and " { $snippet "v" } " component-wise." }
 223 { $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." } ;
 224
 225 HELP: vbitxor
 226 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 227 { $description "Takes the bitwise exclusive or of " { $snippet "u" } " and " { $snippet "v" } " component-wise." }
 228 { $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." } ;
 229
 230 HELP: vlshift
 231 { $values { "u" "a sequence of integers" } { "n" "a non-negative integer" } { "w" "a sequence of integers" } }
 232 { $description "Shifts each element of " { $snippet "u" } " to the left by " { $snippet "n" } " bits." }
 233 { $notes "Undefined behavior will result if " { $snippet "n" } " is negative." } ;
 234
 235 HELP: vrshift
 236 { $values { "u" "a sequence of integers" } { "n" "a non-negative integer" } { "w" "a sequence of integers" } }
 237 { $description "Shifts each element of " { $snippet "u" } " to the right by " { $snippet "n" } " bits." }
 238 { $notes "Undefined behavior will result if " { $snippet "n" } " is negative." } ;
 239
 240 HELP: hlshift
 241 { $values { "u" "a SIMD array" } { "n" "a non-negative integer" } { "w" "a SIMD array" } }
 242 { $description "Shifts the entire SIMD array to the left by " { $snippet "n" } " bytes. This word may only be used in a context where the compiler can statically infer that the input is a SIMD array." } ;
 243
 244 HELP: hrshift
 245 { $values { "u" "a SIMD array" } { "n" "a non-negative integer" } { "w" "a SIMD array" } }
 246 { $description "Shifts the entire SIMD array to the right by " { $snippet "n" } " bytes. This word may only be used in a context where the compiler can statically infer that the input is a SIMD array." } ;
 247
 248 HELP: vbroadcast
 249 { $values { "u" "a SIMD array" } { "n" "a non-negative integer" } { "v" "a SIMD array" } }
 250 { $description "Outputs a new SIMD array of the same type as " { $snippet "u" } " where every element is equal to the " { $snippet "n" } "th element of " { $snippet "u" } "." }
 251 { $examples
 252     { $example
 253         "USING: alien.c-types math.vectors math.vectors.simd" "prettyprint ;"
 254         "SIMD: int"
 255         "int-4{ 69 42 911 13 } 2 vbroadcast ."
 256         "int-4{ 911 911 911 911 }"
 257     }
 258 } ;
 259
 260 HELP: vshuffle
 261 { $values { "u" "a SIMD array" } { "perm" "an array of integers" } { "v" "a SIMD array" } }
 262 { $description "Permutes the elements of a SIMD array. Duplicate entries are allowed in the permutation." }
 263 { $examples
 264     { $example
 265         "USING: alien.c-types math.vectors math.vectors.simd" "prettyprint ;"
 266         "SIMD: int"
 267         "int-4{ 69 42 911 13 } { 1 3 2 3 } vshuffle ."
 268         "int-4{ 42 13 911 13 }"
 269     }
 270 } ;
 271
 272 HELP: norm-sq
 273 { $values { "v" "a sequence of numbers" } { "x" "a non-negative real number" } }
 274 { $description "Computes the squared length of a mathematical vector." } ;
 275
 276 HELP: norm
 277 { $values { "v" "a sequence of numbers" } { "x" "a non-negative real number" } }
 278 { $description "Computes the length of a mathematical vector." } ;
 279
 280 HELP: normalize
 281 { $values { "u" "a sequence of numbers, not all zero" } { "v" "a sequence of numbers" } }
 282 { $description "Outputs a vector with the same direction as " { $snippet "u" } " but length 1." } ;
 283
 284 HELP: distance
 285 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "x" "a non-negative real number" } }
 286 { $description "Outputs the Euclidean distance between two vectors." } ;
 287
 288 HELP: set-axis
 289 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "axis" "a sequence of 0/1" } { "w" "a sequence of numbers" } }
 290 { $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." }
 291 { $examples { $example "USING: math.vectors prettyprint ;" "{ 1 2 3 } { 4 5 6 } { 0 1 0 } set-axis ." "{ 1 5 3 }" } } ;
 292
 293 HELP: v<
 294 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of booleans" } }
 295 { $description "Compares each corresponding element of " { $snippet "u" } " and " { $snippet "v" } ", returning " { $link t } " in the result vector when the former is less than the latter or " { $link f } " otherwise." } ;
 296
 297 HELP: v<=
 298 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of booleans" } }
 299 { $description "Compares each corresponding element of " { $snippet "u" } " and " { $snippet "v" } ", returning " { $link t } " in the result vector when the former is less than or equal to the latter or " { $link f } " otherwise." } ;
 300
 301 HELP: v=
 302 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of booleans" } }
 303 { $description "Compares each corresponding element of " { $snippet "u" } " and " { $snippet "v" } ", returning " { $link t } " in the result vector when they are equal or " { $link f } " otherwise." } ;
 304
 305 HELP: v>
 306 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of booleans" } }
 307 { $description "Compares each corresponding element of " { $snippet "u" } " and " { $snippet "v" } ", returning " { $link t } " in the result vector when the former is greater than the latter or " { $link f } " otherwise." } ;
 308
 309 HELP: v>=
 310 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of booleans" } }
 311 { $description "Compares each corresponding element of " { $snippet "u" } " and " { $snippet "v" } ", returning " { $link t } " in the result vector when the former is greater than or equal to the latter or " { $link f } " otherwise." } ;
 312
 313 HELP: vunordered?
 314 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of booleans" } }
 315 { $description "Compares each corresponding element of " { $snippet "u" } " and " { $snippet "v" } ", returning " { $link t } " in the result vector when either value is Not-a-Number or " { $link f } " otherwise." } ;
 316
 317 HELP: vand
 318 { $values { "u" "a sequence of booleans" } { "v" "a sequence of booleans" } { "w" "a sequence of booleans" } }
 319 { $description "Takes the logical AND of each corresponding element of " { $snippet "u" } " and " { $snippet "v" } "." } ;
 320
 321 HELP: vor
 322 { $values { "u" "a sequence of booleans" } { "v" "a sequence of booleans" } { "w" "a sequence of booleans" } }
 323 { $description "Takes the logical OR of each corresponding element of " { $snippet "u" } " and " { $snippet "v" } "." } ;
 324
 325 HELP: vxor
 326 { $values { "u" "a sequence of booleans" } { "v" "a sequence of booleans" } { "w" "a sequence of booleans" } }
 327 { $description "Takes the logical XOR of each corresponding element of " { $snippet "u" } " and " { $snippet "v" } "." } ;
 328
 329 HELP: vnot
 330 { $values { "u" "a sequence of booleans" } { "w" "a sequence of booleans" } }
 331 { $description "Takes the logical NOT of each element of " { $snippet "u" } "." } ;
 332
 333 HELP: vmask
 334 { $values { "u" "a sequence of numbers" } { "?" "a sequence of booleans" } { "u'" "a sequence of numbers" } }
 335 { $description "Returns a copy of " { $snippet "u" } " with the elements for which the corresponding element of " { $snippet "?" } " is false replaced by zero." } ;
 336
 337 HELP: v?
 338 { $values { "?" "a sequence of booleans" } { "true" "a sequence of numbers" } { "false" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 339 { $description "Creates a new sequence by selecting elements from the " { $snippet "true" } " and " { $snippet "false" } " sequences based on whether the corresponding element of the " { $snippet "?" } " sequence is true or false." } ;
 340
 341 { 2map v+ v- v* v/ } related-words
 342
 343 { 2reduce v. } related-words
 344
 345 { vs+ vs- vs* } related-words
 346
 347 { v< v<= v= v> v>= vunordered? vand vor vxor vnot vmask v? } related-words
 348
 349 { vbitand vbitandn vbitor vbitxor vbitnot } related-words