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