Class Vector

Declare a new class "Vector" into global table inherited from "table" and with initialization constructor

Usage:

-- Pulls itself and all sub-requirements in lua-ctable package with one
-- require()
require("Vector")                                   --> true
type(Vector)                                        --> table
ctables.version()                                   --> 1.0.2-1 d0134dd   5.3

Alternatively put require("Vector") your $LUA_INIT script

NOTE:Using require("Vector") will also automatically ctables=require("lua-ctables").

Even though there are no real dependencies between them, they are often used together. For example, see:

Simplest form

v = Vector(1, 2, 3, 4)          -- 1D vector with values {1, 2, 3, 4}
-- v = Vector({1, 2, 3, 4})     -- Alternative form (same CTOR)
v:sum()
--> 10
print(v)
--> {1, 2, 3, 4}

Linear algebra operations with two 1-dimensional Vector's

p = Vector(11, 12, 4)
v = Vector(2, 3)
print(p + v)                                        --> {13, 15, 4}
print(v + p)                                        --> {13, 15, 4}
print(v - p)                                        --> {-9, -9, -4}
print(p - v)                                        --> {9, 9, 4}

-- Unary operations on Vector v
print(-v)               -- Unary negation
--> {-2, -3}
print(~v)               -- Unary transpose
--> {{2}, {3}}
print(~-v)              -- Unary transpose of unary negation
--> {{-2}, {-3}}

Multi dimensional matrices (3D Vector)

Example matrix build-up

  • Dimensions and leaf content as simple as possible of a {3x3x3} matrix with same values in all leafs.

    v  = Vector(1, 2, 3)            -- A leaf is 1D: {1, 2, 3}
v2 = Vector(v, v, v)            -- 2:d dimension, i.e. a {3x3} matrix
v3 = Vector(v2, v2, v2)         -- 3:rd dimension, i.e. a {3x3x3} matrix
print(v3)
--> {{{1, 2, 3}, {1, 2, 3}, {1, 2, 3}}, {{1, 2, 3}, {1, 2, 3}, {1, 2, 3}}, {{1, 2, 3}, {1, 2, 3}, {1, 2, 3}}}

  • Linear algebra transformation possible during build-up. Size per dimension need not be the uniform. Build-up example of a {2x3x4} matrix:

v  = Vector(1, 2, 3, 4)         -- Root leaf: {1, 2, 3, 4}, i.e. a {4} vector
v2 = Vector(v, v+10, v+20)      -- 2:d dimension, i.e. a {3x4} matrix
v3 = Vector(v2, v2*10)          -- 3:rd dimension, i.e. a {2x3x4} matrix

print(v)
--> {1, 2, 3, 4}
print(v2)
--> {{1, 2, 3, 4}, {11, 12, 13, 14}, {21, 22, 23, 24}}
print(v3)
--> {{{1, 2, 3, 4}, {11, 12, 13, 14}, {21, 22, 23, 24}}, {{10, 20, 30, 40}, {110, 120, 130, 140}, {210, 220, 230, 240}}}

Scalar Vector algebra

