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-shuffle" "Vector shuffling, packing, and unpacking"
+{ $notes
+"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."
+}
+$nl
+{ $subsections
+ vshuffle
+ vbroadcast
+ hlshift
+ hrshift
+ vmerge
+ (vmerge)
+}
+"See the " { $vocab-link "math.vectors.conversion" } " vocabulary for packing, unpacking, and converting vectors." ;
-ARTICLE: "math-vectors-logic" "Vector componentwise logic"
+ARTICLE: "math-vectors-logic" "Vector component- and bit-wise logic"
+{ $notes
"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
+ vnot
+ v?
+ vif
+}
"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 }
"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
-"Also note that providing SIMD vectors with element values other than true or false as inputs to logical or test operations is undefined."
+"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
-"These notes apply to the output of the following element comparison words: "
+"This applies to the output of the following element comparison words:"
{ $list
{ $link v< }
{ $link v<= }
{ $link v> }
{ $link vunordered? }
}
-"They likewise apply to the " { $snippet "mask" } " argument of " { $link v? } " and the inputs and outputs of the following element logic words:"
+"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 vxor }
{ $link vnot }
}
-"Finally, the inputs of these vector test words is affected:"
+"Finally, this applies to the inputs of these vector test words:"
{ $list
{ $link vall? }
{ $link vany? }
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."
-{ $subsection "math-vectors-arithmetic" }
-{ $subsection "math-vectors-logic" }
-{ $subsection "math-vectors-misc" } ;
+{ $subsections
+ "math-vectors-arithmetic"
+ "math-vectors-logic"
+ "math-vectors-shuffle"
+ "math-vectors-misc"
+} ;
ABOUT: "math-vectors"
{ $description "Truncates each element of " { $snippet "u" } "." } ;
HELP: n+v
-{ $values { "n" "a number" } { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
+{ $values { "n" "a number" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
{ $description "Adds " { $snippet "n" } " to each element of " { $snippet "u" } "." } ;
HELP: v+n
-{ $values { "u" "a sequence of numbers" } { "n" "a number" } { "v" "a sequence of numbers" } }
+{ $values { "u" "a sequence of numbers" } { "n" "a number" } { "w" "a sequence of numbers" } }
{ $description "Adds " { $snippet "n" } " to each element of " { $snippet "u" } "." } ;
HELP: n-v
-{ $values { "n" "a number" } { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
+{ $values { "n" "a number" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
{ $description "Subtracts each element of " { $snippet "u" } " from " { $snippet "n" } "." } ;
HELP: v-n
-{ $values { "u" "a sequence of numbers" } { "n" "a number" } { "v" "a sequence of numbers" } }
+{ $values { "u" "a sequence of numbers" } { "n" "a number" } { "w" "a sequence of numbers" } }
{ $description "Subtracts " { $snippet "n" } " from each element of " { $snippet "u" } "." } ;
HELP: n*v
-{ $values { "n" "a number" } { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
+{ $values { "n" "a number" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
{ $description "Multiplies each element of " { $snippet "u" } " by " { $snippet "n" } "." } ;
HELP: v*n
-{ $values { "u" "a sequence of numbers" } { "n" "a number" } { "v" "a sequence of numbers" } }
+{ $values { "u" "a sequence of numbers" } { "n" "a number" } { "w" "a sequence of numbers" } }
{ $description "Multiplies each element of " { $snippet "u" } " by " { $snippet "n" } "." } ;
HELP: n/v
-{ $values { "n" "a number" } { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
+{ $values { "n" "a number" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
{ $description "Divides " { $snippet "n" } " by each element of " { $snippet "u" } "." }
{ $errors "May throw an error if a division by zero occurs; see " { $link "division-by-zero" } "." } ;
HELP: v/n
-{ $values { "u" "a sequence of numbers" } { "n" "a number" } { "v" "a sequence of numbers" } }
+{ $values { "u" "a sequence of numbers" } { "n" "a number" } { "w" "a sequence of numbers" } }
{ $description "Divides each element of " { $snippet "u" } " by " { $snippet "n" } "." }
{ $errors "May throw an error if a division by zero occurs; see " { $link "division-by-zero" } "." } ;
HELP: v+-
{ $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
-{ $description "Adds and subtracts alternate elements of " { $snippet "v" } " and " { $snippet "u" } " component-wise." }
+{ $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." }
{ $examples
{ $example
"USING: math.vectors prettyprint ;"
HELP: hlshift
{ $values { "u" "a SIMD array" } { "n" "a non-negative integer" } { "w" "a SIMD array" } }
-{ $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." } ;
+{ $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." } ;
HELP: hrshift
{ $values { "u" "a SIMD array" } { "n" "a non-negative integer" } { "w" "a SIMD array" } }
-{ $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." } ;
+{ $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." } ;
+
+HELP: vmerge
+{ $values { "u" "a sequence" } { "v" "a sequence" } { "w" "a sequence" } }
+{ $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" } "." }
+{ $examples
+{ $example """USING: kernel math.vectors prettyprint ;
+
+{ "A" "B" "C" "D" } { "1" "2" "3" "4" } vmerge ."""
+"""{ "A" "1" "B" "2" "C" "3" "D" "4" }"""
+} } ;
+
+HELP: (vmerge)
+{ $values { "u" "a sequence" } { "v" "a sequence" } { "h" "a sequence" } { "t" "a sequence" } }
+{ $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" } "." }
+{ $notes "For hardware-supported SIMD vector types this word compiles to a single instruction per output value." }
+{ $examples
+{ $example """USING: kernel math.vectors prettyprint ;
+
+{ "A" "B" "C" "D" } { "1" "2" "3" "4" } (vmerge) [ . ] bi@"""
+"""{ "A" "1" "B" "2" }
+{ "C" "3" "D" "4" }"""
+} } ;
+
+HELP: (vmerge-head)
+{ $values { "u" "a sequence" } { "v" "a sequence" } { "h" "a sequence" } }
+{ $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" } "." }
+{ $notes "For hardware-supported SIMD vector types this word compiles to a single instruction." }
+{ $examples
+{ $example """USING: kernel math.vectors prettyprint ;
+
+{ "A" "B" "C" "D" } { "1" "2" "3" "4" } (vmerge-head) ."""
+"""{ "A" "1" "B" "2" }"""
+} } ;
+
+HELP: (vmerge-tail)
+{ $values { "u" "a sequence" } { "v" "a sequence" } { "t" "a sequence" } }
+{ $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" } "." }
+{ $notes "For hardware-supported SIMD vector types this word compiles to a single instruction." }
+{ $examples
+{ $example """USING: kernel math.vectors prettyprint ;
+
+{ "A" "B" "C" "D" } { "1" "2" "3" "4" } (vmerge-tail) ."""
+"""{ "C" "3" "D" "4" }"""
+} } ;
+
+{ vmerge (vmerge) (vmerge-head) (vmerge-tail) } related-words
HELP: vbroadcast
{ $values { "u" "a SIMD array" } { "n" "a non-negative integer" } { "v" "a SIMD array" } }
{ $examples
{ $example
"USING: alien.c-types math.vectors math.vectors.simd" "prettyprint ;"
- "SIMD: int"
"int-4{ 69 42 911 13 } 2 vbroadcast ."
"int-4{ 911 911 911 911 }"
}
} ;
HELP: vshuffle
-{ $values { "u" "a SIMD array" } { "perm" "an array of integers" } { "v" "a SIMD array" } }
-{ $description "Permutes the elements of a SIMD array. Duplicate entries are allowed in the permutation." }
+{ $values { "u" "a SIMD array" } { "perm" "an array of integers, or a byte-array" } { "v" "a SIMD array" } }
+{ $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:"
+{ $list
+{ "A literal array of integers of the same length as the vector. This will perform a static, elementwise shuffle." }
+{ "A byte array or SIMD vector of the same byte length as the vector. This will perform a variable bytewise shuffle." }
+} }
{ $examples
{ $example
"USING: alien.c-types math.vectors math.vectors.simd" "prettyprint ;"
- "SIMD: int"
"int-4{ 69 42 911 13 } { 1 3 2 3 } vshuffle ."
"int-4{ 42 13 911 13 }"
}
+ { $example
+ "USING: alien.c-types combinators math.vectors math.vectors.simd"
+ "namespaces prettyprint prettyprint.config ;"
+ "IN: scratchpad"
+ ""
+ ": endian-swap ( size -- vector )"
+ " {"
+ " { 1 [ uchar-16{ 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 } ] }"
+ " { 2 [ uchar-16{ 1 0 3 2 5 4 7 6 9 8 11 10 13 12 15 14 } ] }"
+ " { 4 [ uchar-16{ 3 2 1 0 7 6 5 4 11 10 9 8 15 14 13 12 } ] }"
+ " } case ;"
+ ""
+ "int-4{ 0x11223344 0x11223344 0x11223344 0x11223344 }"
+ "4 endian-swap vshuffle"
+ "16 number-base [ . ] with-variable"
+ """int-4{
+ 0x44332211
+ 0x44332211
+ 0x44332211
+ 0x44332211
+}"""
+ }
} ;
HELP: norm-sq
{ $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean inputs and results when using SIMD types." } ;
HELP: v?
-{ $values { "mask" "a sequence of booleans" } { "true" "a sequence of numbers" } { "false" "a sequence of numbers" } { "w" "a sequence of numbers" } }
+{ $values { "mask" "a sequence of booleans" } { "true" "a sequence of numbers" } { "false" "a sequence of numbers" } { "result" "a sequence of numbers" } }
{ $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." }
{ $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean inputs and results when using SIMD types." } ;
+HELP: vif
+{ $values { "mask" "a sequence of booleans" } { "true-quot" { $quotation "( -- vector )" } } { "false-quot" { $quotation "( -- vector )" } } { "result" "a sequence" } }
+{ $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? } "." }
+{ $notes "See " { $link "math-vectors-simd-logic" } " for notes on dealing with vector boolean inputs and results when using SIMD types."
+$nl
+"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" } "." } ;
+
+{ v? vif } related-words
+
HELP: vany?
{ $values { "v" "a sequence of booleans" } { "?" "a boolean" } }
{ $description "Returns true if any element of " { $snippet "v" } " is true." }
projects / factor.git / blobdiff