ARTICLE: "math-vectors-arithmetic" "Vector arithmetic"
"Vector/vector binary operations:"
- { $subsection v+ }
- { $subsection v- }
- { $subsection v+- }
- { $subsection v* }
- { $subsection v/ }
+ { $subsections
+ v+
+ v-
+ v+-
+ v*
+ v/
+ }
"Vector unary operations:"
- { $subsection vneg }
- { $subsection vabs }
- { $subsection vsqrt }
- { $subsection vfloor }
- { $subsection vceiling }
- { $subsection vtruncate }
+ { $subsections
+ vneg
+ vabs
+ vsqrt
+ vfloor
+ vceiling
+ vtruncate
+ }
"Vector/scalar and scalar/vector binary operations:"
- { $subsection vneg }
- { $subsection v*n }
- { $subsection n*v }
- { $subsection v/n }
- { $subsection n/v }
- { $subsection v+n }
- { $subsection n+v }
- { $subsection v-n }
- { $subsection n-v }
+ { $subsections
+ vneg
+ v*n
+ n*v
+ v/n
+ n/v
+ v+n
+ n+v
+ v-n
+ n-v
+ }
"Saturated arithmetic (only on " { $link "specialized-arrays" } "):"
- { $subsection vs+ }
- { $subsection vs- }
- { $subsection vs* }
+ { $subsections
+ vs+
+ vs-
+ vs*
+ }
"Inner product and norm:"
- { $subsection v. }
- { $subsection norm }
- { $subsection norm-sq }
- { $subsection normalize }
+ { $subsections
+ v.
+ norm
+ norm-sq
+ normalize
+ }
"Comparing entire vectors:"
- { $subsection distance }
- { $subsection v~ } ;
+ { $subsections
+ distance
+ v~
+ } ;
ARTICLE: "math-vectors-logic" "Vector componentwise logic"
+"See " { $link "math-vectors-simd-logic" } " for notes about using comparison and logical operations with SIMD vector types."
+$nl
"Element comparisons:"
- { $subsection v< }
- { $subsection v<= }
- { $subsection v= }
- { $subsection v>= }
- { $subsection v> }
- { $subsection vunordered? }
- { $subsection vmax }
- { $subsection vmin }
- { $subsection vsupremum }
- { $subsection vinfimum }
+ { $subsections
+ v<
+ v<=
+ v=
+ v>=
+ v>
+ vunordered?
+ vmax
+ vmin
+ vsupremum
+ vinfimum
+ }
"Bitwise operations:"
- { $subsection vbitand }
- { $subsection vbitandn }
- { $subsection vbitor }
- { $subsection vbitxor }
- { $subsection vbitnot }
- { $subsection vlshift }
- { $subsection vrshift }
+ { $subsections
+ vbitand
+ vbitandn
+ vbitor
+ vbitxor
++ vbitnot
+ vlshift
+ vrshift
+ }
"Element logical operations:"
- { $subsection vand }
- { $subsection vandn }
- { $subsection vor }
- { $subsection vxor }
- { $subsection vnot }
- { $subsection v? }
+ { $subsections
+ vand
++ vandn
+ vor
+ vxor
- vmask
++ vnot
+ v?
+ }
+"Entire vector tests:"
- { $subsection vall? }
- { $subsection vany? }
- { $subsection vnone? }
++{ $subsections
++ vall?
++ vany?
++ vnone?
++}
"Element shuffling:"
- { $subsection vshuffle } ;
+ { $subsections vshuffle } ;
ARTICLE: "math-vectors-misc" "Miscellaneous vector functions"
- { $subsection trilerp }
- { $subsection bilerp }
- { $subsection vlerp }
- { $subsection vnlerp }
- { $subsection vbilerp } ;
+ { $subsections
+ trilerp
+ bilerp
+ vlerp
+ vnlerp
+ vbilerp
+ } ;
+ARTICLE: "math-vectors-simd-logic" "Componentwise logic with SIMD vectors"
+"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 set bits in its payload:"
+{ $example
+"""USING: math.vectors math.vectors.simd prettyprint ;
+FROM: alien.c-types => float ;
+SIMD: float
+
+float-4{ 1.0 2.0 3.0 0/0. } float-4{ 1.0 -2.0 3.0 0/0. } v= ."""
+"""float-4{ NAN: fffffe0000000 0.0 NAN: fffffe0000000 0.0 }"""
+}
+"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):"
+{ $example
+"""USING: math.vectors math.vectors.simd prettyprint alien.c-types ;
+SIMD: int
+SIMD: uchar
+
+int-4{ 1 2 3 0 } int-4{ 1 -2 3 4 } v=
+uchar-16{ 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 }
+uchar-16{ 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 } v<
+[ . ] bi@"""
+"""int-4{ -1 0 -1 0 }
+uchar-16{ 255 255 255 255 255 255 255 255 0 0 0 0 0 0 0 0 }"""
+}
+"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:"
+{ $example
+"""USING: math.vectors math.vectors.simd prettyprint alien.c-types ;
+SIMD: int
+
+int-4{ f f t f } ."""
+"""int-4{ 0 0 -1 0 }""" }
+"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."
+$nl
+"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."
+$nl
+"This applies to the output of the following element comparison words: "
+{ $list
+{ $link v< }
+{ $link v<= }
+{ $link v= }
+{ $link v>= }
+{ $link v> }
+{ $link vunordered? }
+}
+"This likewise applies to the " { $snippet "mask" } " argument of " { $link v? } " and to the inputs and outputs of the following element logic words:"
+{ $list
+{ $link vand }
+{ $link vandn }
+{ $link vor }
+{ $link vxor }
+{ $link vnot }
+}
+"Finally, this applies to the inputs of these vector test words:"
+{ $list
+{ $link vall? }
+{ $link vany? }
+{ $link vnone? }
+} ;
ARTICLE: "math-vectors" "Vector operations"
"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."
projects / factor.git / commitdiff