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