basis/math/vectors/vectors-docs.factor

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