Help us shape the future of Go! Take the 2026 Go Developer Survey

engine

package
v0.0.0-...-dd6fb2f Latest Latest
Warning

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

 Go to latest Published: Oct 27, 2026 License: BSD-3-Clause Imports: 8 Imported by: 0

Documentation

Overview

Package engine is the model of the go-ndarray playground: a pipeline of steps, each one go-ndarray operation applied to earlier results, with the Go, Ruby and NumPy spellings of every step and what each result looks like in memory. Everything here is computed by go-ndarray itself; the package has no user interface and no JavaScript.

Index

Constants

View Source 
const (
	GridMaxRows = 200
	GridMaxCols = 64
)

Grid limits: past these the table would only be scrolled, never read.

View Source 
const MaxElements = 1 << 22

MaxElements bounds the size of an array the playground will build. A browser tab has a few GiB at most, and Go cannot recover from running out of memory: the tab would die instead of showing an error. 2^22 float64s are 32 MiB — far beyond anything worth looking at in a table.

Variables

View Source 
var Ops = []Op{
	{Name: "Arange", Kind: KindCreate, Hint: "start, stop, step", Default: "0, 12, 1", /* contains filtered or unexported fields */},
	{Name: "Linspace", Kind: KindCreate, Hint: "start, stop, num", Default: "0, 1, 5", /* contains filtered or unexported fields */},
	{Name: "Zeros", Kind: KindCreate, Hint: "shape, e.g. 2, 3", Default: "2, 3", /* contains filtered or unexported fields */},
	{Name: "Ones", Kind: KindCreate, Hint: "shape, e.g. 2, 3", Default: "2, 3", /* contains filtered or unexported fields */},
	{Name: "Full", Kind: KindCreate, Hint: "value, shape…", Default: "7, 2, 3", /* contains filtered or unexported fields */},
	{Name: "Eye", Kind: KindCreate, Hint: "n, m, k (diagonal)", Default: "4, 4, 0", /* contains filtered or unexported fields */},
	{Name: "FromData", Kind: KindCreate, Hint: "[values], shape…", Default: "[1, 2, 3, 4, 5, 6], 2, 3", /* contains filtered or unexported fields */},

	{Name: "Reshape", Kind: KindUnary, Hint: "new shape, -1 is inferred", Default: "3, -1", /* contains filtered or unexported fields */},
	{Name: "Transpose", Kind: KindUnary, Hint: "(no arguments)", /* contains filtered or unexported fields */},
	{Name: "Slice", Kind: KindUnary, Hint: "NumPy indices: 1:3, ::2, 0, -1, :", Default: ":, 1:", /* contains filtered or unexported fields */},
	{Name: "Flatten", Kind: KindUnary, Hint: "(no arguments)", /* contains filtered or unexported fields */},
	{Name: "Copy", Kind: KindUnary, Hint: "(no arguments)", /* contains filtered or unexported fields */},
	{Name: "Squeeze", Kind: KindUnary, Hint: "axes to drop (none = every length-1 axis)", /* contains filtered or unexported fields */},
	{Name: "ExpandDims", Kind: KindUnary, Hint: "axis", Default: "0", /* contains filtered or unexported fields */},

	{Name: "Exp", Kind: KindUnary, Hint: "(no arguments)", /* contains filtered or unexported fields */},
	{Name: "Log", Kind: KindUnary, Hint: "(no arguments)", /* contains filtered or unexported fields */},
	{Name: "Sqrt", Kind: KindUnary, Hint: "(no arguments)", /* contains filtered or unexported fields */},
	{Name: "Sin", Kind: KindUnary, Hint: "(no arguments)", /* contains filtered or unexported fields */},
	{Name: "Cos", Kind: KindUnary, Hint: "(no arguments)", /* contains filtered or unexported fields */},
	{Name: "Abs", Kind: KindUnary, Hint: "(no arguments)", /* contains filtered or unexported fields */},
	{Name: "Square", Kind: KindUnary, Hint: "(no arguments)", /* contains filtered or unexported fields */},
	{Name: "Power", Kind: KindUnary, Hint: "exponent", Default: "2", /* contains filtered or unexported fields */},
	{Name: "Clip", Kind: KindUnary, Hint: "lo, hi", Default: "2, 8", /* contains filtered or unexported fields */},

	{Name: "Sum", Kind: KindUnary, Hint: "axis[, keepdims] (none = whole array)", Default: "0", /* contains filtered or unexported fields */},
	{Name: "Mean", Kind: KindUnary, Hint: "axis[, keepdims] (none = whole array)", Default: "0", /* contains filtered or unexported fields */},
	{Name: "Max", Kind: KindUnary, Hint: "axis[, keepdims] (none = whole array)", Default: "1", /* contains filtered or unexported fields */},
	{Name: "Min", Kind: KindUnary, Hint: "axis[, keepdims] (none = whole array)", Default: "1", /* contains filtered or unexported fields */},
	{Name: "ArgMax", Kind: KindUnary, Hint: "axis[, keepdims] (none = flat index)", Default: "1", /* contains filtered or unexported fields */},
	{Name: "CumSum", Kind: KindUnary, Hint: "axis (none = flattened)", Default: "0", /* contains filtered or unexported fields */},

	{Name: "Add", Kind: KindBinary, Hint: "a step name, or a number", Default: "10", /* contains filtered or unexported fields */},
	{Name: "Sub", Kind: KindBinary, Hint: "a step name, or a number", Default: "1", /* contains filtered or unexported fields */},
	{Name: "Mul", Kind: KindBinary, Hint: "a step name, or a number", Default: "2", /* contains filtered or unexported fields */},
	{Name: "Div", Kind: KindBinary, Hint: "a step name, or a number", Default: "2", /* contains filtered or unexported fields */},
	{Name: "Maximum", Kind: KindBinary, Hint: "a step name", /* contains filtered or unexported fields */},
	{Name: "Minimum", Kind: KindBinary, Hint: "a step name", /* contains filtered or unexported fields */},
	{Name: "MatMul", Kind: KindBinary, Hint: "a step name", /* contains filtered or unexported fields */},
	{Name: "Dot", Kind: KindBinary, Hint: "a step name", /* contains filtered or unexported fields */},
	{Name: "Outer", Kind: KindBinary, Hint: "a step name", /* contains filtered or unexported fields */},

	{Name: "Concatenate", Kind: KindJoin, Hint: "other steps…, axis", /* contains filtered or unexported fields */},
	{Name: "Stack", Kind: KindJoin, Hint: "other steps…, axis", /* contains filtered or unexported fields */},
}

