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-arithmetic" "Vector arithmetic"
   5 "Vector/vector binary operations:"
   6 { $subsections
   7     v+
   8     v-
   9     v+-
  10     v*
  11     v/
  12 }
  13 "Vector unary operations:"
  14 { $subsections
  15     vneg
  16     vabs
  17     vsqrt
  18     vfloor
  19     vceiling
  20     vtruncate
  21 }
  22 "Vector/scalar and scalar/vector binary operations:"
  23 { $subsections
  24     vneg
  25     v*n
  26     n*v
  27     v/n
  28     n/v
  29     v+n
  30     n+v
  31     v-n
  32     n-v
  33 }
  34 "Saturated arithmetic (only on " { $link "specialized-arrays" } "):"
  35 { $subsections
  36     vs+
  37     vs-
  38     vs*
  39 }
  40 "Inner product and norm:"
  41 { $subsections
  42     v.
  43     norm
  44     norm-sq
  45     normalize
  46 }
  47 "Comparing entire vectors:"
  48 { $subsections
  49     distance
  50     v~
  51 } ;
  52
  53 ARTICLE: "math-vectors-shuffle" "Vector shuffling, packing, and unpacking"
  54 { $notes
  55 "These operations are primarily meant to be used with " { $vocab-link "math.vectors.simd" } " types. The software fallbacks for types not supported by hardware will not perform well."
  56 }
  57 $nl
  58 { $subsections
  59     vshuffle
  60     vbroadcast
  61     hlshift
  62     hrshift
  63     vmerge
  64     (vmerge)
  65 }
  66 "See the " { $vocab-link "math.vectors.conversion" } " vocabulary for packing, unpacking, and converting vectors." ;
  67
  68 ARTICLE: "math-vectors-logic" "Vector component- and bit-wise logic"
  69 { $notes
  70 "See " { $link "math-vectors-simd-logic" } " for notes about using comparison and logical operations with SIMD vector types."
  71 }
  72 $nl
  73 "Element comparisons:"
  74 { $subsections
  75     v<
  76     v<=
  77     v=
  78     v>=
  79     v>
  80     vunordered?
  81     vmax
  82     vmin
  83     vsupremum
  84     vinfimum
  85 }
  86 "Bitwise operations:"
  87 { $subsections
  88     vbitand
  89     vbitandn
  90     vbitor
  91     vbitxor
  92     vbitnot
  93     vlshift
  94     vrshift
  95 }
  96 "Element logical operations:"
  97 { $subsections
  98     vand
  99     vandn
 100     vor
 101     vxor
 102     vnot
 103     v?
 104     vif
 105 }
 106 "Entire vector tests:"
 107 { $subsections
 108     vall?
 109     vany?
 110     vnone?
 111 }
 112 "Element shuffling:"
 113 { $subsections vshuffle } ;
 114
 115 ARTICLE: "math-vectors-misc" "Miscellaneous vector functions"
 116 { $subsections
 117     trilerp
 118     bilerp
 119     vlerp
 120     vnlerp
 121     vbilerp
 122 } ;
 123
 124 ARTICLE: "math-vectors-simd-logic" "Componentwise logic with SIMD vectors"
 125 "Processor SIMD units supported by the " { $vocab-link "math.vectors.simd" } " vocabulary represent boolean values as bitmasks, where a true result's binary representation is all ones and a false representation is all zeroes. This is the format in which results from comparison words such as " { $link v= } " return their results and in which logic and test words such as " { $link vand } " and " { $link vall? } " take their inputs when working with SIMD types. For a float vector, false will manifest itself as " { $snippet "0.0" } " and true as a " { $link POSTPONE: NAN: } " literal with a string of set bits in its payload:"
 126 { $example
 127 """USING: math.vectors math.vectors.simd prettyprint ;
 128
 129 float-4{ 1.0 2.0 3.0 0/0. } float-4{ 1.0 -2.0 3.0 0/0. } v= ."""
 130 """float-4{ NAN: fffffe0000000 0.0 NAN: fffffe0000000 0.0 }"""
 131 }
 132 "For an integer vector, false will manifest as " { $snippet "0" } " and true as " { $snippet "-1" } " (for signed vectors) or the largest representable value of the element type (for unsigned vectors):"
 133 { $example
 134 """USING: math.vectors math.vectors.simd prettyprint alien.c-types ;
 135
 136 int-4{ 1 2 3 0 } int-4{ 1 -2 3 4 } v=
 137 uchar-16{  0  1  2  3  4  5 6 7 8 9 10 11 12 13 14 15 }
 138 uchar-16{ 15 14 13 12 11 10 9 8 7 6  5  4  3  2  1  0 } v<
 139 [ . ] bi@"""
 140 """int-4{ -1 0 -1 0 }
 141 uchar-16{ 255 255 255 255 255 255 255 255 0 0 0 0 0 0 0 0 }"""
 142 }
 143 "This differs from Factor's native representation of boolean values, where " { $link f } " is false and every other value (including " { $snippet "0" } " and " { $snippet "0.0" } ") is true. To make it easy to construct literal SIMD masks, " { $link t } " and " { $link f } " are accepted inside SIMD literal syntax and expand to the proper true or false representation for the underlying type:"
 144 { $example
 145 """USING: math.vectors math.vectors.simd prettyprint alien.c-types ;
 146
 147 int-4{ f f t f } ."""
 148 """int-4{ 0 0 -1 0 }""" }
 149 "However, extracting an element from a boolean SIMD vector with " { $link nth } " will not yield a valid Factor boolean. This is not generally a problem, since the results of vector comparisons are meant to be consumed by subsequent vector logical and test operations, which will accept SIMD values in the native boolean format."
 150 $nl
 151 "Providing a SIMD boolean vector with element values other than the proper true and false representations as an input to the vector logical or test operations is undefined. Do not count on operations such as " { $link vall? } " or " { $link v? } " using bitwise operations to construct their results."
 152 $nl
 153 "This applies to the output of the following element comparison words:"
 154 { $list
 155 { $link v< }
 156 { $link v<= }
 157 { $link v= }
 158 { $link v>= }
 159 { $link v> }
 160 { $link vunordered? }
 161 }
 162 "This likewise applies to the " { $snippet "mask" } " argument of " { $link v? } " and to the inputs and outputs of the following element logic words:"
 163 { $list
 164 { $link vand }
 165 { $link vandn }
 166 { $link vor }
 167 { $link vxor }
 168 { $link vnot }
 169 }
 170 "Finally, this applies to the inputs of these vector test words:"
 171 { $list
 172 { $link vall? }
 173 { $link vany? }
 174 { $link vnone? }
 175 } ;
 176
 177 ARTICLE: "math-vectors" "Vector operations"
 178 "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."
 179 { $subsections
 180     "math-vectors-arithmetic"
 181     "math-vectors-logic"
 182     "math-vectors-shuffle"
 183     "math-vectors-misc"
 184 } ;
 185
 186 ABOUT: "math-vectors"
 187
 188 HELP: vneg
 189 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
 190 { $description "Negates each element of " { $snippet "u" } "." } ;
 191
 192 HELP: vabs
 193 { $values { "u" "a sequence of numbers" } { "v" "a sequence of non-negative real numbers" } }
 194 { $description "Takes the absolute value of each element of " { $snippet "u" } "." } ;
 195
 196 HELP: vsqrt
 197 { $values { "u" "a sequence of non-negative real numbers" } { "v" "a sequence of non-negative real numbers" } }
 198 { $description "Takes the square root of each element of " { $snippet "u" } "." }
 199 { $warning "For performance reasons, this does not work with negative inputs, unlike " { $link sqrt } "." } ;
 200
 201 HELP: vfloor
 202 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } }
 203 { $description "Takes the " { $link floor } " of each element of " { $snippet "u" } "." } ;
 204
 205 HELP: vceiling
 206 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } }
 207 { $description "Takes the " { $link ceiling } " of each element of " { $snippet "u" } "." } ;
 208
 209 HELP: vtruncate
 210 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } }
 211 { $description "Truncates each element of " { $snippet "u" } "." } ;
 212
 213 HELP: n+v
 214 { $values { "n" "a number" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 215 { $description "Adds " { $snippet "n" } " to each element of " { $snippet "u" } "." } ;
 216
 217 HELP: v+n
 218 { $values { "u" "a sequence of numbers" } { "n" "a number" } { "w" "a sequence of numbers" } }
 219 { $description "Adds " { $snippet "n" } " to each element of " { $snippet "u" } "." } ;
 220
 221 HELP: n-v
 222 { $values { "n" "a number" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 223 { $description "Subtracts each element of " { $snippet "u" } " from " { $snippet "n" } "." } ;
 224
 225 HELP: v-n
 226 { $values { "u" "a sequence of numbers" } { "n" "a number" } { "w" "a sequence of numbers" } }
 227 { $description "Subtracts " { $snippet "n" } " from each element of " { $snippet "u" } "." } ;
 228
 229 HELP: n*v
 230 { $values { "n" "a number" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 231 { $description "Multiplies each element of " { $snippet "u" } " by " { $snippet "n" } "." } ;
 232
 233 HELP: v*n
 234 { $values { "u" "a sequence of numbers" } { "n" "a number" } { "w" "a sequence of numbers" } }
 235 { $description "Multiplies each element of " { $snippet "u" } " by " { $snippet "n" } "." } ;
 236
 237 HELP: n/v
 238 { $values { "n" "a number" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 239 { $description "Divides " { $snippet "n" } " by each element of " { $snippet "u" } "." }
 240 { $errors "May throw an error if a division by zero occurs; see " { $link "division-by-zero" } "." } ;
 241
 242 HELP: v/n
 243 { $values { "u" "a sequence of numbers" } { "n" "a number" } { "w" "a sequence of numbers" } }
 244 { $description "Divides each element of " { $snippet "u" } " by " { $snippet "n" } "." }
 245 { $errors "May throw an error if a division by zero occurs; see " { $link "division-by-zero" } "." } ;
 246
 247 HELP: v+
 248 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 249 { $description "Adds " { $snippet "u" } " and " { $snippet "v" } " component-wise." } ;
 250
 251 HELP: v-
 252 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 253 { $description "Subtracts " { $snippet "v" } " from " { $snippet "u" } " component-wise." } ;
 254
 255 HELP: v+-
 256 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 257 { $description "Adds and subtracts alternate elements of " { $snippet "v" } " and " { $snippet "u" } " component-wise. Elements at even indexes are subtracted, while elements at odd indexes are added." }
 258 { $examples
 259     { $example
 260         "USING: math.vectors prettyprint ;"
 261         "{ 1 2 3 } { 2 3 2 } v+- ."
 262         "{ -1 5 1 }"
 263     }
 264 } ;
 265
 266 HELP: [v-]
 267 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 268 { $description "Subtracts " { $snippet "v" } " from " { $snippet "u" } " component-wise; any components which become negative are set to zero." } ;
 269
 270 HELP: v*
 271 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 272 { $description "Multiplies " { $snippet "u" } " and " { $snippet "v" } " component-wise." } ;
 273
 274 HELP: v/
 275 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 276 { $description "Divides " { $snippet "u" } " by " { $snippet "v" } " component-wise." }
 277 { $errors "May throw an error if a division by zero occurs; see " { $link "division-by-zero" } "." } ;
 278
 279 HELP: vmax
 280 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 281 { $description "Creates a sequence where each element is the maximum of the corresponding elements from " { $snippet "u" } " and " { $snippet "v" } "." }
 282 { $examples { $example "USING: math.vectors prettyprint ;" "{ 1 2 5 } { -7 6 3 } vmax ." "{ 1 6 5 }" } } ;
 283
 284 HELP: vmin
 285 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 286 { $description "Creates a sequence where each element is the minimum of the corresponding elements from " { $snippet "u" } " and " { $snippet "v" } "." }
 287 { $examples { $example "USING: math.vectors prettyprint ;" "{ 1 2 5 } { -7 6 3 } vmin ." "{ -7 2 3 }" } } ;
 288
 289 HELP: v.
 290 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "x" "a real number" } }
 291 { $description "Computes the dot product of two vectors." } ;
 292
 293 HELP: vs+
 294 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 295 { $description "Adds " { $snippet "u" } " and " { $snippet "v" } " component-wise with saturation." }
 296 { $examples
 297     "With saturation:"
 298     { $example
 299         "USING: alien.c-types math.vectors prettyprint specialized-arrays ;"
 300         "SPECIALIZED-ARRAY: uchar"
 301         "uchar-array{ 100 200 150 } uchar-array{ 70 70 70 } vs+ ."
 302         "uchar-array{ 170 255 220 }"
 303     }
 304     "Without saturation:"
 305     { $example
 306         "USING: alien.c-types math.vectors prettyprint specialized-arrays ;"
 307         "SPECIALIZED-ARRAY: uchar"
 308         "uchar-array{ 100 200 150 } uchar-array{ 70 70 70 } v+ ."
 309         "uchar-array{ 170 14 220 }"
 310     }
 311 } ;
 312
 313 HELP: vs-
 314 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 315 { $description "Subtracts " { $snippet "v" } " from " { $snippet "u" } " component-wise with saturation." } ;
 316
 317 HELP: vs*
 318 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
 319 { $description "Multiplies " { $snippet "u" } " and " { $snippet "v" } " component-wise with saturation." } ;
 320
 321 HELP: vbitand
 322 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 323 { $description "Takes the bitwise and of " { $snippet "u" } " and " { $snippet "v" } " component-wise." }
 324 { $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." } ;
 325
 326 HELP: vbitandn
 327 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 328 { $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" } "." }
 329 { $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." } ;
 330
 331 HELP: vbitor
 332 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 333 { $description "Takes the bitwise or of " { $snippet "u" } " and " { $snippet "v" } " component-wise." }
 334 { $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." } ;
 335
 336 HELP: vbitxor
 337 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 338 { $description "Takes the bitwise exclusive or of " { $snippet "u" } " and " { $snippet "v" } " component-wise." }
 339 { $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." } ;
 340
 341 HELP: vlshift
 342 { $values { "u" "a sequence of integers" } { "n" "a non-negative integer" } { "w" "a sequence of integers" } }
 343 { $description "Shifts each element of " { $snippet "u" } " to the left by " { $snippet "n" } " bits." }
 344 { $notes "Undefined behavior will result if " { $snippet "n" } " is negative." } ;
 345
 346 HELP: vrshift
 347 { $values { "u" "a sequence of integers" } { "n" "a non-negative integer" } { "w" "a sequence of integers" } }
 348 { $description "Shifts each element of " { $snippet "u" } " to the right by " { $snippet "n" } " bits." }
 349 { $notes "Undefined behavior will result if " { $snippet "n" } " is negative." } ;
 350
 351 HELP: hlshift
 352 { $values { "u" "a SIMD array" } { "n" "a non-negative integer" } { "w" "a SIMD array" } }
 353 { $description "Shifts the entire SIMD array to the left by " { $snippet "n" } " bytes, filling the vacated right-hand bits with zeroes. This word may only be used in a context where the compiler can statically infer that the input is a SIMD array." } ;
 354
 355 HELP: hrshift
 356 { $values { "u" "a SIMD array" } { "n" "a non-negative integer" } { "w" "a SIMD array" } }
 357 { $description "Shifts the entire SIMD array to the right by " { $snippet "n" } " bytes, filling the vacated left-hand bits with zeroes. This word may only be used in a context where the compiler can statically infer that the input is a SIMD array." } ;
 358
 359 HELP: vmerge
 360 { $values { "u" "a sequence" } { "v" "a sequence" } { "w" "a sequence" } }
 361 { $description "Creates a new sequence of the same type as and twice the length of " { $snippet "u" } " and " { $snippet "v" } " by interleaving the elements of " { $snippet "u" } " and " { $snippet "v" } "." }
 362 { $examples
 363 { $example """USING: kernel math.vectors prettyprint ;
 364
 365 { "A" "B" "C" "D" } { "1" "2" "3" "4" } vmerge ."""
 366 """{ "A" "1" "B" "2" "C" "3" "D" "4" }"""
 367 } } ;
 368
 369 HELP: (vmerge)
 370 { $values { "u" "a sequence" } { "v" "a sequence" } { "h" "a sequence" } { "t" "a sequence" } }
 371 { $description "Creates two new sequences of the same type and size as " { $snippet "u" } " and " { $snippet "v" } " by interleaving the elements of " { $snippet "u" } " and " { $snippet "v" } "." }
 372 { $notes "For hardware-supported SIMD vector types this word compiles to a single instruction per output value." }
 373 { $examples
 374 { $example """USING: kernel math.vectors prettyprint ;
 375
 376 { "A" "B" "C" "D" } { "1" "2" "3" "4" } (vmerge) [ . ] bi@"""
 377 """{ "A" "1" "B" "2" }
 378 { "C" "3" "D" "4" }"""
 379 } } ;
 380
 381 HELP: (vmerge-head)
 382 { $values { "u" "a sequence" } { "v" "a sequence" } { "h" "a sequence" } }
 383 { $description "Creates a new sequence of the same type and size as " { $snippet "u" } " and " { $snippet "v" } " by interleaving the elements from the first half of " { $snippet "u" } " and " { $snippet "v" } "." }
 384 { $notes "For hardware-supported SIMD vector types this word compiles to a single instruction." }
 385 { $examples
 386 { $example """USING: kernel math.vectors prettyprint ;
 387
 388 { "A" "B" "C" "D" } { "1" "2" "3" "4" } (vmerge-head) ."""
 389 """{ "A" "1" "B" "2" }"""
 390 } } ;
 391
 392 HELP: (vmerge-tail)
 393 { $values { "u" "a sequence" } { "v" "a sequence" } { "t" "a sequence" } }
 394 { $description "Creates a new sequence of the same type and size as " { $snippet "u" } " and " { $snippet "v" } " by interleaving the elements from the tail half of " { $snippet "u" } " and " { $snippet "v" } "." }
 395 { $notes "For hardware-supported SIMD vector types this word compiles to a single instruction." }
 396 { $examples
 397 { $example """USING: kernel math.vectors prettyprint ;
 398
 399 { "A" "B" "C" "D" } { "1" "2" "3" "4" } (vmerge-tail) ."""
 400 """{ "C" "3" "D" "4" }"""
 401 } } ;
 402
 403 { vmerge (vmerge) (vmerge-head) (vmerge-tail) } related-words
 404
 405 HELP: vbroadcast
 406 { $values { "u" "a SIMD array" } { "n" "a non-negative integer" } { "v" "a SIMD array" } }
 407 { $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" } "." }
 408 { $examples
 409     { $example
 410         "USING: alien.c-types math.vectors math.vectors.simd" "prettyprint ;"
 411         "int-4{ 69 42 911 13 } 2 vbroadcast ."
 412         "int-4{ 911 911 911 911 }"
 413     }
 414 } ;
 415
 416 HELP: vshuffle
 417 { $values { "u" "a SIMD array" } { "perm" "an array of integers, or a byte-array" } { "v" "a SIMD array" } }
 418 { $description "Permutes the elements of a SIMD array. Duplicate entries are allowed in the permutation. The " { $snippet "perm" } " argument can have one of two forms:"
 419 { $list
 420 { "A literal array of integers of the same length as the vector. This will perform a static, elementwise shuffle." }
 421 { "A byte array or SIMD vector of the same byte length as the vector. This will perform a variable bytewise shuffle." }
 422 } }
 423 { $examples
 424     { $example
 425         "USING: alien.c-types math.vectors math.vectors.simd" "prettyprint ;"
 426         "int-4{ 69 42 911 13 } { 1 3 2 3 } vshuffle ."
 427         "int-4{ 42 13 911 13 }"
 428     }
 429     { $example
 430         "USING: alien.c-types combinators math.vectors math.vectors.simd"
 431         "namespaces prettyprint prettyprint.config ;"
 432         "IN: scratchpad"
 433         ""
 434         ": endian-swap ( size -- vector )"
 435         "    {"
 436         "        { 1 [ uchar-16{ 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 } ] }"
 437         "        { 2 [ uchar-16{ 1 0 3 2 5 4 7 6 9 8 11 10 13 12 15 14 } ] }"
 438         "        { 4 [ uchar-16{ 3 2 1 0 7 6 5 4 11 10 9 8 15 14 13 12 } ] }"
 439         "    } case ;"
 440         ""
 441         "int-4{ 0x11223344 0x11223344 0x11223344 0x11223344 }"
 442         "4 endian-swap vshuffle"
 443         "16 number-base [ . ] with-variable"
 444         """int-4{
 445     0x44332211
 446     0x44332211
 447     0x44332211
 448     0x44332211
 449 }"""
 450     }
 451 } ;
 452
 453 HELP: norm-sq
 454 { $values { "v" "a sequence of numbers" } { "x" "a non-negative real number" } }
 455 { $description "Computes the squared length of a mathematical vector." } ;
 456
 457 HELP: norm
 458 { $values { "v" "a sequence of numbers" } { "x" "a non-negative real number" } }
 459 { $description "Computes the length of a mathematical vector." } ;
 460
 461 HELP: normalize
 462 { $values { "u" "a sequence of numbers, not all zero" } { "v" "a sequence of numbers" } }
 463 { $description "Outputs a vector with the same direction as " { $snippet "u" } " but length 1." } ;
 464
 465 HELP: distance
 466 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "x" "a non-negative real number" } }
 467 { $description "Outputs the Euclidean distance between two vectors." } ;
 468
 469 HELP: set-axis
 470 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "axis" "a sequence of 0/1" } { "w" "a sequence of numbers" } }
 471 { $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." }
 472 { $examples { $example "USING: math.vectors prettyprint ;" "{ 1 2 3 } { 4 5 6 } { 0 1 0 } set-axis ." "{ 1 5 3 }" } } ;
 473
 474 HELP: v<
 475 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of booleans" } }
 476 { $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." }
 477 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean results when using SIMD types." } ;
 478
 479 HELP: v<=
 480 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of booleans" } }
 481 { $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." }
 482 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean results when using SIMD types." } ;
 483
 484 HELP: v=
 485 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of booleans" } }
 486 { $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." }
 487 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean results when using SIMD types." } ;
 488
 489 HELP: v>
 490 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of booleans" } }
 491 { $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." }
 492 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean results when using SIMD types." } ;
 493
 494 HELP: v>=
 495 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of booleans" } }
 496 { $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." }
 497 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean results when using SIMD types." } ;
 498
 499 HELP: vunordered?
 500 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of booleans" } }
 501 { $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." }
 502 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean results when using SIMD types." } ;
 503
 504 HELP: vand
 505 { $values { "u" "a sequence of booleans" } { "v" "a sequence of booleans" } { "w" "a sequence of booleans" } }
 506 { $description "Takes the logical AND of each corresponding element of " { $snippet "u" } " and " { $snippet "v" } "." }
 507 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean inputs and results when using SIMD types." } ;
 508
 509 HELP: vandn
 510 { $values { "u" "a sequence of booleans" } { "v" "a sequence of booleans" } { "w" "a sequence of booleans" } }
 511 { $description "Takes the logical AND-NOT of each corresponding element of " { $snippet "u" } " and " { $snippet "v" } ", where " { $snippet "x AND-NOT y" } " is defined as " { $snippet "NOT(x) AND y" } "." }
 512 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean inputs and results when using SIMD types." } ;
 513
 514 HELP: vor
 515 { $values { "u" "a sequence of booleans" } { "v" "a sequence of booleans" } { "w" "a sequence of booleans" } }
 516 { $description "Takes the logical OR of each corresponding element of " { $snippet "u" } " and " { $snippet "v" } "." }
 517 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean inputs and results when using SIMD types." } ;
 518
 519 HELP: vxor
 520 { $values { "u" "a sequence of booleans" } { "v" "a sequence of booleans" } { "w" "a sequence of booleans" } }
 521 { $description "Takes the logical XOR of each corresponding element of " { $snippet "u" } " and " { $snippet "v" } "." }
 522 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean inputs and results when using SIMD types." } ;
 523
 524 HELP: vnot
 525 { $values { "u" "a sequence of booleans" } { "w" "a sequence of booleans" } }
 526 { $description "Takes the logical NOT of each element of " { $snippet "u" } "." }
 527 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean inputs and results when using SIMD types." } ;
 528
 529 HELP: v?
 530 { $values { "mask" "a sequence of booleans" } { "true" "a sequence of numbers" } { "false" "a sequence of numbers" } { "result" "a sequence of numbers" } }
 531 { $description "Creates a new sequence by selecting elements from the " { $snippet "true" } " and " { $snippet "false" } " sequences based on whether the corresponding bits of the " { $snippet "mask" } " sequence are set or not." }
 532 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean inputs and results when using SIMD types." } ;
 533
 534 HELP: vif
 535 { $values { "mask" "a sequence of booleans" } { "true-quot" { $quotation "( -- vector )" } } { "false-quot" { $quotation "( -- vector )" } } { "result" "a sequence" } }
 536 { $description "If all of the elements of " { $snippet "mask" } " are true, " { $snippet "true-quot" } " is called and its output value returned. If all of the elements of " { $snippet "mask" } " are false, " { $snippet "false-quot" } " is called and its output value returned. Otherwise, both quotations are called and " { $snippet "mask" } " is used to select elements from each output as with " { $link v? } "." }
 537 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean inputs and results when using SIMD types."
 538 $nl
 539 "For most conditional SIMD code, unless a case is exceptionally expensive to compute, it is usually most efficient to just compute all cases and blend them with " { $link v? } " instead of using " { $snippet "vif" } "." } ;
 540
 541 { v? vif } related-words
 542
 543 HELP: vany?
 544 { $values { "v" "a sequence of booleans" } { "?" "a boolean" } }
 545 { $description "Returns true if any element of " { $snippet "v" } " is true." }
 546 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean inputs when using SIMD types." } ;
 547
 548 HELP: vall?
 549 { $values { "v" "a sequence of booleans" } { "?" "a boolean" } }
 550 { $description "Returns true if every element of " { $snippet "v" } " is true." }
 551 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean inputs when using SIMD types." } ;
 552
 553 HELP: vnone?
 554 { $values { "v" "a sequence of booleans" } { "?" "a boolean" } }
 555 { $description "Returns true if every element of " { $snippet "v" } " is false." }
 556 { $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean inputs when using SIMD types." } ;
 557
 558 { 2map v+ v- v* v/ } related-words
 559
 560 { 2reduce v. } related-words
 561
 562 { vs+ vs- vs* } related-words
 563
 564 { v< v<= v= v> v>= vunordered? vand vor vxor vnot vany? vall? vnone? v? } related-words
 565
 566 { vbitand vbitandn vbitor vbitxor vbitnot } related-words