README
¶
mat
-- import "github.com/NDari/gocrunch/mat"
Package mat implements a large set of functions which act on one and two
dimensional slices of float64. For functions that act on one dimensional
slices of float64, look at the gocrunch/vec package.
Many of the functions in this library expect either a float64, a []float64, or [][]float64, and do "the right thing" based on what is passed. For example, consider the function
mat.Mul(m, n)
In this function, m can be a [][]float64, where as n could be a float64, []float64, or [][]float64. This allows the same function to be called for wide range of situations. This trades compile time safety for runtime errors. We believe that Go's fast compile time, along with the verbose errors in this package make up for that, however.
All errors encountered in this package, such as attempting to access an element out of bounds are treated as critical error, and thus, the code immediately panics. In such cases, the function in which the error was encountered is printed to the screen along with the reason for the panic, in addition to the full stack trace, in order to help fix any issues rapidly.
As mentioned, all the functions in this library act on Go primitive types, which allows the code to be easily modified to serve in different situations.
Usage
Create a square matrix, and a non-square matrix:
m, n := mat.New(10), mat.New(10, 5)
Create an Identity matrix:
q := mat.I(10)
Set all values of m to 11.0:
mat.Set(m, 11.0)
Check if all elements of m are set to 11.0:
isEleven := func(i float64) float64 {
if i == 11.0 {
return true
}
return false
}
if !mat.All(m, isEleven) {
log.Fatal("Non-11 values found!")
}
Calculate the dot product of m with the identity matrix:
m2 := mat.Dot(m, q)
Check if m and m2 are equal:
if !mat.Equal(m, m2) {
log.Fatal("We have a problem...")
}
Documentation
Full documentation is under badges, below.
Badges
Documentation
¶
Overview ¶
Package mat implements a large set of functions which act on two dimensional slices of float64.
Many of the functions in this library expect either a float64, a []float64, or [][]float64, and do "the right thing" based on what is passed. For example, consider the function
mat.Mul(m, n)
In this function, m is a [][]float64, where as n could be a float64, []float64, or [][]float64. This allows the same function to be called for wide range of situations. This trades compile time safety for runtime errors. We believe that Go's fast compile time, along with the verbose errors in this package make up for that, however.
All errors encountered in this package, such as attempting to access an element out of bounds are treated as critical error, and thus, the code immediately panics. In such cases, the function in which the error was encountered is printed to the screen along with the reason for the panic, in addition to the full stack trace, in order to help fix any issues rapidly.
As mentioned, all the functions in this library act on Go primitive types, which allows the code to be easily modified to serve in different situations.
Index ¶
- func Add(m [][]float64, val interface{}) [][]float64
- func All(m [][]float64, f func(float64) bool) bool
- func Any(m [][]float64, f func(float64) bool) bool
- func AppendCol(m [][]float64, v []float64) [][]float64
- func Avg(m [][]float64, args ...int) float64
- func Clone(m [][]float64) [][]float64
- func Col(m [][]float64, x int) []float64
- func Div(m [][]float64, val interface{}) [][]float64
- func Dot(m, n [][]float64) [][]float64
- func Equal(m, n [][]float64) bool
- func Flatten(m [][]float64) []float64
- func Foreach(m [][]float64, f func(float64) float64) [][]float64
- func FromCSV(filename string) [][]float64
- func I(x int) [][]float64
- func Mul(m [][]float64, val interface{}) [][]float64
- func New(dims ...int) [][]float64
- func Prod(m [][]float64, args ...int) float64
- func Rand(x, y int, args ...float64) [][]float64
- func Row(m [][]float64, x int) []float64
- func Set(m [][]float64, val float64) [][]float64
- func Sub(m [][]float64, val interface{}) [][]float64
- func Sum(m [][]float64, args ...int) float64
- func T(m [][]float64) [][]float64
- func ToCSV(m [][]float64, fileName string) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Add ¶
Add adds a passed value in the second argument to the [][]float64 in the first argument. The second argument can be a float64, a 1D slice of float64, or a [][]float64.
When the passed value is a float64, the passed value is added to each element of the [][]float64.
If the passed value is a []float64, then the elements of the []float64 are elementally added by the corresponding entries in each row of the [][]float64. The length of the []float64 must match the length of each row of the [][]float64.
Finally, if the passed value is a [][]float64, then mat.Add() takes each element of the first [][]float64 passed to it, and adds to that element the corresponding element in the second [][]float64 passed to this function. The shape of the [][]float64s must be the same (same number or rows and columns), and they are assumed to be non-jagged (same number of elements in each row).
The original [][]float64 (the first arg of this function) is not mutated in this function.
func All ¶
All checks if a supplied function is true for all elements of a mat object. The supplied function is expected to have the signature of a function that takes a float64, returning a bool. For instance, consider
positive := func(i float64) bool {
if i > 0.0 {
return true
}
return false
}
Then calling
mat.All(m, positive)
will return true if and only if all elements in m are positive.
func Any ¶
Any checks if a supplied function is true for at least one elements of a [][]float64. The supplied function must have the signature of a function that takes a float64, and returns a bool. For instance,
positive := func(i float64) bool {
if i > 0.0 {
return true
}
return false
}
Then calling
mat.Any(m, positive)
would be true if at least one element of the m is positive.
func AppendCol ¶
AppendCol returns a copy of a passed [][]float64, with the second argument, a []float64, appended to its right side. For example, consider:
m := mat.New(2, 2) // [[0.0, 0.0], [0.0, 0.0]]
v := []float64{1.0, 2.0}
n := mat.AppendCol(m, v) // [[0.0, 0.0, 1.0], [0.0, 0.0, 2.0]]
The passed arguments are not mutated by this function.
func Avg ¶
Avg returns the average value of all the elements in a [][]float64. For example:
m := mat.New(12, 13) mat.Set(m, 1.0) x := mat.Avg(m) // x is 1.0
It's also possible to return the sum of a specific row or column in a [][]float64, by passing two additional integers to it: The first integer must be either 0 for picking a row, or 1 for picking a column. The second integer determines the specific row or column for which the average is desired. This function allow the index to be negative. For example, the average of the last row of a [][]float64 is given by:
mat.Avg(m, 0, -1)
where as the sum of the first column is given by:
mat.Avg(m, 1, 0)
The original [][]float64 is not mutated in this function.
func Clone ¶
Clone returns a duplicate of a [][]float64. The returned duplicate is "deep", meaning that the object can be manipulated without effecting the original.
func Col ¶
Col returns a column from a [][]float64. For example:
fmt.Println(m) // [[1.0, 2.3], [3.4, 1.7]] mat.Col(m, 0) // [1.0, 3.4]
Col also accepts negative indices. For example:
mat.Col(m, -1) // [2.3, 1.7]
The original [][]float64 is not mutated in this function.
func Div ¶
Div divides all elements of a [][]float64 by the passed value. The passed value can be a float64, []float64, or a [][]float64.
When the passed value is a float64, then each element of the [][]float64 is devided by the passed value. The passed value cannot be zero, and such condition will cause a panic.
If the passed value is a []float64, then each row of the [][]float64 is elementally divided by the corresponding entry in the passed []float64. Non of the elements of the []float64 can be zero, and such condition will cause a panic.
Finally, if the passed value is a [][]float64, then mat.Div() takes each element of the first [][]float64 passed to it, and devides that element by the corresponding element in the second [][]float64 passed to this function. The shape of the [][]float64 must be the same (same number or rows and columns), and they are assumed to be non-jagged (same number of elements in each row). As usual, no elements of the second [][]float64 are allowed to be 0.0, and such condition will cause a panic.
The original [][]float64 (the first arg of this function) is not mutated in this function.
func Dot ¶
Dot is the matrix product of two [][]float64. In essence, this means that each row of the first [][]float64 is multiplied by each column of the second [][]float64, which creates the first row of the result.
For the sake of simplicity, it is assumed that both passed [][]float64s are non-jagged, meaning that each row has the same number of entries as any other row in both [][]float64, and each column has the same number of entries as any other column in both [][]float64s passed to this function.
The original [][]float64s is not mutated in this function.
func Equal ¶
Equal checks to see if two [][]float64s are equal. That mean that the two slices have the same number of rows, same number of columns, and have the same float64 in each entry at a given set of indices.
func Flatten ¶
Flatten turns a [][]float64 into a 1D slice of float64. This is done by appending all rows tip to tail. The original [][]float 64 is not mutated in this function.
func Foreach ¶
Foreach applies a given function to each element of a [][]float64. The resultant [][]float64 is returned, leaving the orginal [][]float64 intact.
func FromCSV ¶
FromCSV creates a mat object from a CSV (comma separated values) file. Here, we assume that the number of rows of the resultant [][]float64 is equal to the number of lines, and the number of columns is equal to the number of entries in each line making sure that each line contains the same number of elements.
The file to be read is assumed to be very large, and hence it is read one line at a time.
func I ¶
I returns a square [][]float64 with all elements alone the diagonal equal to 1.0, and 0.0 elsewhere. This is the identity matrix.
func Mul ¶
Mul multiples all elements of a [][]float64 by the passed value. The passed value can be a float64, []float64, or a [][]float64.
When the passed value is a float64, then each element of the [][]float64 are multiplied by the passed value.
If the passed value is a []float64, then each row of the [][]float64 is elementally multiplied by the corresponding entry in the passed 1D slice.
Finally, if the passed value is a [][]float64, then mat.Mul() takes each element of the first [][]float64 passed to it, and multiples that element by the corresponding element in the second [][]float64 passed to this function. The shape of the [][]float64 must be the same (same number of rows, and same number of entries in each row).
The original [][]float64 (the first arg of this function) is not mutated in this function.
func New ¶
New is a utility function to create [][]float64s. New is a variadic function, expecting 0, 1 or 2 ints, with differing behavior as follows:
m := mat.New()
returns an empty [][]float64. A perhaps more useful option is:
m := mat.New(x)
which return a x by x (square) [][]float64. Alternatively
m := mat.New(x, y)
is a [][]float64 with x rows and y columns.
func Prod ¶
Prod returns the product of all elements in a [][]float64. For example:
m := mat.New(2, 2) mat.Set(m, 2.0) x := mat.Prod(m) // x is 16.0
It is also possible for this function to return the Product of a specific row or column in a [][]float64, by passing two additional integers to it: The first integer must be either 0 for picking a row, or 1 for picking a column. The second integer determines the specific row or column for which the product is desired. This function allow the index to be negative. For example, the product of the last row of a [][]float64 is given by:
mat.Prod(m, 0, -1)
where as the product of the first column is given by:
mat.Prod(m, 1, 0)
The original [][]float64 is not mutated in this function.
func Rand ¶
Rand creates a x by y [][]float64 with the entries set to random numbers. The x and y are integers which are passed to this function. The range from which the random numbers are selected is determined based on the arguments passed.
For no additional arguments, such as
mat.Rand(x, y)
the range is [0, 1)
For 1 argument, such as
mat.Rand(x, y, arg)
the range is [0, arg) for arg > 0, or (arg, 0] is arg < 0.
For 2 arguments, such as
mat.Rand(x, y, arg1, arg2)
the range is [arg1, arg2). For this case, arg1 must be less than arg2, or the function will panic.
func Row ¶
Row returns a row from a [][]float64. For example:
fmt.Println(m) // [[1.0, 2.3], [3.4, 1.7]] mat.Row(m, 0) // [1.0, 2.3]
Row also accepts negative indices. For example:
mat.Row(m, -1) // [3.4, 1.7]
The original [][]float64 is not mutated in this function.
func Sub ¶
Sub subtracts a passed value in the second argument from the [][]float64 in the first argument. The second argument can be a float64, a 1D slice of float64, or a [][]float64.
When the passed value is a float64, the passed value is subtracted from each element of the [][]float64.
If the passed value is a []float64, then the elements of the []float64 are elementally subtracted from the corresponding entries in each row of the [][]float64. The length of the []float64 must match the length of each row of the [][]float64.
Finally, if the passed value is a [][]float64, then mat.Sub() takes each element of the first [][]float64 passed to it, and subtracts that element from the corresponding element in the second [][]float64 passed to this function. The shape of the [][]float64 must be the same (same number or rows and columns), and they are assumed to be non-jagged (same number of elements in each row).
The original [][]float64 (the first arg of this function) is not mutated in this function.
func Sum ¶
Sum returns the sum of all elements in a [][]float64. For example:
m := mat.New(10, 5) mat.Set(m, 1.0) x := mat.Sum(m) // x is 50.0
It is also possible for this function to return the sum of a specific row or column in a [][]float64, by passing two additional integers to it: The first integer must be either 0 for picking a row, or 1 for picking a column. The second integer determines the specific row or column for which the sum is desired. This function allow the index to be negative. For example, the sum of the last row of a [][]float64 is given by:
mat.Sum(m, 0, -1)
where as the sum of the first column is given by:
mat.Sum(m, 1, 0)
The original [][]float64 is not mutated in this function.
func T ¶
T returns the transpose of the original [][]float64. The transpose of a [][]float64 is defined in the usual manner, where every value at row x, and column y is placed at row y, and column x. The number of rows and column of the transpose of a slice are equal to the number of columns and rows of the original slice, respectively. This method creates a new [][]float64, and the original is left intact. The passed [][]float64 is assumed to be non-jagged.
func ToCSV ¶
ToCSV writes the content of a passed [][]float64 into a CSV file with the passed name, by putting each row in a single comma separated line. The number of entries in each line is equal to the length of the second dimension of the [][]float64. The passed [][]float64 is assumed to be non-jagged, such that all rows have the same number of entries. This function returns an error, which contains any errors found during opening and writing to the file or nil if no errors were seen.
Types ¶
This section is empty.
Source Files