Class `Array`

Implementation of ND Arrays in Lua.

A generic implementation of ND arrays in pure Lua. This module tries to be as similar to the Python numpy package as possible.

Due to everything being in Lua there are not views of arrays which means that many functions creates unnecessary data-duplications. This may be leveraged in later code implementations.

The underlying Array class is implemented as follows:

Every Array gets associated a Shape which determines the size of the current Array.
If the Array is > 1D all elements Array[i] is an array with sub-Arrays of one less dimension.
This enables one to call any Array function on sub-partitions of the Array without having to think about the details.
The special case is the last dimension which contains the actual data.

The Array class is using the same names as the Python numerical library numpy for clarity.

Initialization routines

Array:new (...)	Initialization routine for the Array object.
Array:empty (...)	Initialize an Array, equivalent to `Array(...)`.
Array:zeros (...)	Initialize an Array filled with 0's, equivalent to `a = Array(...); a:fill(0.)`
Array:ones (...)	Initialize an Array filled with 1's, equivalent to `a = Array(...); a:fill(1.)`
Array:copy ()	Create a deep copy of the array by copying all elements.
Array:range (i1, i2[, step=1])	Initialize a 1D Array with a linear spacing of values starting from `i1`, ending with `i2` and with step size `step` which defaults to 1.

Object information

Array:__len ()	Query the length of the first dimension of the Array
Array:size ([axis=0])	Query the size of the Array, @see Shape:size.
Array:get_linear (i)	Get an Array element through a linear index of the ND array
Array:set_linear (i, v)	Set an Array element through a linear index of the ND array

Manipulation routines

