matrix

Documentation

Overview

Package matrix implements several different data structures for efficiently representing large matrices of arbitrary size and dimensionality.

Note that fixed-size small matrices would be better represented using a special-purpose package e.g. a GLM-style implementation.

The concrete implementations are exposed for use by performance-sensitive code.

Index

• func Copy[T comparable](dest, src M[T])
• type Bit
  • func (b Bit) Clear()
  • func (b Bit) Get(idx int) int
  • func (b Bit) Next(idx int) (int, bool)
  • func (b Bit) Set(idx int, value int)
• type Bool
  • func (b Bool) Clear()
  • func (b Bool) Get(idx int) bool
  • func (b Bool) Next(idx int) (int, bool)
  • func (b Bool) Set(idx int, value bool)
• type Diagonal
  • func (m Diagonal[T]) Clear()
  • func (m Diagonal[T]) Get(idx int) T
  • func (m Diagonal[T]) Next(idx int) (int, bool)
  • func (m Diagonal[T]) Set(idx int, value T)
• type Grid
  • func (g Grid[T]) Clear()
  • func (g Grid[T]) Get(idx int) T
  • func (g Grid[T]) Next(idx int) (int, bool)
  • func (g Grid[T]) Set(idx int, value T)
• type Hashmap
  • func (m Hashmap[T]) Clear()
  • func (m Hashmap[T]) Get(idx int) T
  • func (m Hashmap[T]) Next(idx int) (int, bool)
  • func (m Hashmap[T]) Set(idx int, value T)
• type M
  • func Const[T comparable](m M[T]) M[T]
  • func Crop[T comparable](parent M[T], startIdx int, lengths ...int) M[T]
  • func NewBit(lengths ...int) M[int]
  • func NewBool(lengths ...int) M[bool]
  • func NewDiagonal[T comparable](dimensionality, length int) M[T]
  • func NewGrid[T comparable](lengths ...int) M[T]
  • func NewHashmap[T comparable](lengths ...int) M[T]
  • func NewSharedDiagonal[T comparable](dimensionality int, values []T) M[T]
  • func NewSharedGrid[T comparable](lengths []int, values []T) M[T]
  • func NewSharedHashmap[T comparable](lengths []int, values map[int]T) M[T]
  • func NewView[T comparable](parent M[T], mapping dimensions.Map) M[T]
  • func Sample[T comparable](parent M[T], sampler string, constants ...int) M[T]
• type View
  • func (v View[T]) Clear()
  • func (v View[T]) Get(idx int) T
  • func (v View[T]) Next(idx int) (int, bool)
  • func (v View[T]) Set(idx int, value T)

Functions

func Copy

func Copy[T comparable](dest, src M[T])

Copy clears dest and copies every value from src into dest at the same offsets. If dest is smaller than src along any dimension, the results are cropped.

Types

type Bit

type Bit struct {
	dimensions.D
	// contains filtered or unexported fields
}

Bit is an implementation of the matrix interface M that stores data using a densely packed sequence of bits that are either 1 or 0. In most cases, this is initialised by calling [New] or NewBit. Performance sensitive code may cast M to this type.

func (Bit) Clear

func (b Bit) Clear()

func (Bit) Get

func (b Bit) Get(idx int) int

func (Bit) Next

func (b Bit) Next(idx int) (int, bool)

func (Bit) Set

func (b Bit) Set(idx int, value int)

type Bool

type Bool struct {
	dimensions.D
	// contains filtered or unexported fields
}

Bool is an implementation of the matrix interface M that stores data using a densely packed sequence of bits that are either true or false. In most cases, this is initialised by calling [New] or NewBool. Performance sensitive code may cast M to this type.

func (Bool) Clear

func (b Bool) Clear()

func (Bool) Get

func (b Bool) Get(idx int) bool

func (Bool) Next

func (b Bool) Next(idx int) (int, bool)

func (Bool) Set

func (b Bool) Set(idx int, value bool)

type Diagonal

type Diagonal[T comparable] struct {
	dimensions.D
	// contains filtered or unexported fields
}

Diagonal is an implementation of the matrix interface M that represents a diagonal matrix (one where entries outside the main diagonal are all zero) as a contiguous slice of only the diagonal values. In most cases, this is initialised by calling [New] or NewDiagonal.

Setting an element of the diagonal matrix to a non-zero value if it does not lie on the diagonal is an error, and will panic.

func (Diagonal[T]) Clear

func (m Diagonal[T]) Clear()

func (Diagonal[T]) Get

func (m Diagonal[T]) Get(idx int) T

func (Diagonal[T]) Next

func (m Diagonal[T]) Next(idx int) (int, bool)

func (Diagonal[T]) Set

func (m Diagonal[T]) Set(idx int, value T)

type Grid

type Grid[T comparable] struct {
	dimensions.D
	// contains filtered or unexported fields
}

Grid is an implementation of the matrix interface M that stores data using a contiguous slice of values. In most cases, this is initialised by calling [New] or NewGrid. Performance sensitive code may cast M to this type.

func (Grid[T]) Clear

func (g Grid[T]) Clear()

func (Grid[T]) Get

func (g Grid[T]) Get(idx int) T

func (Grid[T]) Next

func (g Grid[T]) Next(idx int) (int, bool)

func (Grid[T]) Set

