1 USING: help.markup help.syntax math math.functions sequences ;
4 ARTICLE: "math-vectors-arithmetic" "Vector arithmetic"
5 "Vector/vector binary operations:"
11 "Vector unary operations:"
15 { $subsection vfloor }
16 { $subsection vceiling }
17 { $subsection vtruncate }
18 "Vector/scalar and scalar/vector binary operations:"
28 "Saturated arithmetic (only on " { $link "specialized-arrays" } "):"
32 "Inner product and norm:"
35 { $subsection norm-sq }
36 { $subsection normalize }
37 "Comparing entire vectors:"
38 { $subsection distance }
41 ARTICLE: "math-vectors-logic" "Vector componentwise logic"
42 "Element comparisons:"
48 { $subsection vunordered? }
51 { $subsection vsupremum }
52 { $subsection vinfimum }
54 { $subsection vbitand }
55 { $subsection vbitandn }
56 { $subsection vbitor }
57 { $subsection vbitxor }
58 { $subsection vlshift }
59 { $subsection vrshift }
60 "Element logical operations:"
65 "Entire vector tests:"
68 { $subsection vnone? }
70 { $subsection vshuffle } ;
72 ARTICLE: "math-vectors-misc" "Miscellaneous vector functions"
73 { $subsection trilerp }
74 { $subsection bilerp }
76 { $subsection vnlerp }
77 { $subsection vbilerp } ;
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" } ;
89 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
90 { $description "Negates each element of " { $snippet "u" } "." } ;
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" } "." } ;
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 } "." } ;
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" } "." } ;
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" } "." } ;
110 { $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } }
111 { $description "Truncates each element of " { $snippet "u" } "." } ;
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" } "." } ;
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" } "." } ;
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" } "." } ;
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" } "." } ;
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" } "." } ;
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" } "." } ;
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" } "." } ;
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" } "." } ;
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." } ;
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." } ;
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." }
160 "USING: math.vectors prettyprint ;"
161 "{ 1 2 3 } { 2 3 2 } 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." } ;
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." } ;
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" } "." } ;
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 }" } } ;
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 }" } } ;
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." } ;
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." }
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 }"
204 "Without saturation:"
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 }"
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." } ;
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." } ;
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." } ;
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." } ;
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." } ;
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." } ;
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." } ;
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." } ;
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." } ;
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." } ;
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" } "." }
264 "USING: alien.c-types math.vectors math.vectors.simd" "prettyprint ;"
266 "int-4{ 69 42 911 13 } 2 vbroadcast ."
267 "int-4{ 911 911 911 911 }"
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." }
276 "USING: alien.c-types math.vectors math.vectors.simd" "prettyprint ;"
278 "int-4{ 69 42 911 13 } { 1 3 2 3 } vshuffle ."
279 "int-4{ 42 13 911 13 }"
284 { $values { "v" "a sequence of numbers" } { "x" "a non-negative real number" } }
285 { $description "Computes the squared length of a mathematical vector." } ;
288 { $values { "v" "a sequence of numbers" } { "x" "a non-negative real number" } }
289 { $description "Computes the length of a mathematical vector." } ;
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." } ;
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." } ;
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 }" } } ;
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." } ;
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." } ;
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." } ;
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." } ;
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." } ;
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." } ;
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" } "." } ;
333 { $values { "u" "a sequence of booleans" } { "v" "a sequence of booleans" } { "w" "a sequence of booleans" } }
334 { $description "Takes the logical OR of each corresponding element of " { $snippet "u" } " and " { $snippet "v" } "." } ;
337 { $values { "u" "a sequence of booleans" } { "v" "a sequence of booleans" } { "w" "a sequence of booleans" } }
338 { $description "Takes the logical XOR of each corresponding element of " { $snippet "u" } " and " { $snippet "v" } "." } ;
341 { $values { "u" "a sequence of booleans" } { "w" "a sequence of booleans" } }
342 { $description "Takes the logical NOT of each element of " { $snippet "u" } "." } ;
345 { $values { "mask" "a sequence of booleans" } { "true" "a sequence of numbers" } { "false" "a sequence of numbers" } { "w" "a sequence of numbers" } }
346 { $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." } ;
349 { $values { "v" "a sequence of booleans" } { "?" "a boolean" } }
350 { $description "Returns true if any element of " { $snippet "v" } " is true." } ;
353 { $values { "v" "a sequence of booleans" } { "?" "a boolean" } }
354 { $description "Returns true if every element of " { $snippet "v" } " is true." } ;
357 { $values { "v" "a sequence of booleans" } { "?" "a boolean" } }
358 { $description "Returns true if every element of " { $snippet "v" } " is false." } ;
360 { 2map v+ v- v* v/ } related-words
362 { 2reduce v. } related-words
364 { vs+ vs- vs* } related-words
366 { v< v<= v= v> v>= vunordered? vand vor vxor vnot vany? vall? vnone? v? } related-words
368 { vbitand vbitandn vbitor vbitxor vbitnot } related-words