v = Vector(1, 2, 3)
print(v - 1)                                        --> {0, 1, 2}
print(1 - v)                                        --> {0, 1, 2}
v2 = Vector(v, v, v)
print(v2 - 3)
--> {{-2, -1, 0}, {-2, -1, 0}, {-2, -1, 0}}
print(3 - v2)
--> {{-2, -1, 0}, {-2, -1, 0}, {-2, -1, 0}

Instance and "casting" from Lua tables

Create Vector objects from Lua tables

Multi dimensional:

q = Vector.cast({{{3, 4, 5}, {4, 5, 6}}, {{4, 5, 6}, {5, 6, 7}}})
q:dim()
--> {3, 2, 2}
print(q)
--> {{{3, 4, 5}, {4, 5, 6}}, {{4, 5, 6}, {5, 6, 7}}}

Recursive cast only as needed:

one = Vector.cast(1)
print(one)
--> {1}
one = Vector.cast({1})  -- It's already a table
print(one)
--> {1}

"CTOR" uses Vector.cast() internally:

w_3x2x2 = Vector({{{3, 4, 5}, {4, 5, 6}}, {{4, 5, 6}, {5, 6, 7}}})
print(w_3x2x2)
--> {{{3, 4, 5}, {4, 5, 6}}, {{4, 5, 6}, {5, 6, 7}}}

See also:

Tables

vector.Vector Meta-table with constructor (class)
vector.mt Meta-table with linear algebra operators

The class-name Vector is used interchangeably with Matrix below as a matrix is just a vector of vectors.

Methods

vector:vmap (B, fn) Growable maps iterator

Iterate over the larger of RHS and LHS (self) and append result of fn to each element to a resulting vector.
vector:map (fn) Self maps iterator
vector:reduce (fn, init) Iterate over self table

This is mainly used internally for operations where the result is one dimensional and no temporary Vector needs to be kept in memory.
vector:cast (t) Cast to Vector
vector:sum () Sum of all elements
vector:max () Maximum of all elements
vector:min () Minimum of all elements
vector:vdim (V, t) Dimension(s) - static class method
vector:dim () Self dimension(s)
vector:transpose (V) Perform a transpose operation on Vector
vector:vmul (A, B) vmul

Vector multiplication between two Vector objects producing a Vector-matrix.


Tables

vector.Vector
Meta-table with constructor (class) Inherit from "table" and define __call for member "mt" which is applied to either referenced to table or constructed table, effectively making either use-case returning a Vector object

Fields:

  • __index inheritance (table)
  • __call Used as CTOR
vector.mt
Meta-table with linear algebra operators

The class-name Vector is used interchangeably with Matrix below as a matrix is just a vector of vectors. Convention for examples below are scalars in in italics and vectors in bold.

Fields:

  • __add + operator. Performs addition between Vectors or Vector and scalar. Result is another Vector of the same number of dimensions end dimensional size as the largest of the operands.

    c = a + b == b + a

    c = a + b == b + a

  • __sub - operator. Performs subtraction between Vectors or Vector and scalar. Result is another Vector of the same number of dimensions end dimensional size as the largest of the operands.

    c = a - b ≠ b - a

    c = a - b == b - a

  • __unm Unary - operator. All elements negated

    a + (-a) = 0

  • __mul * operator. Performs multiplication between Vectors or Vector and scalar. For multiplication between Vectors, they have to oblige to certain rules or result is undefined. Matrix multiplication is NOT commutative.

    c = a * b == b * a

    d = (a * b) * c ≠ a * (b * c)

  • __div / operator. Performs scalar division with Vectors

    c = a / b ≠ b - a

  • __bnot Unary ~ used as transpose operator. Shift rows and columns. Transposition in 1D or 2D (row->column shift). If transposing a vector or dimensions >2, it's still only row->column of the first 2 dimensions that's swapped.

    a == (aᵀ)ᵀ

Methods

vector:vmap (B, fn)

Growable maps iterator

Iterate over the larger of RHS and LHS (self) and append result of fn to each element to a resulting vector.

  • Value zero is used when either side runs out or elements
  • Order or Vector elements is swapped if size of "self" is smaller than RHS

Parameters:

  • B Vector Right-hand-side of a vector operation
  • fn func Operation to be performed on each Vectors element

Returns:

    Vector Resulting vector
vector:map (fn)
Self maps iterator Iterate over elements in "self" and apply function "fn" to each element in corresponding result Vector

Parameters:

  • fn func Operation to be performed on each Vectors element

Returns:

    Vector Resulting vector
vector:reduce (fn, init)
Iterate over self table

This is mainly used internally for operations where the result is one dimensional and no temporary Vector needs to be kept in memory. I.e. it's a memory constraint iterative method.

Parameters:

  • fn func Operation to be performed on each Vectors element
  • init element Initial element

Returns:

    value result

See also:

vector:cast (t)
Cast to Vector Explicit "cast" of argument to a Vector object

Parameters:

  • t table to be cast into Vector

Returns:

    Vector resulting vector

See also:

vector:sum ()
Sum of all elements

Returns:

    value result

See also:

vector:max ()
Maximum of all elements

Returns:

    value result

See also:

vector:min ()
Minimum of all elements

Returns:

    value result

See also:

vector:vdim (V, t)
Dimension(s) - static class method Determine given Vectors dimensions

Parameters:

  • V Vector Vector to inspect dimensions for
  • t table Table (reference) to store each dimensions size in
vector:dim ()
Self dimension(s) Objects dimensions

Returns:

    Vector One dimensional with each dimensions size in corresponding element

Usage:

    v = Vector(1, 2, 3)
v2 = Vector(v, -v)
v3 = Vector(v2, 2*v2, v2-3, v2)
v4 = Vector(-v3, 4+v3)
v4:dim()
--> {3, 2, 4, 2}        -- 4D: 3x2x4x2
v3:dim()
--> {3, 2, 4}           -- 3D: 3x2x3
v2:dim()
--> {3, 2}              -- 2D: 3x2
v:dim()
--> {3}                 -- 1D: 3
vector:transpose (V)
Perform a transpose operation on Vector Call method explicitly or via with the ~ unary operator serving the purpose as there's no ' for operations in the Lua grammar.

Parameters:

  • V Vector Vector to transpose

Returns:

    Vector Transposed vector (Vᵀ)

Usage:

    v = Vector(1, 2, 3)
vT = ~v
print(v, vT)
--> {1, 2, 3}       {{1}, {2}, {3}}
print(v:dim(), vT:dim())
--> {3}     {1, 3}
vector:vmul (A, B)

vmul

Vector multiplication between two Vector objects producing a Vector-matrix. This is a class static method used internally by the * operator when both LHS/RHS are Vector's. I.e. used by the class-overloaded * operator determining if operation is scalar or a vmul (i.e. this) operation.

For explicit calls, the following rules apply (normal linear-algebra math rules + implementation specific)

  • Arguments must both be Object::Vector
  • Columns of LHS (A) must be equal Rows or RHS (B)
  • The result matrix has the number of rows of the first and the number of columns of the second matrix. This rule is asserted.
  • Higher order dimensions than 2-D are allowed but all Vectors are considered as matrices, i.e. all operations are performed with the same rules as for matrices, i.e. operating over a plane or rows and columns over the first 2 dimensions. This is mathematically dubious but keeps the code simpler.
  • 1-D Vector are considered matrices too. The second dimension is the length of the Vector.
  • For 1-D multiplications, only LHS can be 1-D

Parameters:

Returns:

    Vector Vector-matrix multiplied result

Usage:

    v = Vector(1, 2, 3)
m1 = Vector(v, v+2, v+3)
m2 = Vector(v+1, v+2)
print(m2 * m1)
--> {{27, 36, 45}, {35, 47, 59}}
generated by LDoc 1.5.0 Last updated 2024-09-16 20:16:45