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:

  1. Every Array gets associated a Shape which determines the size of the current Array.
  2. If the Array is > 1D all elements Array[i] is an array with sub-Arrays of one less dimension.
  3. This enables one to call any Array function on sub-partitions of the Array without having to think about the details.
  4. 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:

    the length of the first dimension, 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:

    an Array with every element mapped through the function func
Array:abs ()
Elementwise absolute operation

Returns:

    math.abs(Array)

See also:

Array:ceil ()
Elementwise ceiling operation

Returns:

    math.ceil(Array)

See also:

Array:floor ()
Elementwise floor operation

Returns:

    math.floor(Array)

See also:

Array:tointeger ()
Elementwise conversion to integer

Returns:

    all values as integers (math.tointeger(Array))

See also:

Array:exp ()
Elementwise exponential operation

Returns:

    math.exp(Array)

See also:

Array:cos ()
Elementwise cosine operation

Returns:

    math.cos(Array)

See also:

Array:sin ()
Elementwise sine operation

Returns:

    math.sin(Array)

See also:

Array:log ([base=e])
Elementwise logarithm operation

Parameters:

  • base the base of the logarithm (default e)

Returns:

    math.log(Array, base)

See also:

Array:tan ()
Elementwise tangent operation

Returns:

    math.tan(Array)

See also:

Array:sqrt ()
Elementwise square root operation

Returns:

    math.sqrt(Array)

See also:

Array:cbrt ()
Elementwise cube-root operation

Returns:

    Array ^ (1./3)
Array:prod ([axis=0])
Return the product of array elements over a given axis

Parameters:

  • 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:

    a value if the axis=0 or the Array is 1D, else a new Array with 1 less dimension is returned.

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:

    a value if the axis=0 or the Array is 1D, else a new Array with 1 less dimension is returned.
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:

    a value if the axis=0 or the Array is 1D, else a new Array with 1 less dimension is returned.
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:

    a value if the axis=0 or an Array with one less dimension (the axis dimension is 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:

    a value if the axis=0 or an Array with one less dimension (the axis dimension is 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:

    a value if the axis=0 or an Array with one less dimension (the axis dimension is 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:

    a value if the axis=0 or an Array with one less dimension (the axis dimension is 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 ()
Return the transpose of the Array (all dimensions are swapped).

Returns:

    a copy of the Array with all dimensions reversed.
Array:__add (lhs, rhs)
Elementwise addition of two arrays. It is required that both operands have the same shape (or one of them being a scalar).

Parameters:

  • lhs the first operand (Array or number)
  • rhs the second operand (Array or number)

Returns:

    an Array with lhs + rhs
Array:__sub (lhs, rhs)
Elementwise subtraction of two arrays (see Array:__add)

Parameters:

  • lhs the first operand
  • rhs the second operand

Returns:

    an Array with lhs - rhs
Array:__mul (lhs, rhs)
Elementwise multiplication of two arrays (see Array:__add)

Parameters:

  • lhs the first operand
  • rhs the second operand

Returns:

    an Array with lhs * rhs
Array:__mod (lhs, rhs)
Elementwise modulo (%) of two arrays (see Array:__add)

Parameters:

  • lhs the first operand
  • rhs the second operand

Returns:

    an Array with lhs % rhs
Array:__div (lhs, rhs)
Elementwise division of two arrays (see Array:__add)

Parameters:

  • lhs the first operand
  • rhs the second operand

Returns:

    an Array with lhs / rhs
Array:__idiv (lhs, rhs)
Elementwise floor division of two arrays (see Array:__add)

Parameters:

  • lhs the first operand
  • rhs the second operand

Returns:

    an Array with lhs // rhs
Array:__unm ()
Elementwise unary negation

Returns:

    an Array with -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:

    an Array with lhs ^ rhs, or the transpose if 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:

    an Array with elements corresponding to the values in tbl
generated by LDoc 1.4.6 Last updated 2019-05-23 08:36:38