Documentation
¶
Overview ¶
Package vecmath holds the stateless vector and scalar maths kernels behind the expression-language vector built-ins (vsum, vmean, dot, argmax, vzscore, vnormalize, sqrt, ...). The expr closures in internal/processing only adapt arguments. The metric functions (dist, cosine, jaccard, dice, hamming, overlap) are not here: they resolve through the one linalg/metric registry.
It is a LEAF: standard library only, so internal/processing, internal/descriptor and any future caller import it without a cycle. TestVecmathImportBoundary enforces the ceiling.
Edge semantics (pinned) ¶
- Reductions (Sum, Mean, Min, Max, SD, Norm) skip NaN. An empty or all-NaN input gives NaN — Sum included, so "unanswered" never masquerades as 0. SD (ddof = 1) needs at least two valid values. Count is the number of non-NaN values.
- Dot is pairwise-complete: index i is dropped when either side is NaN. No complete pair gives NaN. Unequal lengths return a *LengthMismatchError (errors.Is ErrLengthMismatch), never NaN.
- ArgMax / ArgMin return a 0-based index; the first index wins a tie; an empty or all-NaN input returns ok == false.
- Center, ZScore and Normalize return a NEW slice (the input is never mutated, because callers bind reused per-worker buffers), keep NaN in place, and give all-NaN when the mean is undefined, the sd is zero or undefined, or the norm is zero or undefined.
- Infinities are ordinary IEEE values: they are not skipped.
FMA-free arithmetic ¶
Every product that feeds an addition is written float64(a*b): the Go specification forbids fusing an explicitly converted product into a fused multiply-add, so arm64 and amd64 give identical bits. Never remove one of those conversions, and never reorder a loop: the left-to-right summation order is part of the contract.
Index ¶
- Constants
- Variables
- func ArgMax(v []float64) (idx int, ok bool)
- func ArgMin(v []float64) (idx int, ok bool)
- func Center(v []float64) []float64
- func Count(v []float64) int
- func Dot(a, b []float64) (float64, error)
- func Exp(x float64) float64
- func Log(x float64) float64
- func Max(v []float64) float64
- func Mean(v []float64) float64
- func Min(v []float64) float64
- func Norm(v []float64) float64
- func Normalize(v []float64, mode string) ([]float64, error)
- func Pow(x, y float64) float64
- func SD(v []float64) float64
- func Sqrt(x float64) float64
- func Sum(v []float64) float64
- func ZScore(v []float64) []float64
- type InvalidNormalizeModeError
- type LengthMismatchError
Constants ¶
const ( NormL1 = "l1" NormL2 = "l2" )
Normalize modes.
Variables ¶
var ErrInvalidNormalizeMode = errors.New("vecmath: invalid normalize mode")
ErrInvalidNormalizeMode is the sentinel every *InvalidNormalizeModeError matches under errors.Is.
var ErrLengthMismatch = errors.New("vecmath: vector length mismatch")
ErrLengthMismatch is the sentinel every *LengthMismatchError matches under errors.Is.
Functions ¶
func ArgMax ¶
ArgMax returns the 0-based index of the largest non-NaN value in v; the first index wins a tie. ok is false when v has no valid value.
func ArgMin ¶
ArgMin returns the 0-based index of the smallest non-NaN value in v; the first index wins a tie. ok is false when v has no valid value.
func Center ¶
Center returns a new slice holding v minus its NaN-skipping mean, NaN kept in place; all-NaN when the mean is undefined.
func Dot ¶
Dot returns the pairwise-complete dot product of a and b; NaN when no index has both sides valid.
func Normalize ¶
Normalize returns a new slice holding v divided by its NaN-skipping L1 (sum of absolute values) or L2 norm, NaN kept in place; all-NaN when the norm is zero or undefined. Any mode other than NormL1 or NormL2 returns an *InvalidNormalizeModeError.
func SD ¶
SD returns the NaN-skipping sample standard deviation (ddof = 1) of v, computed two-pass about the mean; NaN with fewer than two valid values.
Types ¶
type InvalidNormalizeModeError ¶
type InvalidNormalizeModeError struct {
Mode string
}
InvalidNormalizeModeError reports a Normalize mode other than NormL1 or NormL2.
func (*InvalidNormalizeModeError) Error ¶
func (e *InvalidNormalizeModeError) Error() string
func (*InvalidNormalizeModeError) Is ¶
func (e *InvalidNormalizeModeError) Is(target error) bool
Is makes errors.Is(err, ErrInvalidNormalizeMode) true.
type LengthMismatchError ¶
type LengthMismatchError struct {
Left, Right int
}
LengthMismatchError reports two vectors of unequal length handed to Dot.
func (*LengthMismatchError) Error ¶
func (e *LengthMismatchError) Error() string
func (*LengthMismatchError) Is ¶
func (e *LengthMismatchError) Is(target error) bool
Is makes errors.Is(err, ErrLengthMismatch) true.
Source Files