README
¶
vecf32 
Package vecf32 provides common functions and methods for slices of float32
Installation
go get -u github.com/chewxy/vecf32
Dependencies
This package math32. For testing this package uses testify/assert, which is licenced with a MIT/BSD-like licence
Build Tags
The point of this package is to provide operations that are accelerated by SIMD. However, this pakcage by default does not use SIMD. To use SIMD, build tags must be used. The supported build tags are sse and avx. Here's an example on how to use them:
FAQ
Why are there so many a = a[:len(a)] lines?
This is mainly done to eliminate bounds checking in a loop. The idea is the bounds of the slice is checked early on, and if need be, panics early. Then if everything is normal, there won't be bounds checking while in the loop.
To check for boundschecking and bounds check elimination (an amazing feature that landed in Go 1.7), compile your programs with -gcflags='-d=ssa/check_bce/debug=1'.
Contributing
Contributions are welcome. The typical process works like this:
- File an issue on the topic you want to contribute
- Fork this repo
- Add your contribution
- Make a pull request
- The pull request will be merged once tests pass, and code reviewed.
Pull Requests
This package is very well tested. Please ensure tests are written if any new features are added. If bugs are fixed, please add the bugs to the tests as well.
Licence
Package vecf32 is licenced under the MIT licence.
Documentation
¶
Overview ¶
Package vecf32 provides common functions and methods for slices of float32.
Name ¶
In the days of yore, scientists who computed with computers would use arrays to represent vectors, each value representing magnitude and/or direction. Then came the C++ Standard Templates Library, which sought to provide this data type in the standard library. Now, everyone conflates a term "vector" with dynamic arrays.
In the C++ book, Bjarne Stroustrup has this to say:
One could argue that valarray should have been called vector because is is a traditional mathematical vector and that vector should have been called array. However, this is not the way that the terminology evolved. A valarray is a vector optimized for numeric computation; a vector is a flexible container designed for holding and manipulating objects of a wide variety of types; and an array is a low-level built-in type
Go has a better name for representing dynamically allocated arrays of any type - "slice". However, "slice" is both a noun and verb and many libraries that I use already use "slice"-as-a-verb as a name, so I had to settle for the second best name: "vector".
It should be noted that while the names used in this package were definitely mathematically inspired, they bear only little resemblance the actual mathematical operations performed.
Naming Convention ¶
The names of the operations assume you're working with slices of float32s. Hence `Add` performs elementwise addition between two []float32.
Operations between []float32 and float32 are also supported, however they are differently named. Here are the equivalents:
+------------------------+--------------------------------------------+ | []float32-[]float32 Op | []float32-float32 Op | +------------------------+--------------------------------------------+ | Add(a, b []float32) | Trans(a float32, b []float32) | | Sub(a, b []float32) | TransInv/TransInvR(a float32, b []float32) | | Mul(a, b []float32) | Scale(a float32, b []float32) | | Div(a, b []float32) | ScaleInv/ScaleInvR(a float32, b []float32) | | Pow(a, b []float32) | PowOf/PowOfR(a float32, b []float32) | +------------------------+--------------------------------------------+
You may note that for the []float64 - float64 binary operations, the scalar (float64) is always the first operand. In operations that are not commutative, an additional function is provided, suffixed with "R" (for reverse)
Range Check and BCE ¶
This package does not provide range checking. If indices are out of range, the functions will panic. This package should play well with BCE.
TODO(anyone): provide SIMD vectorization for Incr and []float32-float64 functions Pull requests accepted
Index ¶
- func Add(a, b []float32)
- func Argmax(a []float32) int
- func Argmin(a []float32) int
- func Div(a, b []float32)
- func IncrAdd(a, b, incr []float32)
- func IncrDiv(a, b, incr []float32)
- func IncrMod(a, b, incr []float32)
- func IncrMul(a, b, incr []float32)
- func IncrPow(a, b, incr []float32)
- func IncrPowOf(a []float32, s float32, incr []float32)
- func IncrPowOfR(a []float32, s float32, incr []float32)
- func IncrScale(a []float32, s float32, incr []float32)
- func IncrScaleInv(a []float32, s float32, incr []float32)
- func IncrScaleInvR(a []float32, s float32, incr []float32)
- func IncrSub(a, b, incr []float32)
- func IncrTrans(a []float32, s float32, incr []float32)
- func IncrTransInv(a []float32, s float32, incr []float32)
- func IncrTransInvR(a []float32, s float32, incr []float32)
- func InvSqrt(a []float32)
- func Max(a, b []float32)
- func MaxOf(a []float32) (retVal float32)
- func Min(a, b []float32)
- func MinOf(a []float32) (retVal float32)
- func Mod(a, b []float32)
- func Mul(a, b []float32)
- func Pow(a, b []float32)
- func PowOf(a []float32, s float32)
- func PowOfR(a []float32, s float32)
- func Range(start, end int) []float32
- func Reduce(f func(a, b float32) float32, def float32, l ...float32) (retVal float32)
- func Scale(a []float32, s float32)
- func ScaleInv(a []float32, s float32)
- func ScaleInvR(a []float32, s float32)
- func Sqrt(a []float32)
- func Sub(a, b []float32)
- func Sum(a []float32) float32
- func Trans(a []float32, s float32)
- func TransInv(a []float32, s float32)
- func TransInvR(a []float32, s float32)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IncrAdd ¶
func IncrAdd(a, b, incr []float32)
IncrAdd performs a̅ + b̅ and then adds it elementwise to the incr slice
func IncrMul ¶
func IncrMul(a, b, incr []float32)
IncrMul performs a̅ × b̅ and then adds it elementwise to the incr slice
func IncrPowOf ¶
IncrPowOf performs elementwise power function and then increments the incr slice
incr += a̅ ^ s
func IncrPowOfR ¶
PowOfR performs elementwise power function below and then increments the incr slice.
incr += s ^ a̅
func IncrScale ¶
Scale multiplies all values in the slice by the scalar and then increments the incr slice
incr += a̅ * s
func IncrScaleInv ¶
IncrScaleInv divides all values in the slice by the scalar and then increments the incr slice
incr += a̅ / s
func IncrScaleInvR ¶
/ IncrScaleInvR divides all numbers in the slice by a scalar and then increments the incr slice
incr += s / a̅
func IncrSub ¶
func IncrSub(a, b, incr []float32)
IncrSub performs a̅ = b̅ and then adds it elementwise to the incr slice
func IncrTrans ¶
IncrTrans adds all the values in the slice by a scalar and then increments the incr slice
incr += a̅ + s
func IncrTransInv ¶
IncrTransInv subtracts all the values in the slice by a scalar and then increments the incr slice
incr += a̅ - s
func IncrTransInvR ¶
IncrTransInvR subtracts all the numbers in a slice from a scalar and then increments the incr slice
incr += s - a̅
func Max ¶
func Max(a, b []float32)
Max takes two slices, a̅ + b̅, and compares them elementwise. The highest value is put into a̅.
func Min ¶
func Min(a, b []float32)
Min takes two slices, a̅ + b̅ and compares them elementwise. The lowest value is put into a̅.
func ScaleInv ¶
ScaleInv divides all values in the slice by the scalar. It performs elementwise
a̅ / s
Types ¶
This section is empty.
Source Files