Ops is the catalog, in menu order.

View Source 
var Presets = []Preset{
	{Name: "The README example", Calls: []Call{
		{"Arange", "", "0, 6, 1"},
		{"Reshape", "a", "2, -1"},
		{"FromData", "", "[10, 20, 30]"},
		{"Transpose", "b", ""},
		{"Sum", "b", "0"},
		{"Slice", "b", ":, 0"},
		{"Add", "b", "c"},
	}},
	{Name: "Views share data", Calls: []Call{
		{"Arange", "", "0, 24, 1"},
		{"Reshape", "a", "4, 6"},
		{"Transpose", "b", ""},
		{"Slice", "b", "1:3, ::2"},
		{"Slice", "b", "::-1, -1"},
		{"Copy", "d", ""},
	}},
	{Name: "Broadcasting", Calls: []Call{
		{"Arange", "", "0, 4, 1"},
		{"Reshape", "a", "4, 1"},
		{"Linspace", "", "0, 1, 5"},
		{"Mul", "b", "c"},
		{"Add", "d", "100"},
	}},
	{Name: "Reductions along an axis", Calls: []Call{
		{"Arange", "", "1, 13, 1"},
		{"Reshape", "a", "3, 4"},
		{"Sum", "b", "0"},
		{"Mean", "b", "1, keepdims"},
		{"Max", "b", ""},
		{"ArgMax", "b", "1"},
		{"CumSum", "b", "1"},
	}},
	{Name: "Ufuncs on a grid", Calls: []Call{
		{"Linspace", "", "0, 6.283185307179586, 16"},
		{"Reshape", "a", "1, 16"},
		{"Reshape", "a", "16, 1"},
		{"Sin", "b", ""},
		{"Cos", "c", ""},
		{"Mul", "d", "e"},
	}},
	{Name: "Concatenate and stack", Calls: []Call{
		{"Ones", "", "2, 3"},
		{"Full", "", "5, 2, 3"},
		{"Concatenate", "a", "b, 0"},
		{"Concatenate", "a", "b, 1"},
		{"Stack", "a", "b, 0"},
	}},
	{Name: "Linear algebra", Calls: []Call{
		{"Arange", "", "0, 6, 1"},
		{"Reshape", "a", "2, 3"},
		{"Transpose", "b", ""},
		{"MatMul", "b", "c"},
		{"Eye", "", "3, 3, 0"},
		{"Dot", "c", "b"},
		{"Outer", "a", "a"},
	}},
	{Name: "A shape mismatch", Calls: []Call{
		{"Arange", "", "0, 6, 1"},
		{"Reshape", "a", "2, 3"},
		{"Ones", "", "3, 2"},
	}, Next: &Call{"Add", "b", "c"}},
}

Presets are the examples offered in the menu. The first is what the page opens on; it is the README's example.

Functions

func Flat 

func Flat(a *ndarray.Array) []float64

Flat returns the values of a in row-major order, as Ruby's to_a and NumPy's ravel list them.

func FormatValue 

func FormatValue(v float64) string

FormatValue writes one value for a table cell: six significant digits.

func ShapeText 

func ShapeText(shape []int) string

ShapeText writes a shape as NumPy prints it: "(2, 3)", "(3,)", "()".

func SharesMemory 

func SharesMemory(x, y Layout) bool

SharesMemory reports whether two layouts point into overlapping storage, i.e. whether writing through one could change the other — NumPy's np.shares_memory, answered from the storage spans.

func StepName 

func StepName(i int) string

StepName returns the name of the i-th step (0-based): a, b, …, z, then a1, b1, …, so every name is a valid identifier in both Go and Python that is not a keyword of either.

