Documentation
¶
Overview ¶
Package tensor provides the core tensor types and operations for Born ML framework.
Package tensor provides the core tensor types and operations for Born ML framework.
Index ¶
- type Backend
- type DType
- type DataType
- type Device
- type MockBackend
- func (m *MockBackend) Add(a, b *RawTensor) *RawTensor
- func (m *MockBackend) Conv2D(input, kernel *RawTensor, stride, padding int) *RawTensor
- func (m *MockBackend) Device() Device
- func (m *MockBackend) Div(a, b *RawTensor) *RawTensor
- func (m *MockBackend) MatMul(a, b *RawTensor) *RawTensor
- func (m *MockBackend) MaxPool2D(input *RawTensor, kernelSize, stride int) *RawTensor
- func (m *MockBackend) Mul(a, b *RawTensor) *RawTensor
- func (m *MockBackend) Name() string
- func (m *MockBackend) Reshape(t *RawTensor, newShape Shape) *RawTensor
- func (m *MockBackend) Sub(a, b *RawTensor) *RawTensor
- func (m *MockBackend) Transpose(t *RawTensor, axes ...int) *RawTensor
- type RawTensor
- func (r *RawTensor) AsBool() []bool
- func (r *RawTensor) AsFloat32() []float32
- func (r *RawTensor) AsFloat64() []float64
- func (r *RawTensor) AsInt32() []int32
- func (r *RawTensor) AsInt64() []int64
- func (r *RawTensor) AsUint8() []uint8
- func (r *RawTensor) ByteSize() int
- func (r *RawTensor) Clone() *RawTensor
- func (r *RawTensor) DType() DataType
- func (r *RawTensor) Data() []byte
- func (r *RawTensor) Device() Device
- func (r *RawTensor) ForceNonUnique() func()
- func (r *RawTensor) IsUnique() bool
- func (r *RawTensor) NumElements() int
- func (r *RawTensor) Release()
- func (r *RawTensor) Shape() Shape
- func (r *RawTensor) Strides() []int
- type Shape
- type Tensor
- func Arange[T DType, B Backend](start, end T, b B) *Tensor[T, B]
- func Eye[T DType, B Backend](n int, b B) *Tensor[T, B]
- func FromSlice[T DType, B Backend](data []T, shape Shape, b B) (*Tensor[T, B], error)
- func Full[T DType, B Backend](shape Shape, value T, b B) *Tensor[T, B]
- func New[T DType, B Backend](raw *RawTensor, b B) *Tensor[T, B]
- func Ones[T DType, B Backend](shape Shape, b B) *Tensor[T, B]
- func Rand[T DType, B Backend](shape Shape, b B) *Tensor[T, B]
- func Randn[T DType, B Backend](shape Shape, b B) *Tensor[T, B]
- func Zeros[T DType, B Backend](shape Shape, b B) *Tensor[T, B]
- func (t *Tensor[T, B]) Add(other *Tensor[T, B]) *Tensor[T, B]
- func (t *Tensor[T, B]) At(indices ...int) T
- func (t *Tensor[T, B]) Backend() B
- func (t *Tensor[T, B]) Clone() *Tensor[T, B]
- func (t *Tensor[T, B]) DType() DataType
- func (t *Tensor[T, B]) Data() []T
- func (t *Tensor[T, B]) Device() Device
- func (t *Tensor[T, B]) Div(other *Tensor[T, B]) *Tensor[T, B]
- func (t *Tensor[T, B]) Grad() *Tensor[T, B]
- func (t *Tensor[T, B]) Item() T
- func (t *Tensor[T, B]) MatMul(other *Tensor[T, B]) *Tensor[T, B]
- func (t *Tensor[T, B]) Mul(other *Tensor[T, B]) *Tensor[T, B]
- func (t *Tensor[T, B]) NumElements() int
- func (t *Tensor[T, B]) Raw() *RawTensor
- func (t *Tensor[T, B]) RequireGrad() *Tensor[T, B]
- func (t *Tensor[T, B]) RequiresGrad() bool
- func (t *Tensor[T, B]) Reshape(newShape ...int) *Tensor[T, B]
- func (t *Tensor[T, B]) Set(value T, indices ...int)
- func (t *Tensor[T, B]) SetGrad(grad *Tensor[T, B])
- func (t *Tensor[T, B]) Shape() Shape
- func (t *Tensor[T, B]) String() string
- func (t *Tensor[T, B]) Sub(other *Tensor[T, B]) *Tensor[T, B]
- func (t *Tensor[T, B]) T() *Tensor[T, B]
- func (t *Tensor[T, B]) Transpose(axes ...int) *Tensor[T, B]
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Backend ¶
type Backend interface {
// Element-wise binary operations
Add(a, b *RawTensor) *RawTensor
Sub(a, b *RawTensor) *RawTensor
Mul(a, b *RawTensor) *RawTensor
Div(a, b *RawTensor) *RawTensor
// Matrix operations
MatMul(a, b *RawTensor) *RawTensor
// Convolutional operations
Conv2D(input, kernel *RawTensor, stride, padding int) *RawTensor
MaxPool2D(input *RawTensor, kernelSize, stride int) *RawTensor
// Shape operations
Reshape(t *RawTensor, newShape Shape) *RawTensor
Transpose(t *RawTensor, axes ...int) *RawTensor
// Metadata
Name() string
Device() Device
}
Backend defines the interface that all compute backends must implement. Backends handle the actual computation for tensor operations.
Implementations:
- CPU: Pure Go with SIMD optimizations (TASK-003)
- CUDA: NVIDIA GPU via driver API (Phase 2)
- Vulkan: Cross-platform GPU compute (Phase 2)
- Metal: Apple GPU (Phase 2)
- WebGPU: Browser/native GPU (Phase 2)
type DType ¶
DType is a constraint for supported tensor data types. It uses Go generics to ensure compile-time type safety.
type MockBackend ¶
type MockBackend struct{}
MockBackend is a simple backend for testing. It implements all operations naively for correctness verification.
func (*MockBackend) Add ¶
func (m *MockBackend) Add(a, b *RawTensor) *RawTensor
Add performs element-wise addition with broadcasting.
func (*MockBackend) Conv2D ¶
func (m *MockBackend) Conv2D(input, kernel *RawTensor, stride, padding int) *RawTensor
Conv2D performs 2D convolution (naive implementation for testing).
func (*MockBackend) Div ¶
func (m *MockBackend) Div(a, b *RawTensor) *RawTensor
Div performs element-wise division with broadcasting.
func (*MockBackend) MatMul ¶
func (m *MockBackend) MatMul(a, b *RawTensor) *RawTensor
MatMul performs matrix multiplication.
func (*MockBackend) MaxPool2D ¶
func (m *MockBackend) MaxPool2D(input *RawTensor, kernelSize, stride int) *RawTensor
MaxPool2D performs 2D max pooling (naive implementation for testing).
func (*MockBackend) Mul ¶
func (m *MockBackend) Mul(a, b *RawTensor) *RawTensor
Mul performs element-wise multiplication with broadcasting.
func (*MockBackend) Reshape ¶
func (m *MockBackend) Reshape(t *RawTensor, newShape Shape) *RawTensor
Reshape changes tensor shape.
func (*MockBackend) Sub ¶
func (m *MockBackend) Sub(a, b *RawTensor) *RawTensor
Sub performs element-wise subtraction with broadcasting.
type RawTensor ¶
type RawTensor struct {
// contains filtered or unexported fields
}
RawTensor is the low-level tensor representation. It uses reference-counted shared buffers for Copy-on-Write semantics.
func NewRaw ¶
NewRaw creates a new RawTensor with the given shape and type. Memory is allocated but not initialized (contains zeros).
func (*RawTensor) AsBool ¶
AsBool interprets the data as []bool. Panics if the tensor's dtype is not Bool.
func (*RawTensor) AsFloat32 ¶
AsFloat32 interprets the data as []float32. Panics if the tensor's dtype is not Float32.
func (*RawTensor) AsFloat64 ¶
AsFloat64 interprets the data as []float64. Panics if the tensor's dtype is not Float64.
func (*RawTensor) AsInt32 ¶
AsInt32 interprets the data as []int32. Panics if the tensor's dtype is not Int32.
func (*RawTensor) AsInt64 ¶
AsInt64 interprets the data as []int64. Panics if the tensor's dtype is not Int64.
func (*RawTensor) AsUint8 ¶
AsUint8 interprets the data as []uint8. Panics if the tensor's dtype is not Uint8.
func (*RawTensor) Clone ¶
Clone creates a shallow copy of the RawTensor (shares buffer with reference counting). The buffer is reference-counted and will be copied only when modified (copy-on-write). This enables cheap cloning and inplace optimizations when refCount == 1.
Example:
a := tensor.Ones[float32](Shape{1000, 1000}, backend)
b := a.Clone() // Shares buffer with a (just increments refCount)
c := a.Add(b) // May use inplace if refCount allows
func (*RawTensor) Data ¶
Data returns the raw byte slice. WARNING: Direct access to underlying memory. Use with caution.
func (*RawTensor) ForceNonUnique ¶
func (r *RawTensor) ForceNonUnique() func()
ForceNonUnique temporarily increases refCount to prevent inplace modifications. Returns a cleanup function that MUST be called to restore refCount (use defer).
This is used by autodiff backend to preserve original input values: inplace optimizations would corrupt the computational graph.
Example:
defer tensor.ForceNonUnique()() result := backend.Mul(tensor, other) // No inplace modification!
func (*RawTensor) IsUnique ¶
IsUnique returns true if this tensor is the only reference to the buffer. When true, backends can perform inplace operations for better performance.
func (*RawTensor) NumElements ¶
NumElements returns the total number of elements.
type Shape ¶
type Shape []int
Shape represents the dimensions of a tensor.
func BroadcastShapes ¶
BroadcastShapes implements NumPy-style broadcasting rules.
Rules: 1. Compare shapes element-wise from right to left 2. Dimensions are compatible if:
- They are equal, OR
- One of them is 1
3. Missing dimensions are treated as 1
Returns the broadcasted shape, a flag indicating if broadcasting is needed, and an error if incompatible.
Examples:
(3, 1) + (3, 5) → (3, 5), true, nil (1, 5) + (3, 5) → (3, 5), true, nil (3, 5) + (3, 5) → (3, 5), false, nil (3, 4) + (3, 5) → nil, false, Error
func (Shape) ComputeStrides ¶
ComputeStrides calculates row-major strides for the shape. Strides define memory layout: stride[i] = product of all dimensions after i.
func (Shape) NumElements ¶
NumElements returns the total number of elements in the tensor.
type Tensor ¶
Tensor is a generic tensor with type T and backend B. It provides type-safe operations over multi-dimensional arrays.
Type Parameters:
- T: Data type (must satisfy DType constraint)
- B: Computation backend (must implement Backend interface)
Example:
backend := cpu.New()
t := tensor.Zeros[float32](Shape{3, 4}, backend)
result := t.Add(t) // Type-safe addition
func Arange ¶
Arange creates a 1D tensor with values from start to end (exclusive). Only works with numeric types (not bool).
Example:
t := tensor.Arange[int32](0, 10, backend) // [0, 1, 2, ..., 9]
func Eye ¶
Eye creates a 2D identity matrix.
Example:
t := tensor.Eye[float32](3, backend) // 3x3 identity matrix
func FromSlice ¶
FromSlice creates a tensor from a Go slice. The slice is copied into the tensor's memory.
func Full ¶
Full creates a tensor filled with a specific value.
Example:
t := tensor.Full[float32](Shape{3, 3}, 3.14, backend)
func Ones ¶
Ones creates a tensor filled with ones.
Example:
t := tensor.Ones[float64](Shape{2, 3}, backend)
func Rand ¶
Rand creates a tensor with random values uniformly distributed in [0, 1). Only works with float types.
Example:
t := tensor.Rand[float32](Shape{10, 10}, backend)
func Randn ¶
Randn creates a tensor with random values from a normal distribution (mean=0, std=1). Uses Box-Muller transform for generating normal distribution. Only works with float types. Note: Uses math/rand (not crypto/rand) - appropriate for ML/statistical purposes.
Example:
t := tensor.Randn[float32](Shape{100, 100}, backend)
func Zeros ¶
Zeros creates a tensor filled with zeros.
Example:
backend := cpu.New()
t := tensor.Zeros[float32](Shape{3, 4}, backend)
func (*Tensor[T, B]) Add ¶
Add performs element-wise addition with broadcasting.
Example:
a := tensor.Ones[float32](Shape{3, 1}, backend)
b := tensor.Ones[float32](Shape{3, 5}, backend)
c := a.Add(b) // Shape: [3, 5] (broadcasted)
func (*Tensor[T, B]) At ¶
At returns the element at the given indices. Panics if indices are out of bounds.
Example:
t := tensor.Zeros[float32](Shape{3, 4}, backend)
value := t.At(1, 2) // Row 1, column 2
func (*Tensor[T, B]) Backend ¶
func (t *Tensor[T, B]) Backend() B
Backend returns the computation backend.
func (*Tensor[T, B]) Data ¶
func (t *Tensor[T, B]) Data() []T
Data returns a typed slice view of the tensor's data. The slice directly accesses the underlying memory (zero-copy).
WARNING: Modifications to the returned slice will modify the tensor.
func (*Tensor[T, B]) Item ¶
func (t *Tensor[T, B]) Item() T
Item returns the scalar value of a 0-D tensor. Panics if the tensor is not a scalar.
func (*Tensor[T, B]) MatMul ¶
MatMul performs matrix multiplication.
Requirements:
- For 2D tensors: (M, K) @ (K, N) → (M, N)
- For batched: (B, M, K) @ (B, K, N) → (B, M, N)
Example:
a := tensor.Randn[float32](Shape{3, 4}, backend)
b := tensor.Randn[float32](Shape{4, 5}, backend)
c := a.MatMul(b) // Shape: [3, 5]
func (*Tensor[T, B]) NumElements ¶
NumElements returns the total number of elements.
func (*Tensor[T, B]) Raw ¶
Raw returns the underlying RawTensor. Used by backend implementations for low-level operations.
func (*Tensor[T, B]) RequireGrad ¶
RequireGrad marks this tensor for gradient computation. When called, subsequent operations involving this tensor will be tracked in the computation graph (if using an AutodiffBackend).
Returns the tensor itself for method chaining.
Example:
x := tensor.Ones[float32](Shape{2, 2}, autodiffBackend).RequireGrad()
y := x.Mul(x) // Operations are tracked
y.Backward() // Computes gradients
fmt.Println(x.Grad()) // dy/dx available
func (*Tensor[T, B]) RequiresGrad ¶
RequiresGrad returns true if this tensor requires gradient computation.
func (*Tensor[T, B]) Reshape ¶
Reshape returns a tensor with the same data but different shape. The new shape must have the same number of elements.
Example:
t := tensor.Arange[int32](0, 12, backend) // Shape: [12] reshaped := t.Reshape(3, 4) // Shape: [3, 4]
func (*Tensor[T, B]) Set ¶
Set sets the element at the given indices. Panics if indices are out of bounds.
func (*Tensor[T, B]) SetGrad ¶
SetGrad sets the gradient tensor. Used internally by autodiff (TASK-004).
func (*Tensor[T, B]) T ¶
T is a shortcut for 2D transpose (swaps rows and columns). Panics if the tensor is not 2D.
Example:
t := tensor.Randn[float32](Shape{3, 4}, backend)
transposed := t.T() // Shape: [4, 3]
func (*Tensor[T, B]) Transpose ¶
Transpose transposes the tensor by permuting its dimensions.
If axes is empty, reverses all dimensions (for 2D, this is standard transpose). Otherwise, axes specifies the permutation.
Example:
t := tensor.Randn[float32](Shape{2, 3, 4}, backend)
transposed := t.Transpose(2, 0, 1) // Shape: [4, 2, 3]
Source Files