Module tensor

Sparse tensor tools.

Tensors are entered as coordinate lists:

{ {x1,y1,z1,val1}, {x2,y2,z2,val2},...}

This module provides functions to convert a coordinate lists to a nested sparse table or to a (non-growable) fast ffi coordinate list.

While not the most (space-)efficient sparse tensor storage method, it's simple, generic (for variable dimensions) and fast enough for contractions with 1D arrays.

Functions

coo_to_sparse_table (coo_list) Convert a coordinate list of arbitrary dimension to a sparse nested table.
new_sparse_table () Create a new sparse table.
sparse_table_to_coo (sparse_table) Convert a sparse tensor encoded as a nested table into a coordinate list.
simplify_coo (coo_list) Merge duplicate entries in a coordinate list.
coo_to_fficoo (coo_list) Convert a coordinate list of arbitrary dimension to an ffi coordinate list.
sparse_mul2 (fficoo_ij, arr_j, res) Sparse multiplication of two tensors, C[i][j] a[j].
sparse_mul3 (fficoo_ijk, arr_j, arr_k, res) Sparse multiplication of three tensors, C[i][j][k] a[j] b[k].
jsparse_mul (fficoo_ijk, arr_j)

Sparse multiplication of two tensors to determine the Jacobian:

J[i][j] = C[i][j][k] a[k] + C[i][k][j] a[k].
sparse_mul4 (fficoo_ijkl, arr_j, arr_k, arr_l, res) Sparse multiplication of four tensors, C[i][j][k][l] a[j] b[k] c[l] Note that it is NOT safe to pass arr_j/k/l as a result buffer, as this operation does multiple passes.
sparse_mul5 (fficoo_ijklm, arr_j, arr_k, arr_l, arr_m, res) Sparse multiplication of five tensors, C[i][j][k][l][m] a[j] b[k] c[l] d[m] Note that it is NOT safe to pass arr_j/k/l/m as a result buffer, as this operation does multiple passes.
append_coo (coo1, coo2) Append a coo_list to another one.


Functions

coo_to_sparse_table (coo_list)
Convert a coordinate list of arbitrary dimension to a sparse nested table. Input format: { {x1,y1,z1,val1}, {x2,y2,z2,val2},...} In the returned table, we have

 t[x1][y1][z1]==val1

e.g.

 mycoolist = {{1, 5, 0.1},{2, 3, 3.14}}

yields

 {[1]={[5]=0.1},[2]={[3]=3.14}}

Missing entries are treated as zero in mathematical operations.

Parameters:

  • coo_list coordinate list (Lua table)

Returns:

    sparse table
new_sparse_table ()
Create a new sparse table. Missing entries are treated as zero in mathematical operations. This sparse table cannot be filled up with st[i][j][k]=val Instead, use the assign method sparse_t:assign(val,indices...)

Returns:

    sparse table
sparse_table_to_coo (sparse_table)
Convert a sparse tensor encoded as a nested table into a coordinate list. Don't include elements with value equal to zero.

Parameters:

  • sparse_table sparse, nested table

Returns:

    coordinate list (Lua table)
simplify_coo (coo_list)
Merge duplicate entries in a coordinate list. This is done by converting it to a sparse table and back.

Parameters:

  • coo_list coordinate list (Lua table)

Returns:

    simplified coordinate list (Lua table)
coo_to_fficoo (coo_list)
Convert a coordinate list of arbitrary dimension to an ffi coordinate list. Input format:

 { {x1,y1,z1,val1}, {x2,y2,z2,val2},...}

e.g.

 mycoolist = {{1, 5, 0.1}, {2, 3, 3.14}, {3, 2, 10}}

yields a struct fficoo which has

 fficoo.dim == 2
 fficoo.nelem == 3
 fficoo.data[0].c[0] == 1
 fficoo.data[0].c[1] == 5
 fficoo.data[0].v == 0.1
 fficoo.data[1].c[0] == 2

etc.

Parameters:

  • coo_list coordinate list (Lua table)

Returns:

    ffi coordinate list (ffi struct)
sparse_mul2 (fficoo_ij, arr_j, res)
Sparse multiplication of two tensors, C[i][j] a[j]. Note that it is NOT safe to pass arr_j as a result buffer, as this operation does multiple passes.

Parameters:

  • fficoo_ij an ffi coordinate list (ffi struct) of which index 2 will be contracted.
  • arr_j the array to be contracted with index 2 of fficooij
  • res array (buffer) to store the result of the contraction

Returns:

    the result array
sparse_mul3 (fficoo_ijk, arr_j, arr_k, res)
Sparse multiplication of three tensors, C[i][j][k] a[j] b[k]. Note that it is NOT safe to pass arr_j/arr_k as a result buffer, as this operation does multiple passes.

Parameters:

  • fficoo_ijk an ffi coordinate list (ffi struct) of which index 2 and 3 will be contracted.
  • arr_j the array to be contracted with index 2 of fficooijk
  • arr_k the array to be contracted with index 3 of fficooijk
  • res array (buffer) to store the result of the contraction

Returns:

    the result array
jsparse_mul (fficoo_ijk, arr_j)
Sparse multiplication of two tensors to determine the Jacobian:

J[i][j] = C[i][j][k] a[k] + C[i][k][j] a[k].

It's implemented slightly differently: for every C[i][j][k], we add to J as follows:

J[i][j] += C[i][j][k] a[k];
J[i][k] += C[i][j][k] a[j]

Return a tensor in the form of a coolist.

Parameters:

  • fficoo_ijk an ffi coordinate list (ffi struct) of which index 2 or 3 will be contracted.
  • arr_j the array to be contracted with index 2 and then index 3 of fficooijk

Returns:

    jcoo_ij a coolist with the result of the contraction
sparse_mul4 (fficoo_ijkl, arr_j, arr_k, arr_l, res)
Sparse multiplication of four tensors, C[i][j][k][l] a[j] b[k] c[l] Note that it is NOT safe to pass arr_j/k/l as a result buffer, as this operation does multiple passes.

Parameters:

  • fficoo_ijkl an ffi coordinate list (ffi struct) of which index 2,3,4 will be contracted.
  • arr_j the array to be contracted with index 2 of fficooijkl
  • arr_k the array to be contracted with index 3 of fficooijkl
  • arr_l the array to be contracted with index 4 of fficooijkl
  • res array (buffer) to store the result of the contraction

Returns:

    the result array
sparse_mul5 (fficoo_ijklm, arr_j, arr_k, arr_l, arr_m, res)
Sparse multiplication of five tensors, C[i][j][k][l][m] a[j] b[k] c[l] d[m] Note that it is NOT safe to pass arr_j/k/l/m as a result buffer, as this operation does multiple passes.

Parameters:

  • fficoo_ijklm an ffi coordinate list (ffi struct) of which index 2,3,4,5 will be contracted.
  • arr_j the array to be contracted with index 2 of fficooijklm
  • arr_k the array to be contracted with index 3 of fficooijklm
  • arr_l the array to be contracted with index 4 of fficooijklm
  • arr_m the array to be contracted with index 5 of fficooijklm
  • res array (buffer) to store the result of the contraction

Returns:

    the result array
append_coo (coo1, coo2)
Append a coo_list to another one.

Parameters:

  • coo1 the target coo_list
  • coo2 the coo_list that will be appended to coo1
generated by LDoc 1.4.3 Last updated 2016-03-11 16:19:27