Documentation ¶
Overview ¶
Package numgo provides implementations of n-dimensional array objects and operations.
Two types of numgo arrays are currently supported: Array64 holds float64 values Arrayb holds boolean values
Basic usage ¶
Array64 objects can be created from a slice or as an empty array. Arange and Identity are convenience creation functions.
array := numgo.NewArray64(nil,1,2,3) // This 1x2x3 array will be filled with zeros by default sl := []float64{2,2,3,3,4,4} wrap := numgo.NewArray64(sl) // Wrap a copy of the slice as a 1-D Array64 wrap2 := numgo.NewArray64(sl,3,2) // Wrap a copy of the slice as a 3x2 Array64 wrap3 := numgo.NewArray64(sl,2,2) // Only wraps the first 4 values in sl as a 2x2 Array64 arange := numgo.Arange(100) // Simple 1-D array filled with incrementing numbers arange.Reshape(2,5,10) // Changes the shape from 1-D to 3-D arange.Mean(2) // Mean across axis 2, returning a 2-D (2x5) array arange.Sum() // An empty call operates on all data (Grand Total)
Fold and Map operations ¶
Map takes a function of type MapFunc and applies it across all data elements. Fold and FoldCC take a function of type FoldFunc and applies it in contracting the data across one or more axes.
// Increment MapFunc definition increment := func(input float64) float64 { return input + 1 } array.Map(increment) // Using map with defined function array.AddC(1) // Using built-in add method // Create a FoldFunc sumFn := func(input []float64) float64 { var t float64 :=0 for _,v := range input { t += v } return t } // Pass it into the Map method and give it any number of axes to map over // Returns an n-dimensional array object // with the count of NaN values on 2nd and 4th axes. (0-based axis count) array.Fold(sumFn, 2,4) // No axes operates over all data on all axes array.Fold(sumfn)
Function Chaining ¶
numgo is designed with function-chaining at its core, to allow different actions on different axes and at different points in the calculation. Errors are maintained by the object and can be checked and handled using HasErr() and GetErr():
// Errors are not handled on each call, // but, instead, can be checked and handled after a block of calculations ng := numgo.Arange(100).Reshape(2,5,10).Mean(2).Min(1).Max() // Non-allocating style if ng.HasErr() { log.Println(ng.GetErr()) // GetErr() clears the error flag } // Allocation style if err = ng.GetErr(); err != nil { log.Println(err) } // ng.GetErr() will always return nil here, // so avoid stacking this type of error handling
Debugging options ¶
Debugging can be enabled by calling numgo.Debug(true). This will give detailed error strings by using GetDebug() instead of GetErr(). This makes debugging chained method calls much easier.
numgo.Debug(true) nilp := new(Array64) // Forgot to initialize the array. nilp.Set(12, 1,4,0).AddC(2).DivC(6).At(1,4,0) if nilp.HasErr(){ err, debug, trace := nilp.GetDebug() // Prints generic error: "Nil pointer received." fmt.Println(err) // Prints debug info: // "Nil pointer received by GetDebug(). Source array was not initialized." fmt.Println(debug) // Prints stack trace for the call to GetDebug() fmt.Println(trace) } resz := NewArray64(nil, 2, 5) // 2-D (2x5) array of zeros // Reshape would change the capacity of the array, which should use Resize resz.AddC(10).DivC(2).Reshape(3,3).Mean(1) if resz.HasErr() { err, debug, trace := resz.GetDebug() // Prints generic error: "New shape cannot change the size of the array." fmt.Println(err) // Prints debug info: // "Reshape() cannot change data size. Dimensions: [2,5] reshape: [3,3]" fmt.Println(debug) // Prints stack trace for the call to Reshape() fmt.Println(trace) }
Index ¶
- Variables
- func Debug(set bool) bool
- type Array64
- func Arange(vals ...float64) (a *Array64)
- func FullArray64(val float64, shape ...int) (a *Array64)
- func Identity(size int) (r *Array64)
- func MaxSet(arrSet ...*Array64) (b *Array64)
- func MinSet(arrSet ...*Array64) (b *Array64)
- func NewArray64(data []float64, shape ...int) (a *Array64)
- func RandArray64(base, scale float64, shape ...int) (a *Array64)
- func (a *Array64) Add(b *Array64) *Array64
- func (a *Array64) AddC(b float64) *Array64
- func (a *Array64) Append(val *Array64, axis int) *Array64
- func (a *Array64) At(index ...int) float64
- func (a *Array64) C() (b *Array64)
- func (a *Array64) Count(axis ...int) *Array64
- func (a *Array64) Div(b *Array64) *Array64
- func (a *Array64) DivC(b float64) *Array64
- func (a *Array64) DotProd(b *Array64) *Array64
- func (a *Array64) Equals(b *Array64) (r *Arrayb)
- func (a *Array64) FMA12(x float64, b *Array64) *Array64
- func (a *Array64) FMA21(x float64, b *Array64) *Array64
- func (a *Array64) Flatten() *Array64
- func (a *Array64) Fold(f FoldFunc, axis ...int) (ret *Array64)
- func (a *Array64) FoldCC(f FoldFunc, axis ...int) (ret *Array64)
- func (a *Array64) GetDebug() (err error, debugStr, stackTrace string)
- func (a *Array64) GetErr() (err error)
- func (a *Array64) Greater(b *Array64) (r *Arrayb)
- func (a *Array64) GreaterEq(b *Array64) (r *Arrayb)
- func (a *Array64) HasErr() bool
- func (a *Array64) Less(b *Array64) (r *Arrayb)
- func (a *Array64) LessEq(b *Array64) (r *Arrayb)
- func (a *Array64) Map(f MapFunc) (ret *Array64)
- func (a *Array64) MarshalJSON() ([]byte, error)
- func (a *Array64) MatProd(b *Array64) *Array64
- func (a *Array64) Max(axis ...int) (r *Array64)
- func (a *Array64) Mean(axis ...int) *Array64
- func (a *Array64) Min(axis ...int) (r *Array64)
- func (a *Array64) Mult(b *Array64) *Array64
- func (a *Array64) MultC(b float64) *Array64
- func (a *Array64) NaNCount(axis ...int) *Array64
- func (a *Array64) NaNMean(axis ...int) *Array64
- func (a *Array64) NaNSum(axis ...int) *Array64
- func (a *Array64) Nonzero(axis ...int) *Array64
- func (a *Array64) NotEq(b *Array64) (r *Arrayb)
- func (a *Array64) Pow(b *Array64) *Array64
- func (a *Array64) PowC(b float64) *Array64
- func (a *Array64) Reshape(shape ...int) *Array64
- func (a *Array64) Resize(shape ...int) *Array64
- func (a *Array64) Set(val float64, index ...int) *Array64
- func (a *Array64) SetSliceElement(vals []float64, index ...int) *Array64
- func (a *Array64) SetSubArr(vals *Array64, index ...int) *Array64
- func (a *Array64) Shape() []int
- func (a *Array64) SliceElement(index ...int) (ret []float64)
- func (a *Array64) String() (s string)
- func (a *Array64) SubArr(index ...int) (ret *Array64)
- func (a *Array64) Subtr(b *Array64) *Array64
- func (a *Array64) SubtrC(b float64) *Array64
- func (a *Array64) Sum(axis ...int) (r *Array64)
- func (a *Array64) UnmarshalJSON(b []byte) error
- type Arrayb
- func (a *Arrayb) All(axis ...int) *Arrayb
- func (a *Arrayb) Any(axis ...int) *Arrayb
- func (a *Arrayb) Append(val *Arrayb, axis int) *Arrayb
- func (a *Arrayb) At(index ...int) bool
- func (a *Arrayb) C() (b *Arrayb)
- func (a *Arrayb) Equals(b *Arrayb) (r *Arrayb)
- func (a *Arrayb) GetDebug() (err error, debugStr, stackTrace string)
- func (a *Arrayb) GetErr() (err error)
- func (a *Arrayb) HasErr() bool
- func (a *Arrayb) MarshalJSON() ([]byte, error)
- func (a *Arrayb) NotEq(b *Arrayb) (r *Arrayb)
- func (a *Arrayb) Reshape(shape ...int) *Arrayb
- func (a *Arrayb) Resize(shape ...int) *Arrayb
- func (a *Arrayb) Set(val bool, index ...int) *Arrayb
- func (a *Arrayb) SetSliceElement(vals []bool, index ...int) *Arrayb
- func (a *Arrayb) SetSubArr(vals *Arrayb, index ...int) *Arrayb
- func (a *Arrayb) SliceElement(index ...int) (ret []bool)
- func (a *Arrayb) String() (s string)
- func (a *Arrayb) SubArr(index ...int) (ret *Arrayb)
- func (a *Arrayb) UnmarshalJSON(b []byte) error
- type FoldFunc
- type MapFunc
Constants ¶
This section is empty.
Variables ¶
var ( // NilError flags any error where a nil pointer is received NilError = &ngError{"NilError: Nil pointer recieved."} // ShapeError flags any mismatching ShapeError = &ngError{"ShapeError: Array shapes don't match and can't be broadcast."} // ReshapeError flags incorrect use of Reshape() calls. // Resize() is the only call that can change the capacity of arrays. ReshapeError = &ngError{"ReshapeError: New shape cannot change the size of the array."} // NegativeAxis is forNew/Reshape/Resize calls with negative axis length: not allowed NegativeAxis = &ngError{"NegativeAxis: Negative axis length received."} // IndexError flags any attempt to index out of range IndexError = &ngError{"IndexError: Index or Axis out of range."} // InvIndexError flags Negative or illegal indexes InvIndexError = &ngError{"InvIndexError: Invalid or illegal index received."} // FoldMapError catches panics within Fold/FoldCC/Map calls. // This will store the panic message in the debug string // when debugging is turned off, for proper errror reporting FoldMapError = &ngError{"FoldMapError: Fold/Map function panic encountered."} )
Functions ¶
func Debug ¶
Debug sets the error reporting level for the library. To get debugging data from the library, set this to true and use GetDebug() in place of GetErr().
Debugging information includes the function call that generated the error, stack trace at the point the error was generated, and the values involved in that function call. This will add overhead to error reporting and handling, so use it for development and debugging purposes.
Types ¶
type Array64 ¶
type Array64 struct {
// contains filtered or unexported fields
}
Array64 is an n-dimensional array of float64 data
func Arange ¶
Arange Creates an array in one of three different ways, depending on input:
Arange(stop): Array64 from zero to positive value or negative value to zero Arange(start, stop): Array64 from start to stop, with increment of 1 or -1, depending on inputs Arange(start, stop, step): Array64 from start to stop, with increment of step
Any inputs beyond three values are ignored
func FullArray64 ¶
FullArray64 creates an Array64 object with dimensions given in order from outer-most to inner-most All elements will be set to the value passed in val.
func Identity ¶
Identity creates a size x size matrix with 1's on the main diagonal. All other values will be zero.
Negative size values will generate an error and return a nil value.
func MaxSet ¶
MaxSet will return the element-wise maximum of arrays.
All arrays must be the non-nil and the same shape.
func MinSet ¶
MinSet will return the element-wise maximum of arrays.
All arrays must be the non-nil and the same shape.
func NewArray64 ¶
NewArray64 creates an Array64 object with dimensions given in order from outer-most to inner-most Passing a slice with no shape data will wrap the slice as a 1-D array. All values will default to zero. Passing nil as the data parameter creates an empty array.
func RandArray64 ¶
RandArray64 creates an Arry64 object and fills it with random values from the default random source Use base and scale to adjust the default value range [0.0, 1.0) generated by formula rand * scale + default
func (*Array64) Add ¶
Add performs element-wise addition Arrays must be the same size or able to broadcast. This will modify the source array.
func (*Array64) Append ¶
Append will concatenate a and val at the given axis.
Source array will be changed, so use C() if the original data is needed. All axes must be the same except the appending axis.
func (*Array64) At ¶
At returns the element at the given index. There should be one index per axis. Generates a ShapeError if incorrect index.
func (*Array64) Count ¶
Count gives the number of elements along a set of axis. Value in the element is not tested, all elements are counted.
func (*Array64) Div ¶
Div performs element-wise division Arrays must be the same size or able to broadcast. Division by zero conforms to IEEE 754 0/0 = NaN, +x/0 = +Inf, -x/0 = -Inf This will modify the source array.
func (*Array64) DivC ¶
DivC divides all elements of the array by a constant. Division by zero conforms to IEEE 754 0/0 = NaN, +x/0 = +Inf, -x/0 = -Inf
func (*Array64) DotProd ¶
DotProd calculates the dot (scalar) product of two vectors. NOTE: Only implemented on 1-D arrays, and other sizes are NOOP
func (*Array64) FMA12 ¶
FMA12 is the fuse multiply add functionality. Array x will contain a[i] = x*a[i]+b[i]
func (*Array64) FMA21 ¶
FMA21 is the fuse multiply add functionality. Array x will contain a[i] = a[i]*b[i]+x
func (*Array64) Fold ¶
Fold applies function f along the given axes. Slice containing all data to be consolidated into an element will be passed to f. Return value will be the resulting element's value.
func (*Array64) FoldCC ¶
FoldCC applies function f along the given axes concurrently. Each call to f will launch a goroutine. In order to leverage this concurrency, MapCC should only be used for complex and CPU-heavy functions.
Simple functions should use Fold(f, axes...), as it's more performant on small functions.
func (*Array64) GetDebug ¶
GetDebug returns and clears the error object from the array object. The returned debug string will include the function that generated the error and the arguments that caused it.
This debug information will only be generated and returned if numgo.Debug is set to true before the function call that causes the error.
func (*Array64) GetErr ¶
GetErr returns the error object and clears the error from the array.
This will only return an error value once per error instance. Do not use it in the if statement to test for the existence of an error. HasErr() is provided for that purpose.
func (*Array64) HasErr ¶
HasErr tests for the existence of an error on the Array64 object.
Errors will be maintained through a chain of function calls, so only the first error will be returned when GetErr() is called. Use HasErr() as a gate for the GetErr() or GetDebug() choice in error handling code.
func (*Array64) MarshalJSON ¶
MarshalJSON fulfills the json.Marshaler Interface for encoding data. Custom Unmarshaler is needed to encode/send unexported values.
func (*Array64) Mean ¶
Mean calculates the mean across the given axes. NaN values in the dataa will result in NaN result elements.
func (*Array64) Mult ¶
Mult performs element-wise multiplication. Arrays must be the same size or able to broadcast. This will modify the source array.
func (*Array64) NaNCount ¶
NaNCount calculates the number of values along a given axes. Empty call gives the total number of elements.
func (*Array64) NaNMean ¶
NaNMean calculates the mean across the given axes. NaN values are ignored in this calculation.
func (*Array64) NaNSum ¶
NaNSum calculates the sum result array along a given axes. All NaN values will be ignored in the Sum calculation. If all element values along the axis are NaN, NaN is in the return element.
Empty call gives the grand sum of all elements.
func (*Array64) Pow ¶
Pow raises elements of a to the corresponding power in b. Arrays must be the same size or able to broadcast. This will modify the source array.
func (*Array64) PowC ¶
PowC raises all elements to a constant power. Negative powers will result in a math.NaN() values.
func (*Array64) Reshape ¶
Reshape Changes the size of the array axes. Values are not changed or moved. This must not change the size of the array. Incorrect dimensions will return a nil pointer
func (*Array64) Resize ¶
Resize will change the underlying array size.
Make a copy C() if the original array needs to remain unchanged. Element location in the underlying slice will not be adjusted to the new shape.
func (*Array64) Set ¶
Set sets the element at the given index. There should be one index per axis. Generates a ShapeError if incorrect index.
func (*Array64) SetSliceElement ¶
SetSliceElement sets the element group at one axis above the leaf elements. Source Array is returned, for function-chaining design.
func (*Array64) SetSubArr ¶
SetSubArr sets the array below a given index to the values in vals. Values will be broadcast up multiple axes if the shapes match.
func (*Array64) SliceElement ¶
SliceElement returns the element group at one axis above the leaf elements. Data is returned as a copy in a float slice.
func (*Array64) Subtr ¶
Subtr performs element-wise subtraction. Arrays must be the same size or albe to broadcast. This will modify the source array.
func (*Array64) Sum ¶
Sum calculates the sum result array along a given axes. Empty call gives the grand sum of all elements.
func (*Array64) UnmarshalJSON ¶
UnmarshalJSON fulfills the json.Unmarshaler interface for decoding data. Custom Unmarshaler is needed to load/decode unexported values and build strides.
type Arrayb ¶
type Arrayb struct {
// contains filtered or unexported fields
}
Arrayb is an n-dimensional array of boolean values
func Fullb ¶
Fullb creates an Arrayb object with dimensions givin in order from outer-most to inner-most All elements will be set to 'val' in the returned array.
func NewArrayB ¶
NewArrayB creates an Arrayb object with dimensions given in order from outer-most to inner-most All values will default to false
func (*Arrayb) Append ¶
Append will concatenate a and val at the given axis.
Source array will be changed, so use C() if the original data is needed. All axes must be the same except the appending axis.
func (*Arrayb) At ¶
At returns a copy of the element at the given index. Any errors will return a false value and record the error for the HasErr() and GetErr() functions.
func (*Arrayb) GetDebug ¶
GetDebug returns and clears the error object from the array object. The returned debug string will include the function that generated the error and the arguments that caused it.
This debug information will only be generated and returned if numgo.Debug is set to true before the function call that causes the error.
func (*Arrayb) GetErr ¶
GetErr returns the error object and clears the error from the array.
This will only return an error value once per error instance. Do not use it in the if statement to test for the existence of an error. HasErr() is provided for that purpose.
func (*Arrayb) HasErr ¶
HasErr tests for the existence of an error on the Arrayb object.
Errors will be maintained through a chain of function calls, so only the first error will be returned when GetErr() is called. Use HasErr() as a gate for the GetErr() or GetDebug() choice in error handling code.
func (*Arrayb) MarshalJSON ¶
MarshalJSON fulfills the json.Marshaler Interface for encoding data. Custom Unmarshaler is needed to encode/send unexported values.
func (*Arrayb) Reshape ¶
Reshape Changes the size of the array axes. Values are not changed or moved. This must not change the size of the array. Incorrect dimensions will return a nil pointer
func (*Arrayb) Resize ¶
Resize will change the underlying array size.
Make a copy C() if the original array needs to remain unchanged. Element location in the underlying slice will not be adjusted to the new shape.
func (*Arrayb) Set ¶
Set sets the element at the given index. There should be one index per axis. Generates a ShapeError if incorrect index.
func (*Arrayb) SetSliceElement ¶
SetSliceElement sets the element group at one axis above the leaf elements. Source Array is returned, for function-chaining design.
func (*Arrayb) SetSubArr ¶
SetSubArr sets the array below a given index to the values in vals. Values will be broadcast up multiple axes if the shapes match.
func (*Arrayb) SliceElement ¶
SliceElement returns the element group at one axis above the leaf elements. Data is returned as a copy in a float slice.
func (*Arrayb) SubArr ¶
SubArr slices the array object by the index received on each corresponding axis.
These are applied startig from the top axis. Intermediate slicing of axes is not available at this point.
func (*Arrayb) UnmarshalJSON ¶
UnmarshalJSON fulfills the json.Unmarshaler interface for decoding data. Custom Unmarshaler is needed to load/decode unexported values and build strides.