Array:fill (val)	Fill all values in the Array with a given value.
Array:reshape (...)	Return a deep copy of the Array with a different shape
Array:flatten ()	Return a deep copy of the Array in a 1D array (equivalent to `:reshape(0)`)
Array:map (func)	Return the Array as a copy with every element mapped through the given function The function should accept a single value, and return a single value (not a table).
Array:abs ()	Elementwise absolute operation
Array:ceil ()	Elementwise ceiling operation
Array:floor ()	Elementwise floor operation
Array:tointeger ()	Elementwise conversion to integer
Array:exp ()	Elementwise exponential operation
Array:cos ()	Elementwise cosine operation
Array:sin ()	Elementwise sine operation
Array:log ([base=e])	Elementwise logarithm operation
Array:tan ()	Elementwise tangent operation
Array:sqrt ()	Elementwise square root operation
Array:cbrt ()	Elementwise cube-root operation
Array:prod ([axis=0])	Return the product of array elements over a given axis
Array:norm ([axis=#self.shape])	Return a the norm of the Array.
Array:scalar_project (P[, axis=0])	Return the scalar projection of this array onto another.
Array:project (P[, axis=0])	Return the projection of this array onto another.
Array:min ([axis=0])	Return the minimum value of the Array
Array:max ([axis=0])	Return the maximum value of the Array
Array:sum ([axis=0])	Return the sum of elements of the Array
Array:average ([axis=0])	Return the average of elements of the Array
Array:cross (lhs, rhs)	Return the sum of cross-product of two arrays (only for 1D arrays with `#Array == 3`)
Array:flatdot (lhs, rhs)	Wrapper for doing a linear dot-product between any two ND arrays, the only requirement is that they have the same total size.
Array:dot (lhs, rhs)	Dot-product of two Arrays.
Array:transpose ()	Return the transpose of the Array (all dimensions are swapped).
Array:__add (lhs, rhs)	Elementwise addition of two arrays.
Array:__sub (lhs, rhs)	Elementwise subtraction of two arrays (see Array:__add)
Array:__mul (lhs, rhs)	Elementwise multiplication of two arrays (see Array:__add)
Array:__mod (lhs, rhs)	Elementwise modulo (%) of two arrays (see Array:__add)
Array:__div (lhs, rhs)	Elementwise division of two arrays (see Array:__add)
Array:__idiv (lhs, rhs)	Elementwise floor division of two arrays (see Array:__add)
Array:__unm ()	Elementwise unary negation
Array:__pow (lhs, rhs)	Elementwise power of two arrays (see Array:__add)
Array:__tostring ()	Return the values of the array in a tabular format as a string.
Array:savetxt (handle[, format="%20.13e"[, footer="\n"]])	Write the values to an already open file-handle The format is defined via the `format` parameter and the content gets an empty line at the end of the array pri
Array:from (tbl)	Given a regular Lua table this function returns a new Array with elements filled from the table.

Initialization routines

Several routines exists to initialize the Array with values.

Usage:

Array:empty(2, 3) -- it is the users responsibility to assign values
Array(2, 3) -- same as :empty
Array:ones(2, 3) -- filled with 1's all over
Array:zeros(2, 3) -- filled with 0's all over
Array:range(2, 3) -- array with values [2, 3]
Array:ones(2, 3):copy() -- create a copy of another Array

Array:new (...)

Initialization routine for the Array object. Create a new empty Array. Remark that no entries are defined.

Parameters:

... a comma-separated list of integers, or a Shape

Returns:

a new Array object with the given shape

Usage:

Array(2, 3) -- an array with the last element being [2][3]
Array(2, 3, 4) -- an array with the last element being [2][3][4]
Array( Shape(3, 2) ) -- an array with the last element being [3][2]

Array:empty (...)

Initialize an Array, equivalent to Array(...). proceeding with other calculations

Parameters:

... the shape of the Array

Returns:

an Array with no values set, it is the users responsibility to assign values before

Array:zeros (...)

Initialize an Array filled with 0's, equivalent to a = Array(...); a:fill(0.)

Parameters:

... the shape of the Array

Returns:

an Array with all values set to 0.

Array:ones (...)

Initialize an Array filled with 1's, equivalent to a = Array(...); a:fill(1.)

Parameters:

... the shape of the Array

Returns:

an Array with all values set to 1.

Array:copy ()

Create a deep copy of the array by copying all elements.

Returns:

a copy of the Array

Array:range (i1, i2[, step=1])

Initialize a 1D Array with a linear spacing of values starting from i1, ending with i2 and with step size step which defaults to 1.

Parameters:

i1 the initial value of the range
i2 the last value of the range (if (i2-i1+1)/step is a float the last element is not necessarily in the array)
step the stepsize between consecutive values. (default 1)

Returns:

an Array with equally separated values.

Object information

Routines to retrieve information regarding the Array object I.e. the shape, total size, etc.

Usage:

#Array -- length of first dimension
#Array.shape -- number of dimensions
Array.size([dim]) -- size of dimension, total size if dim=0

Array:__len ()

Query the length of the first dimension of the Array

Returns:

self.shape[1]

Array:size ([axis=0])

Query the size of the Array, @see Shape:size.

Parameters:

axis int optional argument to query specific axes, if not supplied the total size of the array will be returned. (default 0)

Returns:

the length of the specified axis (or total size).

Array:get_linear (i)

Get an Array element through a linear index of the ND array

Parameters:

i int linear index in the (possible) ND array

Array:set_linear (i, v)

Set an Array element through a linear index of the ND array

Parameters:

i int linear index in the (possible) ND array
v the value to be set at index i

Manipulation routines

All these routines can change the content and do operations of Array objects.

Array:fill (val)

Fill all values in the Array with a given value.

Parameters:

val the value of all elements of this Array

Array:reshape (...)

Return a deep copy of the Array with a different shape sizes may be a 0 (or nil) which indicates that the length of said dimension will be inferred from the total size of the Array

Parameters:

... the new shape of the array, any of the provided dimension

Returns:

an Array with the same total size and values, but with different shape

Usage:

a = Array:zeros(4, 4)
b = a:reshape(0) -- Array:zeros(16)
c = a:reshape(2, 0) -- Array:zeros(2, 8)
d = a:reshape(0, 2) -- Array:zeros(8, 2)

Array:flatten ()

Return a deep copy of the Array in a 1D array (equivalent to :reshape(0))

Returns:

a 1D-Array with the same total size and values, but with a single dimension

Array:map (func)

Return the Array as a copy with every element mapped through the given function The function should accept a single value, and return a single value (not a table).

Parameters:

func the cast function

Returns:

func

Array:abs ()

axis int optional argument to query specific axes, if not supplied the total product of the array will be returned. (default 0)

Returns:

the product of the specified axis (or total product)

Array:norm ([axis=#self.shape])

Return a the norm of the Array.

Parameters:

axis int the axis along which the norm is taken, defaults to the last dimension, currently any axis between 0 and the last dimension is not implemented. (default #self.shape)

Returns:

axis=0

Usage:

a = Array( 2, 3)
a:fill(1.)
print(a:norm(2)) -- [3 ^ 0.5, 3 ^ 0.5]
print(a:norm(0)) -- 6 ^ 0.5

Array:scalar_project (P[, axis=0])

Return the scalar projection of this array onto another. Example:

a = Array( 2, 3)
print(a:scalar_project( Array.ones( 2, 3) )

The scalar projection is this formula:

$\frac{a \cdot b}{|b|}$

Parameters:

P Array the projection array
axis int the axis along the projection, currently only a full projection is available (default 0)

Returns:

axis=0

Array:project (P[, axis=0])

Return the projection of this array onto another. Example:

a = Array( 2, 3)
print(a:project( Array.ones( 2, 3) )

The scalar projection is this formula:

$\frac{a \cdot b}{|b|^2} b$

Parameters:

P Array the projection array
axis int the axis along the projection, currently only a full projection is available (default 0)

Returns:

axis=0

Array:min ([axis=0])

Return the minimum value of the Array

Parameters:

axis int either 0 or an axis. If 0 (or nil) the global minimum is returned, else along the given dimension (default 0)

Returns:

axis=0

removed

Array:max ([axis=0])

Return the maximum value of the Array

Parameters:

axis int either 0 or an axis. If 0 (or nil) the global maximum is returned, else along the given dimension (default 0)

Returns:

axis=0

removed

Array:sum ([axis=0])

Return the sum of elements of the Array

Parameters:

axis int either 0 or an axis. If 0 (or nil) the global sum is returned, else along the given dimension (default 0)

Returns:

axis=0

removed

Array:average ([axis=0])

Return the average of elements of the Array

Parameters:

axis int either 0 or an axis. If 0 (or nil) the global average is returned, else along the given dimension (default 0)

Returns:

axis=0

removed

Array:cross (lhs, rhs)

Return the sum of cross-product of two arrays (only for 1D arrays with #Array == 3)

Parameters:

lhs Array the left-hand side of the operand
rhs Array the second operand of the cross-product

Returns:

an Array with the cross-product of the two vectors

Array:flatdot (lhs, rhs)

Wrapper for doing a linear dot-product between any two ND arrays, the only requirement is that they have the same total size.

Parameters:

lhs Array the first operand of the dot-product
rhs Array the second operand of the dot-product

Returns:

the value of the dot-product

Array:dot (lhs, rhs)

Dot-product of two Arrays. For 1D arrays this returns a single value, for ND arrays the shapes must fulfil self.shape[#self.shape] == other.shape[1], as well as all dimensions self.shape[1:#self.shape-2] == other.shape[3:].reverse(). Note that for 2D Arrays this is equivalent to matrix-multiplication.

Parameters:

lhs Array the first operand of the dot-product.
rhs Array the second operand of the dot-product.

Returns:

a single value if both Arrays are 1D, else a new Array is returned.

Array:transpose ()

-self

Array:__pow (lhs, rhs)

Elementwise power of two arrays (see Array:__add)

Parameters:

lhs the first operand
rhs the second operand, this may be "T" to indicate a transpose, @see Array:transpose

Returns:

lhs ^ rhs

rhs == "T"

Array:__tostring ()

Return the values of the array in a tabular format as a string. Currently the values are presented in a %12.5e format.

Returns:

a string representation of the Array

Array:savetxt (handle[, format="%20.13e"[, footer="\n"]])

Write the values to an already open file-handle The format is defined via the format parameter and the content gets an empty line at the end of the array pri

Parameters:

handle the file-handle to write to
format the output format of the values (default "%20.13e")
footer a string to write after the array values has been written (default "\n")

Array:from (tbl)

Given a regular Lua table this function returns a new Array with elements filled from the table.

Parameters:

tbl table the input table.

Returns:

tbl

flos

Contents

Classes

Modules

Manual

Examples

Class Array

Initialization routines

Object information

Manipulation routines

Initialization routines

Usage:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Returns:

Parameters:

Returns:

Object information

Usage:

Returns:

Parameters:

Returns:

Parameters:

Parameters:

Manipulation routines

Parameters:

Parameters:

Returns:

Usage:

Returns:

Parameters:

Returns:

Returns:

See also:

Returns:

See also:

Returns:

See also:

Returns:

See also:

Returns:

See also:

Returns:

See also:

Returns:

See also:

Parameters:

Returns:

See also:

Returns:

See also:

Returns:

See also:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Class `Array`