basis/math/vectors/vectors-docs.factor

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