README
¶
ndarray — go-ndarray
-9a6700){kind=icon}
A pure-Go (CGO=0) NumPy-style N-dimensional array library. Row-major (C-order) strided arrays with:
- Creation —
New/Zeros/Ones/Full/FromData/Arange/Linspace/Eye/Identity. - Shape & views —
Reshape(with-1inference),Ravel/Flatten,Transpose,Squeeze/ExpandDims, and NumPy basic-indexingSlicereturning strided views that share data. - Elementwise —
Add/Sub/Mul/Div(+ scalar) with full NumPy broadcasting,Map/Neg/Abs, math ufuncs (Sqrt/Exp/Log/Sin/Cos/…), and broadcasting comparisons (Greater/Equal/… as 0/1 masks) plusMaximum/Minimum. - Reductions — whole-array (
Sum/Prod/Max/Min/Mean), per-axis (SumAxis/… withkeepdims), index reductions (ArgMax/ArgMinflat and per-axis), cumulative scans (CumSum/CumProd),Clip, andWhere. - Indexing — basic-indexing
Sliceviews plus boolean/fancy indexing:MaskSelect(a[mask]),Nonzero(flatnonzero), andTake. - Manipulation —
Concatenate/Stack/VStack/HStack. - Linear algebra —
MatMul/Dot/Inner/Outer.
The numeric inner loops are kept behind a narrow kernel API. Behind it,
large elementwise ops, reductions and matmul run multicore (across
GOMAXPROCS); the sum reduction uses a go-asmgen SIMD kernel (NEON on
arm64, SSE2 on amd64); and MatMul is a panel-packed, cache-blocked GEMM
with a go-asmgen SIMD-FMA micro-kernel (NEON 4×8 on arm64, SSE2 4×4 on amd64) —
the OpenBLAS/BLIS structure. So go-ndarray beats single-threaded NumPy on its
core ops on large arrays — measured honestly in docs/perf.md
(e.g. on arm64 vs NumPy 2.2.4: Add/Mul ~2×, Sum ~2.4×; the packed GEMM is 3–7×
faster than the prior kernel and sustains ~156 GFLOP/s, reaching ~76% of
multi-threaded OpenBLAS). Where a faster reference exists — Sqrt/Max small
sizes, and tuned BLAS (OpenBLAS/MKL) for matmul — it says so. It is a
standalone, reusable module and the cgo-free ndarray backend behind
go-embedded-ruby's NDArray class.
⚠️ Status: float64 NumPy parity for the core surface, and faster than NumPy on it. Creation, slicing/views, broadcasting elementwise + ufuncs, reductions (incl. arg/cumulative/clip/where), manipulation, and linear algebra are complete, 100%-covered, six-arch CI-green, and differentially checked against numpy. The hot paths are multicore + SIMD and beat single-threaded NumPy on large arrays (docs/perf.md). See docs/plan-ndarray.md for the roadmap (more SIMD kernels, more dtypes). The Ruby binding has shipped — go-embedded-ruby's
NDArrayclass binds this module.
Why this module?
gonum is matrix-centric and its optimized assembly is
amd64-only. More broadly, Ruby has no cgo-free ndarray (Numo::NArray,
NMatrix are C extensions). A pure-Go core whose kernels are generated for every
arch is therefore a durable foundation. The numeric loops live in
internal/kernels; Phase 1 replaces them with
go-asmgen-generated SIMD kernels across all six
64-bit Go targets (amd64, arm64, riscv64, loong64, ppc64le, s390x), selected at
runtime, behind the same API and the same tests.
Example
import "github.com/go-ndarray/ndarray"
a, _ := ndarray.Arange(0, 6, 1) // [0 1 2 3 4 5]
m, _ := a.Reshape(2, -1) // -1 inferred -> [[0 1 2] [3 4 5]]
row, _ := ndarray.FromData([]float64{10, 20, 30}, 3)
sum, _ := m.Add(row) // broadcast (2,3)+(3,) -> (2,3)
t := m.Transpose() // zero-copy (3,2) view
total := m.Sum() // 15
cols, _ := m.SumAxis(0, false) // sum down each column -> [3 5 7]
// NumPy basic-indexing views (share data):
col0, _ := m.Slice(ndarray.All(), ndarray.A(0)) // m[:,0] -> [0 3]
sub, _ := m.Slice(ndarray.R(0, 2), ndarray.Step(2)) // m[0:2, ::2]
// ufuncs and masks
roots := m.Sqrt()
two, _ := ndarray.Full(2, 1)
mask, _ := m.Greater(two) // broadcast 0/1 mask of m > 2
// linear algebra
b, _ := ndarray.Arange(0, 6, 1)
b, _ = b.Reshape(3, 2)
prod, _ := m.MatMul(b) // (2,3)·(3,2) -> (2,2)
License
BSD-3-Clause. See LICENSE.
Documentation
¶
Overview ¶
Package ndarray is a pure-Go (CGO=0) NumPy-style N-dimensional array library.
The element type for this phase is float64. The numeric kernels live in internal/kernels behind a contiguous-slice API so that go-asmgen SIMD kernels (amd64, arm64, riscv64, loong64, ppc64le, s390x) can replace them in a later phase without touching the public API. See docs/plan-ndarray.md for the roadmap.
Arrays are stored row-major (C-order). An Array is a view over a flat data slice described by a shape, per-axis strides (in elements) and a base offset, so reshaping and transposing can be zero-copy where possible.
Index ¶
- Variables
- type Array
- func Arange(start, stop, step float64) (*Array, error)
- func Concatenate(arrays []*Array, axis int) (*Array, error)
- func Eye(n, m, k int) (*Array, error)
- func FromData(data []float64, shape ...int) (*Array, error)
- func Full(v float64, shape ...int) (*Array, error)
- func HStack(arrays []*Array) (*Array, error)
- func Identity(n int) (*Array, error)
- func Linspace(start, stop float64, num int) (*Array, error)
- func New(shape ...int) (*Array, error)
- func Ones(shape ...int) (*Array, error)
- func Stack(arrays []*Array, axis int) (*Array, error)
- func VStack(arrays []*Array) (*Array, error)
- func Where(cond, t, f *Array) (*Array, error)
- func Zeros(shape ...int) (*Array, error)
- func (a *Array) Abs() *Array
- func (a *Array) Add(b *Array) (*Array, error)
- func (a *Array) AddInto(out, b *Array) error
- func (a *Array) AddScalar(v float64) *Array
- func (a *Array) ArgMax() (int, error)
- func (a *Array) ArgMaxAxis(axis int, keepdims bool) (*Array, error)
- func (a *Array) ArgMin() (int, error)
- func (a *Array) ArgMinAxis(axis int, keepdims bool) (*Array, error)
- func (a *Array) At(idx ...int) float64
- func (a *Array) Ceil() *Array
- func (a *Array) Clip(lo, hi float64) (*Array, error)
- func (a *Array) Copy() *Array
- func (a *Array) Cos() *Array
- func (a *Array) CumProd(axis int) (*Array, error)
- func (a *Array) CumProdFlat() *Array
- func (a *Array) CumSum(axis int) (*Array, error)
- func (a *Array) CumSumFlat() *Array
- func (a *Array) Div(b *Array) (*Array, error)
- func (a *Array) DivInto(out, b *Array) error
- func (a *Array) DivScalar(v float64) *Array
- func (a *Array) Dot(b *Array) (*Array, error)
- func (a *Array) Equal(b *Array) (*Array, error)
- func (a *Array) Exp() *Array
- func (a *Array) ExpandDims(axis int) (*Array, error)
- func (a *Array) Flatten() *Array
- func (a *Array) Floor() *Array
- func (a *Array) Greater(b *Array) (*Array, error)
- func (a *Array) GreaterEqual(b *Array) (*Array, error)
- func (a *Array) Inner(b *Array) (*Array, error)
- func (a *Array) Less(b *Array) (*Array, error)
- func (a *Array) LessEqual(b *Array) (*Array, error)
- func (a *Array) Log() *Array
- func (a *Array) Log2() *Array
- func (a *Array) Log10() *Array
- func (a *Array) Map(f func(float64) float64) *Array
- func (a *Array) MaskSelect(mask *Array) (*Array, error)
- func (a *Array) MatMul(b *Array) (*Array, error)
- func (a *Array) Max() (float64, error)
- func (a *Array) MaxAxis(axis int, keepdims bool) (*Array, error)
- func (a *Array) Maximum(b *Array) (*Array, error)
- func (a *Array) Mean() (float64, error)
- func (a *Array) MeanAxis(axis int, keepdims bool) (*Array, error)
- func (a *Array) Min() (float64, error)
- func (a *Array) MinAxis(axis int, keepdims bool) (*Array, error)
- func (a *Array) Minimum(b *Array) (*Array, error)
- func (a *Array) Mul(b *Array) (*Array, error)
- func (a *Array) MulInto(out, b *Array) error
- func (a *Array) MulScalar(v float64) *Array
- func (a *Array) Ndim() int
- func (a *Array) Neg() *Array
- func (a *Array) Nonzero() *Array
- func (a *Array) NotEqual(b *Array) (*Array, error)
- func (a *Array) Outer(b *Array) *Array
- func (a *Array) Power(p float64) *Array
- func (a *Array) Prod() float64
- func (a *Array) ProdAxis(axis int, keepdims bool) (*Array, error)
- func (a *Array) Ravel() *Array
- func (a *Array) Reshape(shape ...int) (*Array, error)
- func (a *Array) Round() *Array
- func (a *Array) Set(v float64, idx ...int)
- func (a *Array) Shape() []int
- func (a *Array) Sin() *Array
- func (a *Array) Size() int
- func (a *Array) Slice(idx ...Index) (*Array, error)
- func (a *Array) Sqrt() *Array
- func (a *Array) SqrtInto(out *Array) error
- func (a *Array) Square() *Array
- func (a *Array) Squeeze(axes ...int) (*Array, error)
- func (a *Array) String() string
- func (a *Array) Sub(b *Array) (*Array, error)
- func (a *Array) SubInto(out, b *Array) error
- func (a *Array) SubScalar(v float64) *Array
- func (a *Array) Sum() float64
- func (a *Array) SumAxis(axis int, keepdims bool) (*Array, error)
- func (a *Array) Take(indices ...int) (*Array, error)
- func (a *Array) Tan() *Array
- func (a *Array) Transpose() *Array
- type Index
Constants ¶
This section is empty.
Variables ¶
var ErrAxis = errors.New("ndarray: axis out of range")
ErrAxis is returned when an axis argument is out of range for the array.
var ErrBroadcast = errors.New("ndarray: shapes are not broadcastable")
ErrBroadcast is returned when two shapes cannot be broadcast together.
var ErrIndex = errors.New("ndarray: index out of range")
ErrIndex is returned when an integer index or slice argument is out of range for the axis it addresses, or when the number of index arguments does not match the array's rank.
var ErrLinalg = fmt.Errorf("ndarray: incompatible shapes for linear algebra")
ErrLinalg is returned when operands have shapes incompatible with the requested linear-algebra operation (e.g. a dimension mismatch in matrix multiply).
var ErrShapeMismatch = errors.New("ndarray: shape mismatch")
ErrShapeMismatch is returned when a requested shape is invalid or incompatible with the data it must describe.
Functions ¶
This section is empty.
Types ¶
type Array ¶
type Array struct {
// contains filtered or unexported fields
}
Array is an N-dimensional, row-major array of float64.
func Arange ¶
Arange returns a 1-D array of evenly spaced values over [start, stop) with the given step, matching numpy.arange. step must be non-zero.
func Concatenate ¶
Concatenate joins the given arrays along an existing axis, matching numpy.concatenate. Every array must have the same rank and the same shape on every axis except the concatenation axis; a negative axis counts from the end. At least one array is required. The result is a fresh contiguous array.
func Eye ¶
Eye returns an array with ones on the k-th diagonal and zeros elsewhere, matching numpy.eye(n, m, k). A non-positive m defaults to n (a square matrix), the common case; pass m > 0 for a rectangular result. k > 0 selects a superdiagonal, k < 0 a subdiagonal. n must be non-negative.
func FromData ¶
FromData wraps data in an array of the given shape. The data slice is copied, so later mutations of the caller's slice do not affect the array. The number of elements implied by shape must equal len(data).
func HStack ¶
HStack stacks arrays horizontally (column-wise), matching numpy.hstack: concatenation along axis 1, except that 1-D inputs are joined along axis 0 (their only axis).
func Linspace ¶
Linspace returns num evenly spaced samples over the closed interval [start, stop], matching numpy.linspace with the default endpoint=True. num must be non-negative; num == 0 yields an empty array and num == 1 yields [start]. The spacing is (stop-start)/(num-1) for num > 1.
func Stack ¶
Stack joins the given arrays along a new axis, matching numpy.stack. Every array must have identical shape; the new axis is inserted at the given position, which may range over [-(Ndim+1), Ndim]. The result has rank Ndim+1.
func VStack ¶
VStack stacks arrays vertically (row-wise), matching numpy.vstack: 1-D inputs of length n are treated as (1, n) rows, then all inputs are concatenated along axis 0.
func Where ¶
Where returns an array selecting from t where cond is truthy (non-zero) and from f otherwise, elementwise with full NumPy broadcasting across all three operands — matching numpy.where(cond, t, f). cond is typically a 0/1 mask from the comparison ufuncs.
func (*Array) AddInto ¶
AddInto writes a+b into out (no allocation), the parity-path analogue of np.add(a, b, out=out). out must be contiguous and the broadcast result shape; it may alias a or b. See binOpInto.
func (*Array) ArgMax ¶
ArgMax returns the flat index of the first maximum element over the array in row-major order, matching numpy.argmax with no axis. It errors on an empty array.
func (*Array) ArgMaxAxis ¶
ArgMaxAxis returns the indices of the first maxima along the given axis, matching numpy.argmax(axis=...). The result has the reduced shape (the axis removed, or kept as length 1 with keepdims) and integer index values stored as float64. A negative axis counts from the end.
func (*Array) ArgMin ¶
ArgMin returns the flat index of the first minimum element over the array in row-major order, matching numpy.argmin with no axis. It errors on an empty array.
func (*Array) ArgMinAxis ¶
ArgMinAxis returns the indices of the first minima along the given axis, matching numpy.argmin(axis=...). See ArgMaxAxis for the shape semantics.
func (*Array) Clip ¶
Clip returns a new array with every element limited to the range [lo, hi], matching numpy.clip. It errors if lo > hi.
func (*Array) CumProd ¶
CumProd returns the cumulative product along the given axis, matching numpy.cumprod(axis=...). The result has the same shape as the input.
func (*Array) CumProdFlat ¶
CumProdFlat returns the cumulative product over the flattened array (1-D, row-major order), matching numpy.cumprod with no axis.
func (*Array) CumSum ¶
CumSum returns the cumulative sum along the given axis, matching numpy.cumsum(axis=...). The result has the same shape as the input. A negative axis counts from the end.
func (*Array) CumSumFlat ¶
CumSumFlat returns the cumulative sum over the flattened array (1-D, row-major order), matching numpy.cumsum with no axis.
func (*Array) Dot ¶
Dot returns the dot product following numpy.dot for 1-D and 2-D operands:
- 1-D · 1-D -> a 0-d (scalar) array, the inner product.
- 2-D · 2-D -> matrix multiply (m x k)·(k x n) = (m x n).
- 2-D · 1-D -> matrix-vector (m x k)·(k,) = (m,).
- 1-D · 2-D -> vector-matrix (k,)·(k x n) = (n,).
Higher-rank operands are rejected (the general tensordot is a later phase).
func (*Array) ExpandDims ¶
ExpandDims returns a view with a new length-1 axis inserted at the given position, matching numpy.expand_dims. axis may range over [-(Ndim+1), Ndim]; a negative axis counts from the end of the result.
func (*Array) Flatten ¶
Flatten returns a contiguous 1-D copy of the array's elements in row-major order. Unlike Ravel, the result is always an independent copy (NumPy flatten semantics; here Ravel is also a copy, but Flatten documents the always-copy contract).
func (*Array) GreaterEqual ¶
GreaterEqual returns the elementwise a >= b mask.
func (*Array) Inner ¶
Inner returns the inner product over the last axes, matching numpy.inner for 1-D and 2-D operands: a sum-product over the last axis, which must have the same length in both operands.
- 1-D · 1-D -> scalar (same as Dot).
- 2-D · 2-D -> (m x p) where a is (m x k), b is (p x k): out[i,j] is the dot of row i of a with row j of b.
func (*Array) Map ¶
Map returns a new contiguous array with f applied to every element. For a contiguous receiver the elements are read in place (no materialise copy); the elementwise pass is parallelised across cores above the kernel threshold. f must be safe to call concurrently (the package's math ufuncs are).
func (*Array) MaskSelect ¶
MaskSelect returns a 1-D array of the elements of a where mask is truthy (non-zero), in row-major order — NumPy's a[mask]. mask must broadcast to a's shape (typically it has exactly a's shape, e.g. a mask from a.Greater(...)).
func (*Array) MatMul ¶
MatMul returns the matrix product of two 2-D arrays, matching numpy.matmul (the @ operator) for the 2-D case: a is (m x k), b is (k x n), the result is (m x n). Both operands must be 2-D and the inner dimensions must agree.
func (*Array) MaxAxis ¶
MaxAxis returns the maximum along the given axis. See SumAxis for the axis/keepdims semantics.
func (*Array) Mean ¶
Mean returns the arithmetic mean of all elements. It returns an error for an empty array.
func (*Array) MeanAxis ¶
MeanAxis returns the arithmetic mean along the given axis. See SumAxis for the axis/keepdims semantics.
func (*Array) MinAxis ¶
MinAxis returns the minimum along the given axis. See SumAxis for the axis/keepdims semantics.
func (*Array) Nonzero ¶
Nonzero returns a 1-D array of the flat (row-major) indices at which a is non-zero — NumPy's np.flatnonzero(a). For a 0/1 mask this is the positions of the truthy elements.
func (*Array) Outer ¶
Outer returns the outer product of two arrays, matching numpy.outer: both operands are flattened to 1-D vectors u (length m) and v (length n), and the result is the (m x n) array out[i,j] = u[i]*v[j].
func (*Array) ProdAxis ¶
ProdAxis returns the product along the given axis. See SumAxis for the axis/keepdims semantics.
func (*Array) Ravel ¶
Ravel returns a contiguous 1-D array containing the elements in row-major order.
func (*Array) Reshape ¶
Reshape returns a view (or copy) of the array with a new shape of the same total size. The data is preserved in row-major order. At most one dimension may be -1, which is inferred from the total size (NumPy semantics).
func (*Array) Slice ¶
Slice returns a view of the array selected by per-axis indices, following NumPy basic-indexing semantics. It accepts exactly Ndim index arguments (build them with A, All, R, Rng, From, To). Integer indices (A) drop their axis; range indices keep the axis as a strided view that shares the receiver's backing data — writes through the view are visible in the original and vice versa. The result may have a non-zero offset and arbitrary strides.
func (*Array) Sqrt ¶
Sqrt returns the elementwise non-negative square root. It is routed through the dedicated SIMD sqrt kernel (packed SQRTPD on amd64; the intrinsic FSQRTD scalar loop on arm64/others) rather than the generic Map, because passing math.Sqrt as a func(float64)float64 blocks both the compiler's FSQRTD intrinsic and the packed kernel. The result is bit-identical to a scalar math.Sqrt loop (sqrt(-x)=NaN, sqrt(+Inf)=+Inf, matching NumPy).
func (*Array) SqrtInto ¶
SqrtInto writes the elementwise square root of a into the caller-provided contiguous out array (no allocation), the analogue of np.sqrt(a, out=out) and the parity path for small arrays where Go's per-op make would otherwise cost more than NumPy's cached temp buffer. out must be contiguous and the same shape as a; it may alias a (each index is read before it is written). It routes through the same SIMD sqrt kernel as Sqrt (packed SQRTPD on amd64, the FSQRTD-intrinsic scalar loop on arm64/others), bit-identical to math.Sqrt.
func (*Array) Squeeze ¶
Squeeze returns a view with length-1 axes removed. With no axes given, every length-1 axis is removed; otherwise only the listed axes are removed and each must have length 1 (NumPy semantics). Negative axes count from the end.
func (*Array) Sum ¶
Sum returns the sum of all elements (0 for an empty array). Large sums are computed as a tree of per-core partials, so the result can differ from a strictly left-to-right sum by a few ULP (floating-point addition is not associative) — the same trade-off NumPy's pairwise summation makes.
func (*Array) SumAxis ¶
SumAxis returns the sum along the given axis. With keepdims the reduced axis is kept with length 1 (e.g. (2,3) summed over axis 0 -> (1,3)); otherwise it is removed (-> (3,)). A negative axis counts from the end.
type Index ¶
type Index struct {
// contains filtered or unexported fields
}
Index describes how a single axis is indexed by Slice. It is either an integer index (which removes that axis from the result, NumPy basic-indexing semantics) or a half-open range start:stop:step (which keeps the axis as a strided view). Construct one with A (integer) or R / Rng (range).
func A ¶
A returns an integer Index that selects position i along an axis and removes that axis from the result, mirroring NumPy's a[i] basic indexing. A negative i counts from the end of the axis.
func All ¶
func All() Index
All returns a range Index covering an entire axis with step 1, the equivalent of NumPy's a[:].
func From ¶
From returns a range Index for start: (to the end of the axis) with step 1 (NumPy a[start:]).
func R ¶
R returns a range Index for start:stop with step 1, keeping the axis as a view (NumPy a[start:stop]). Negative bounds count from the end of the axis.
func Rng ¶
Rng returns a range Index for start:stop:step, keeping the axis as a view (NumPy a[start:stop:step]). Negative bounds count from the end; step may be negative to reverse, but must not be zero.
Source Files
Directories