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