Types

type Call 

type Call struct{ Op, Input, Args string }

Call is one step of a preset: an operation, its input and its arguments.

type Grid 

type Grid struct {
	Values    [][]float64
	RowLabels []string
	ColLabels []string
	Rows      int // rows of the whole 2-D view (Values may hold fewer)
	Cols      int
	Note      string
	Min, Max  float64 // over the finite shown values; Min > Max when none
}

Grid is the part of an array the value table shows: a 2-D window of it. A 0-d or 1-D array is one row; an array of more than two axes shows the last two axes at index 0 of every leading axis, and Note says so.

func GridOf 

func GridOf(a *ndarray.Array) Grid

GridOf reads the window of a the table shows.

type Kind 

type Kind int

Kind says what an operation takes. 

const (
	// KindCreate builds a new array from its arguments alone.
	KindCreate Kind = iota
	// KindUnary acts on one input array (a view, a ufunc, a reduction).
	KindUnary
	// KindBinary combines the input array with one operand: another step, or
	// for the four arithmetic operations a number.
	KindBinary
	// KindJoin joins the input array with other steps along an axis.
	KindJoin
)

type Layout 

type Layout struct {
	Shape   []int
	Strides []int // in elements
	Offset  int   // in elements, from the start of the storage
	// contains filtered or unexported fields
}

Layout is how an array sits in memory, read from go-ndarray's own Array value: its shape, its strides and offset (in elements, the unit go-ndarray stores them in), and the span of the storage it points into.

go-ndarray v0.7.1 exports neither the strides nor the storage, so Layout reads the unexported fields through reflect — read-only, and without unsafe. This is the one place the playground depends on go-ndarray's internals; TestLayoutReadsTheLibrary fails if the fields are renamed, so a library change cannot silently turn the panel into a guess.

func LayoutOf 

func LayoutOf(a *ndarray.Array) Layout

LayoutOf reads a's layout. A nil array has the zero Layout.

func (Layout) ByteStrides 

func (l Layout) ByteStrides() []int

ByteStrides is Strides in bytes, the unit NumPy's .strides reports.

func (Layout) Contiguous 

func (l Layout) Contiguous() bool

Contiguous reports whether the layout is C-contiguous: its strides are the row-major strides of its shape (axes of length 1 may have any stride).

type Op 

type Op struct {
	Name    string // the go-ndarray name, as listed in the operation menu
	Kind    Kind
	Hint    string // what the argument line holds
	Default string // a sensible argument line to start from
	// contains filtered or unexported fields
}

Op is one operation of the playground's catalog.

func OpByName 

func OpByName(name string) (Op, bool)

OpByName finds an operation of the catalog.

type Preset 

type Preset struct {
	Name  string
	Calls []Call
	// Next, when set, is filled into the form after loading, not applied:
	// the visitor presses Apply and sees what happens.
	Next *Call
}

Preset is a ready-made pipeline that shows one idea.

type Session 

type Session struct {
	Steps []Step
	// Clock is the time source for timing; nil means time.Now.
	Clock func() time.Time
}

Session is a pipeline of steps.

func (*Session) Apply 

func (s *Session) Apply(opName, input, args string) (Step, error)

Apply runs one operation and appends it as a new step. input names the step the operation reads (ignored for creation). An error — a bad argument line, or go-ndarray's own error — appends nothing.

func (*Session) GoProgram 

func (s *Session) GoProgram() string

GoProgram is the whole pipeline as a Go program that compiles and prints every step, so it can be pasted into a file and run.

func (*Session) Load 

func (s *Session) Load(p Preset) error

Load replaces the session's steps with a preset's. It stops at the first call that fails and returns its error, keeping the steps before it.

func (*Session) Names 

func (s *Session) Names() []string

Names lists the steps whose result is an array, the possible inputs.

func (*Session) PyProgram 

func (s *Session) PyProgram() string

PyProgram is the same pipeline in NumPy.

func (*Session) RbProgram 

func (s *Session) RbProgram(sel int) string

RbProgram is the same pipeline in Ruby, for go-embedded-ruby, whose NDArray is go-ndarray bound into the interpreter. It prints every step, then the shape and the flat, row-major values of step sel (the last step when sel is out of range), so a run can be checked against the Go result.

func (*Session) RemoveLast 

func (s *Session) RemoveLast()

RemoveLast drops the last step.

func (*Session) Reset 

func (s *Session) Reset()

Reset drops every step.

type Step 

type Step struct {
	Name  string // the variable the result is bound to: a, b, c, …
	Op    string
	Input string // the step the operation reads; "" for creation
	Args  string

	Result *ndarray.Array // a 0-d array for a reduction to a number
	Scalar bool           // the Go call returns a number, not an *Array
	Layout Layout
	Shares []string // earlier steps whose memory the result points into

	Go    string // the Go statement
	GoErr bool   // the Go call returns an error too
	Py    string // the NumPy statement
	Rb    string // the Ruby statement (go-embedded-ruby)

	Elapsed time.Duration // mean wall time of one call
	Runs    int           // how many calls the mean is over
}

Step is one applied operation and its result.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.