Documentation
¶
Overview ¶
Package vectorops contains allocation-free vector kernels shared by TreeDB packages. Kernels operate on already validated typed slices; callers that start from mapped bytes must validate and obtain typed views before calling into this package.
Row-major batch dot wrappers accept flat []float32 payloads and ordinal/row-id tiles directly. They validate full-row shapes, leave dst unchanged for invalid shapes, and report whether a platform batch SIMD kernel or a non-batch fallback handled the call. Prevalidated row-id wrappers are reserved for hot paths that have already checked row bounds while composing an adjacency tile. Scalar_u8 helpers expose centered int16 query layouts and indexed row-major byte-code dot kernels while keeping callers allocation-free.
Index ¶
- func DotFloat32(left, right []float32) float32
- func DotFloat32BatchImplementation() string
- func DotFloat32BatchOptimizedAvailable() bool
- func DotFloat32Implementation() string
- func DotFloat32IndexedOptimizedEligible(rows, dims int) bool
- func DotFloat32OptimizedAvailable() bool
- func DotFloat32OptimizedEligible(n int) bool
- func DotFloat32Scalar(left, right []float32) float32
- func DotScalarU8CenteredIndexedOptimizedEligible(rows, dims int) bool
- func PrepareScalarU8CenteredQuery(dst []ScalarU8CenteredCode, codes []byte, dims int) (query ScalarU8CenteredQuery, scratch []ScalarU8CenteredCode, ok bool)
- func PrepareScalarU8CenteredQueryFromCentered(values []ScalarU8CenteredCode, dims int, sum int64) (query ScalarU8CenteredQuery, scratch []ScalarU8CenteredCode, ok bool)
- func ScalarU8CenteredDot(query ScalarU8CenteredQuery, row []byte) (int64, bool)
- func ScalarU8DotBatchImplementation() string
- func ScalarU8DotBatchOptimizedAvailable() bool
- type DotFloat32BatchStatus
- func DotFloat32Indexed(dst []float32, base []float32, query []float32, rowIDs []uint32, dims int) DotFloat32BatchStatus
- func DotFloat32IndexedPrevalidated(dst []float32, base []float32, query []float32, rowIDs []uint32, dims int) DotFloat32BatchStatus
- func DotFloat32Strided(dst []float32, base []float32, query []float32, rowCount, dims, stride int) DotFloat32BatchStatus
- type ScalarU8CenteredCode
- type ScalarU8CenteredQuery
- type ScalarU8DotBatchStatus
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DotFloat32 ¶
DotFloat32 returns the float32 dot product over the shared prefix of left and right using the amd64 SIMD implementation. Callers must pass validated []float32 slices; this kernel does not reinterpret raw bytes.
func DotFloat32BatchImplementation ¶
func DotFloat32BatchImplementation() string
DotFloat32BatchImplementation identifies the active row-major batch dot backend. The per-call status is still authoritative because optimized backends may fall back for unsupported runtime CPU features or individual shapes.
func DotFloat32BatchOptimizedAvailable ¶
func DotFloat32BatchOptimizedAvailable() bool
DotFloat32BatchOptimizedAvailable reports whether this build includes a platform batch SIMD backend. A true value does not guarantee that a given call uses SIMD; callers must inspect DotFloat32BatchStatus.Optimized.
func DotFloat32Implementation ¶
func DotFloat32Implementation() string
DotFloat32Implementation identifies the active DotFloat32 implementation.
func DotFloat32IndexedOptimizedEligible ¶
DotFloat32IndexedOptimizedEligible reports whether this build's indexed-row backend is expected to use optimized execution for a valid rows/dims shape. Callers must still inspect DotFloat32BatchStatus because invalid shapes are rejected before backend selection.
func DotFloat32OptimizedAvailable ¶
func DotFloat32OptimizedAvailable() bool
DotFloat32OptimizedAvailable reports whether this build includes a platform-optimized single-vector dot backend. It does not guarantee that every call uses SIMD; use DotFloat32OptimizedEligible for per-length accounting.
func DotFloat32OptimizedEligible ¶
DotFloat32OptimizedEligible reports whether DotFloat32 is expected to use the platform-optimized backend for a dot product of n float32 values.
func DotFloat32Scalar ¶
DotFloat32Scalar returns the float32 dot product over the shared prefix of left and right. It accepts already validated float32 slices and performs no byte reinterpretation or allocation.
func DotScalarU8CenteredIndexedOptimizedEligible ¶
DotScalarU8CenteredIndexedOptimizedEligible reports whether this build's indexed-row scalar_u8 backend is expected to use optimized execution for a valid rows/dims shape. Callers must still inspect ScalarU8DotBatchStatus because invalid shapes are rejected before backend selection.
func PrepareScalarU8CenteredQuery ¶
func PrepareScalarU8CenteredQuery(dst []ScalarU8CenteredCode, codes []byte, dims int) (query ScalarU8CenteredQuery, scratch []ScalarU8CenteredCode, ok bool)
PrepareScalarU8CenteredQuery fills dst with centered values for codes and returns a validated query view. The function never allocates: callers must provide scratch capacity for dims values. Invalid dimensions or insufficient scratch return ok=false and leave dst contents unspecified.
func PrepareScalarU8CenteredQueryFromCentered ¶
func PrepareScalarU8CenteredQueryFromCentered(values []ScalarU8CenteredCode, dims int, sum int64) (query ScalarU8CenteredQuery, scratch []ScalarU8CenteredCode, ok bool)
PrepareScalarU8CenteredQueryFromCentered returns a validated query view over caller-filled centered values. The caller must provide the exact sum of values[:dims]; SIMD batch kernels use it to preserve the scalar_u8 centered scoring identity without rescanning the query on each score batch.
func ScalarU8CenteredDot ¶
func ScalarU8CenteredDot(query ScalarU8CenteredQuery, row []byte) (int64, bool)
ScalarU8CenteredDot computes the integer dot product between a centered query and a raw scalar_u8 row. The row is centered as 2*row_code-255 while the query is consumed from its pre-centered layout.
func ScalarU8DotBatchImplementation ¶
func ScalarU8DotBatchImplementation() string
ScalarU8DotBatchImplementation identifies the active scalar_u8 centered indexed batch dot backend. Per-call status is still authoritative because optimized backends may fall back for individual shapes.
func ScalarU8DotBatchOptimizedAvailable ¶
func ScalarU8DotBatchOptimizedAvailable() bool
ScalarU8DotBatchOptimizedAvailable reports whether this build includes a platform scalar_u8 batch SIMD backend. A true value does not guarantee that a given call uses SIMD; callers must inspect ScalarU8DotBatchStatus.Optimized.
Types ¶
type DotFloat32BatchStatus ¶
DotFloat32BatchStatus reports how a row-major FP32 batch dot wrapper handled a call. Rows is the number of dst entries written. Optimized is true only when the active platform backend reports that a batch SIMD kernel handled at least one row batch. Fallback is true when valid rows were written and the call was completed without a batch SIMD kernel. Invalid is true when the wrapper rejected the shape and left dst unchanged.
Status is call-level: Optimized and Fallback are mutually exclusive. A call can be valid and non-optimized: unsupported platforms, purego builds, short dims, tiny row counts, or backend-specific thresholds all use the non-batch fallback and return Optimized=false, Fallback=true. The purego and unsupported-platform fallback is the portable scalar implementation.
func DotFloat32Indexed ¶
func DotFloat32Indexed(dst []float32, base []float32, query []float32, rowIDs []uint32, dims int) DotFloat32BatchStatus
DotFloat32Indexed writes dot products for row-major base rows selected by rowIDs using the per-row DotFloat32 fallback. It writes min(len(dst), len(rowIDs)) scores for valid full-row shapes. Invalid shapes leave dst unchanged and return Invalid=true.
func DotFloat32IndexedPrevalidated ¶
func DotFloat32IndexedPrevalidated(dst []float32, base []float32, query []float32, rowIDs []uint32, dims int) DotFloat32BatchStatus
DotFloat32IndexedPrevalidated writes dot products for row-major base rows selected by rowIDs whose bounds were already checked by the caller. It still validates the non-indexed shape (dst/row count, dims, base/query minimum length) but intentionally skips scanning rowIDs so hot graph-search paths that already validated adjacency ordinals do not pay that check twice. Passing an out-of-range row ID violates this function's contract.
func DotFloat32Strided ¶
func DotFloat32Strided(dst []float32, base []float32, query []float32, rowCount, dims, stride int) DotFloat32BatchStatus
DotFloat32Strided writes dot products for row-major base rows at i*stride using the per-row DotFloat32 fallback. It writes min(len(dst), rowCount) scores for valid full-row shapes. Invalid shapes leave dst unchanged and return Invalid=true. stride and dims are in float32 elements; stride must be >= dims.
type ScalarU8CenteredCode ¶
type ScalarU8CenteredCode = int16
ScalarU8CenteredCode is the stable element type for centered scalar_u8 query codes. Each value is 2*code-255, so the valid range is [-255, 255]. The slice layout is contiguous native-endian int16 values with ordinary Go slice alignment; SIMD backends that consume this layout must tolerate unaligned loads.
func ScalarU8CenteredValue ¶
func ScalarU8CenteredValue(code byte) ScalarU8CenteredCode
ScalarU8CenteredValue returns the centered scalar_u8 value 2*code-255.
type ScalarU8CenteredQuery ¶
type ScalarU8CenteredQuery struct {
// contains filtered or unexported fields
}
ScalarU8CenteredQuery is a validated, allocation-free view over centered scalar_u8 query codes. Centered values alias caller-owned scratch, must be treated as immutable while the query is in use, and remain valid until that scratch is reused. The values slice is intentionally unexported so callers cannot mutate cached query metadata through the query handle.
func (ScalarU8CenteredQuery) CenteredSum ¶
func (q ScalarU8CenteredQuery) CenteredSum() int64
CenteredSum returns sum(q.values). Queries returned by PrepareScalarU8CenteredQuery carry this value so batch kernels can reuse it without rescanning the query per call. Manually constructed or resliced queries still return the correct sum by scanning values.
func (ScalarU8CenteredQuery) Dims ¶
func (q ScalarU8CenteredQuery) Dims() int
Dims returns the number of centered query dimensions.
func (ScalarU8CenteredQuery) Valid ¶
func (q ScalarU8CenteredQuery) Valid() bool
Valid reports whether q has a positive-dimension centered-code layout.
func (ScalarU8CenteredQuery) ValidForDims ¶
func (q ScalarU8CenteredQuery) ValidForDims(dims int) bool
ValidForDims reports whether q is valid for exactly dims dimensions.
func (ScalarU8CenteredQuery) Value ¶
func (q ScalarU8CenteredQuery) Value(i int) (ScalarU8CenteredCode, bool)
Value returns the centered value at i for tests and diagnostics without exposing the mutable backing slice.
type ScalarU8DotBatchStatus ¶
ScalarU8DotBatchStatus reports how a row-major scalar_u8 centered dot batch wrapper handled a call. Rows is the number of dst entries written. Optimized is true only when the active platform backend reports that a batch SIMD kernel handled the call. Fallback is true when valid rows were written without a batch SIMD kernel. Invalid is true when the wrapper rejected the shape and left dst unchanged.
Status is call-level: Optimized and Fallback are mutually exclusive. A call can be valid and non-optimized on unsupported platforms, purego builds, tiny row counts, short dimensions, or backend-specific overflow guard thresholds.
func DotScalarU8CenteredIndexed ¶
func DotScalarU8CenteredIndexed(dst []int64, codes []byte, query ScalarU8CenteredQuery, rowIDs []uint32, dims int) ScalarU8DotBatchStatus
DotScalarU8CenteredIndexed writes integer dot products for row-major scalar_u8 code rows selected by rowIDs against a pre-centered scalar_u8 query. Supported amd64 builds use an AVX2 indexed-row kernel when available, otherwise an SSE2 kernel, for sufficiently large overflow-safe tiles. Tiny/short or very high-dimensional shapes use the portable scalar fallback. Invalid shapes leave dst unchanged and return Invalid=true.
func DotScalarU8CenteredIndexedPrevalidated ¶
func DotScalarU8CenteredIndexedPrevalidated(dst []int64, codes []byte, query ScalarU8CenteredQuery, rowIDs []uint32, dims int) ScalarU8DotBatchStatus
DotScalarU8CenteredIndexedPrevalidated is the trusted-call variant of DotScalarU8CenteredIndexed for hot paths that already proved every row ID is within the row-major code payload. It still validates the basic slice/query shape but deliberately skips the per-call rowID bounds scan.
Source Files