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