simd

package standard library
go1.27.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 1, 2026 License: BSD-3-Clause Imports: 6 Imported by: 0

Documentation

Overview

Package simd implements portable and vector-size-agnostic SIMD types, and functions and methods for working with these types. SIMD types are either implemented in hardware (for example, arm64 "Neon" or amd64 "AVX/AVX2/AVX512") using the corresponding types in the simd/archsimd package, or emulated in pure Go. In all cases, the vector length is at least 128 bits, and within a given program execution, all vectors have the same length.

SIMD Types

There is a simd type corresponding to each primitive numeric type, except for complex64 and complex128. Each of these is the type name, capitalized, with an "s" suffix, for example Int8s, Uint16s, or Float64s.

There are also simd "mask" types that abstract the mask registers present in some architectures, otherwise these will be implemented as bit masks.

Obtaining SIMD values

The zero value of a SIMD vector type is valid and represents a zero vector.

For each SIMD type, "Load<Types>(s []<type>) <Types>" loads a full verctor of the type from a long-enough slice.

For slices that are not long enough, "Load<Types>Part(s []<type>) (<Types>, int)" will load as many elements as are available from the slice, fill the remainder with zero, and also return the number that were loaded.

For each SIMD type, "Broadcast<Types>(x type) <Types>" returns a vector whose elements are all initialized to x.

Examples:

Operations

SIMD types provide methods for unary (Float32s.Abs, Int16s.Not), binary (Float64s.Add, Uint32s.GreaterEqual), and ternary operations (Int64s.IfElse, Float32s.MulAdd). Relational operations produce masks.

SIMD types also support conversions between types, both those that are mostly value-preserving (Int32s.ConvertToFloat32, Float32s.ConvertToInt32) and those that change types without altering the underlying vector bit pattern.

Signed integer types convert to mask types (Int16s.ToMask), but this is a comparison against zero, not a simple bitwise conversion. Mask types convert to signed integers in an operation (Mask32s.ToInt32s) that may be a zero-cost bitwise conversion, or not, depending on the underlying hardware.

Storing

SIMD vector types have two methods, one for storing the entire vector into a slice "Store([]<type>)"" and a second for storing part of a vector into a slice "StorePart([]<type>) int". StorePart returns the number of elements actually stored.

String conversion

Vectors and masks provide a String method for conversion to strings.

Conversion to and from simd/archsimd types.

Each SIMD vector type has a "ToArch() any" method that returns the type supported by the current hardware as an "any". Code using these methods must be build-tagged to the relevant architecture(s) and type-assert the returned value to the appropriate type.

The simd package also includes generic functions for converting an architecture-dependent simd/archsimd value (e.g. archsimd.Float32x4) into the corresponding simd type. This function will panic if the correspondence is incorrect.

For an example of converting between simd and arch/simd types, see the test file sum_amd64_test.go.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Emulated 

func Emulated() bool

Emulated returns whether simd operations are emulated or running on actual vector hardware.

func HasHardwareCarrylessMultiply 

func HasHardwareCarrylessMultiply() bool

HasHardwareCarrylessMultiply returns whether this platform as a hardware-implemented version of carryless multiply. With default GODEBUG=simd settings, if this is false, it is emulated and merely slow, but with non-default settings this can indicate the possibility of a missing instruction that will fail ("SIGILL") if it is executed.

func VectorBitSize 

func VectorBitSize() int

VectorBitSize returns the bit length of the longest vector available on the current hardware. It can be artificially reduced by setting GODEBUG=simd=<smaller size> environment variable before running a program.

Types

type Float32s 

type Float32s struct {
	// contains filtered or unexported fields
}

Float32s represents a vector of 32-bit floating-point numbers.

func BroadcastFloat32s 

func BroadcastFloat32s(float32) Float32s

BroadcastFloat32 fills the elements of a slice with its argument value.

func Float32sFromArch 

func Float32sFromArch[T archSimdFloat32s](x T) Float32s

func LoadFloat32s 

func LoadFloat32s([]float32) Float32s

LoadFloat32 loads a slice of float32 into an Float32s vector.

func LoadFloat32sPart 

func LoadFloat32sPart([]float32) (Float32s, int)

LoadFloat32Part loads a partial slice of float32 into an Float32s vector, returning the vector and the number of elements loaded.

func (Float32s) Abs 

func (x Float32s) Abs() Float32s

Abs returns the element-wise absolute value of x.

func (Float32s) Add 

func (x Float32s) Add(y Float32s) Float32s

Add returns the element-wise sum of x and y.

func (Float32s) ConvertToInt32 

func (x Float32s) ConvertToInt32() Int32s

ConvertToInt32 converts the vector elements to int32.

func (Float32s) Div 

func (x Float32s) Div(y Float32s) Float32s

Div returns the element-wise quotient of x and y.

func (Float32s) Equal 

func (x Float32s) Equal(y Float32s) Mask32s

Equal returns a mask indicating where x and y are equal.

func (Float32s) Greater 

func (x Float32s) Greater(y Float32s) Mask32s

Greater returns a mask indicating where x is greater than y.

func (Float32s) GreaterEqual 

func (x Float32s) GreaterEqual(y Float32s) Mask32s

GreaterEqual returns a mask indicating where x is greater than or equal to y.

func (Float32s) IfElse 

func (x Float32s) IfElse(mask Mask32s, y Float32s) Float32s

IfElse returns a new vector with elements from x where mask is true, and y where mask is false.

func (Float32s) Len 

func (x Float32s) Len() int

Len returns the number of elements in the vector.

func (Float32s) Less 

func (x Float32s) Less(y Float32s) Mask32s

Less returns a mask indicating where x is less than y.

func (Float32s) LessEqual 

func (x Float32s) LessEqual(y Float32s) Mask32s

LessEqual returns a mask indicating where x is less than or equal to y.

func (Float32s) Masked 

func (x Float32s) Masked(mask Mask32s) Float32s

Masked returns a new vector with elements from x where mask is true, and zero elsewhere.

func (Float32s) Max 

func (x Float32s) Max(y Float32s) Float32s

Max returns the element-wise maximum of x and y.

func (Float32s) Min 

func (x Float32s) Min(y Float32s) Float32s

Min returns the element-wise minimum of x and y.

func (Float32s) Mul 

func (x Float32s) Mul(y Float32s) Float32s

Mul returns the element-wise product of x and y.

func (Float32s) MulAdd 

func (x Float32s) MulAdd(y Float32s, z Float32s)