func (g Grid[T]) Set(idx int, value T)

type Hashmap

type Hashmap[T comparable] struct {
	dimensions.D
	// contains filtered or unexported fields
}

Hashmap is an implementation of the matrix interface M that stores data using a hashmap with element indexes as keys. Elements with the zero value are omitted. This implementation is best suited to representing very sparse matrices. In most cases, this is initialised by calling [New] or NewHashmap.

func (Hashmap[T]) Clear

func (m Hashmap[T]) Clear()

func (Hashmap[T]) Get

func (m Hashmap[T]) Get(idx int) T

func (Hashmap[T]) Next

func (m Hashmap[T]) Next(idx int) (int, bool)

func (Hashmap[T]) Set

func (m Hashmap[T]) Set(idx int, value T)

type M

type M[T comparable] interface {
	// D provides an efficient way to index the matrix and query its shape.
	//
	// Performance-sensitive code may like to cast D to a concrete type e.g.
	// [dimensions.D2] for a 2-Dimensional matrix.
	dimensions.D

	// Get returns the value stored at the given index. Use the Index method
	// on D to obtain an index from coordinates.
	Get(idx int) T

	// Set sets the value stored at the given index. Use the Index method
	// on D to obtain an index from coordinates.
	Set(idx int, value T)

	// Next returns the subsequent index for a non-zero value in the matrix
	// after idx. Use a negative index to start searching from the first
	// element. Use the Offsets method on [dimensions.D] to obtain coordinates
	// from an index. The second return value is false iff all remaining Values
	// are the zero value for type T.
	//
	// This function therefore efficiently enumerates all non-zero values in a
	// sparse matrix.
	Next(idx int) (int, bool)

	// Clear sets every element in the matrix to the zero value for type T.
	Clear()
}

M is the interface implemented by a matrix of Values.

func Const

func Const[T comparable](m M[T]) M[T]

Const returns a read-only view of matrix m. Changes to m will affect the returned matrix. The returned matrix will panic if its Set or Clear methods are called.

func Crop

func Crop[T comparable](parent M[T], startIdx int, lengths ...int) M[T]

Crop is a shortcut for NewView(parent, dimensions.Crop(...))

See dimensions.Crop.

func NewBit

func NewBit(lengths ...int) M[int]

NewBit allocates and returns a Bit matrix implementing M.

func NewBool

func NewBool(lengths ...int) M[bool]

NewBool allocates and returns a new Bool matrix implementing M.

func NewDiagonal

func NewDiagonal[T comparable](dimensionality, length int) M[T]

NewDiagonal allocates and returns a Diagonal implementing M.

Note the unique constructor: a Diagonal matrix is the same size along each axis, and therefore the caller need only specify the dimensionality and the length of one side.

func NewGrid

func NewGrid[T comparable](lengths ...int) M[T]

NewGrid allocates and returns a new grid matrix implementing M.

func NewHashmap

func NewHashmap[T comparable](lengths ...int) M[T]

NewHashmap allocates and returns a Hashmap implementating M.

func NewSharedDiagonal

func NewSharedDiagonal[T comparable](dimensionality int, values []T) M[T]

NewSharedDiagonal returns a new Diagonal matrix implementing M. The matrix uses the provided slice of values, which are the values along the diagonal only, as its storage. This memory is shared: modifications to the values slice will modify the matrix, and modifications to the matrix will modify the values slice. The length of the values slice sets the length of each side of the matrix.

func NewSharedGrid

func NewSharedGrid[T comparable](lengths []int, values []T) M[T]

NewSharedGrid returns a new Grid matrix implementing M. The grid uses the provided slice of values as its storage. Values are laid out in row-major order. This memory is shared: modifications to the values slice will modify the matrix, and modifications to the matrix will modify the values slice. The length of the values slice must be greater than or equal to the product of all lengths.

func NewSharedHashmap

func NewSharedHashmap[T comparable](lengths []int, values map[int]T) M[T]

NewSharedHashmap returns a new Hashmap matrix implementing M. The matrix uses the provided map of values as its storage. This memory is shared: modifications to the values map will modify the matrix, and modifications to the matrix will modify the values map.

func NewView

func NewView[T comparable](parent M[T], mapping dimensions.Map) M[T]

NewView returns a View, implementing the matrix interface M, using the provided mapping.

See dimensions.Crop and the Bind method on dimensions.Sampler for constructing maps from a parent.

func Sample

func Sample[T comparable](parent M[T], sampler string, constants ...int) M[T]

Sample is a shortcut for NewView(parent, dimensions.Sampler(...).Bind(parent)).

See dimensions.Sampler.

type View

type View[T comparable] struct {
	dimensions.D
	// contains filtered or unexported fields
}

View is an implementation of the matrix interface M that represents a custom view of a parent matrix. The View presents its own dimensions and element offsets and indexes, which are mapped appropriately to the parent matrix.

The underlying memory is shared, so that a modification to either the view or the parent modifies the other.

Clearing a view clears only the elements in the view that map to an element in the parent.

func (View[T]) Clear

func (v View[T]) Clear()

func (View[T]) Get

func (v View[T]) Get(idx int) T

func (View[T]) Next

func (v View[T]) Next(idx int) (int, bool)

func (View[T]) Set

func (v View[T]) Set(idx int, value T)