We are hiring ! See our job offers.

base.py

```
"""
Core tensor operations.
"""
import numpy as np
# Author: Jean Kossaifi
# License: BSD 3 clause
def tensor_from_frontal_slices(*matrices):
"""Creates a third order tensor from a list of matrices (frontal slices)
Parameters
----------
matrices : ndarray list
list of frontal slices, each a matrix of shape ``(I, J)``
Returns
-------
ndarray
tensor of shape ``(I, J, len(matrices))``
"""
return np.concatenate([i[..., None] for i in matrices], axis=-1)
def tensor_to_vec(tensor):
"""Vectorises a tensor
Parameters
----------
tensor : ndarray
tensor of shape ``(i_1, ..., i_n)``
Returns
-------
1D-array
vectorised tensor of shape ``(i_1 * i_2 * ... * i_n)``
See also
--------
vec_to_tensor
fold
unfold
"""
return np.ravel(tensor)
def vec_to_tensor(vec, shape):
"""Folds a vectorised tensor back into a tensor of shape `shape`
Parameters
----------
vec : 1D-array
vectorised tensor of shape ``(i_1 * i_2 * ... * i_n)``
shape : tuple
shape of the ful tensor
Returns
-------
ndarray
tensor of shape `shape` = ``(i_1, ..., i_n)``
See also
--------
tensor_to_vec
fold
unfold
"""
return np.reshape(vec, shape)
def unfold(tensor, mode=0):
"""Returns the mode-`mode` unfolding of `tensor` with modes starting at `0`.
Parameters
----------
tensor : ndarray
mode : int, default is 0
indexing starts at 0, therefore mode is in ``range(0, tensor.ndim)``
Returns
-------
ndarray
unfolded_tensor of shape ``(tensor.shape[mode], -1)``
See also
--------
fold
tensor_to_vec
"""
return np.moveaxis(tensor, mode, 0).reshape((tensor.shape[mode], -1))
def fold(unfolded_tensor, mode, shape):
"""Refolds the mode-`mode` unfolding into a tensor of shape `shape`
In other words, refolds the n-mode unfolded tensor
into the original tensor of the specified shape.
Parameters
----------
unfolded_tensor : ndarray
unfolded tensor of shape ``(shape[mode], -1)``
mode : int
the mode of the unfolding
shape : tuple
shape of the original tensor before unfolding
Returns
-------
ndarray
folded_tensor of shape `shape`
See also
--------
unfold
tensor_to_vec
"""
full_shape = list(shape)
mode_dim = full_shape.pop(mode)
full_shape.insert(0, mode_dim)
return np.moveaxis(unfolded_tensor.reshape(full_shape), 0, mode)
def partial_unfold(tensor, mode=0, skip_begin=1, skip_end=0, ravel_tensors=False):
"""Partially unfolds a tensor while ignoring the specified number of dimensions at the beginning and the end.
For instance, if the first dimension of the tensor is the number of samples, to unfold each sample, you would
set skip_begin=1.
This would, for each i in ``range(tensor.shape[0])``, unfold ``tensor[i, ...]``.
Parameters
----------
tensor : ndarray
tensor of shape n_samples x n_1 x n_2 x ... x n_i
mode : int
indexing starts at 0, therefore mode is in range(0, tensor.ndim)
skip_begin : int, optional
number of dimensions to leave untouched at the beginning
skip_end : int, optional
number of dimensions to leave untouched at the end
ravel_tensors : bool, optional
if True, the unfolded tensors are also flattened
Returns
-------
ndarray
partially unfolded tensor
See also
--------
partial_fold
"""
if ravel_tensors:
new_shape = [-1]
else:
new_shape = [tensor.shape[mode + skip_begin], -1]
if skip_begin:
new_shape = [tensor.shape[i] for i in range(skip_begin)] + new_shape
if skip_end:
new_shape += [tensor.shape[-i] for i in range(skip_end)]
return np.moveaxis(tensor, mode+skip_begin, skip_begin).reshape(new_shape)
def partial_fold(unfolded, mode, shape, skip_begin=1, skip_end=0):
"""Re-folds a partially unfolded tensor
Parameters
----------
unfolded : ndarray
a partially unfolded tensor
mode : int
indexing starts at 0, therefore mode is in range(0, tensor.ndim)
shape : tuple
the shape of the original full tensor (including skipped dimensions)
skip_begin : int, optional, default is 1
number of dimensions to leave untouched at the beginning
skip_end : int, optional
number of dimensions to leave untouched at the end
Returns
-------
ndarray
partially re-folded tensor
See also
--------
partial_unfold
"""
transposed_shape = list(shape)
mode_dim = transposed_shape.pop(skip_begin+mode)
transposed_shape.insert(skip_begin, mode_dim)
return np.moveaxis(unfolded.reshape(transposed_shape), skip_begin, skip_begin+mode)
def partial_tensor_to_vec(tensor, skip_begin=1, skip_end=0):
"""Partially vectorises a tensor
In other words, vectorises the subtensors of `tensor` obtained by
ignoring the specified dimension at the beginning and the end
Parameters
----------
tensor : ndarray
tensor to partially vectorise
skip_begin : int, optional, default is 1
number of dimensions to leave untouched at the beginning
skip_end : int, optional
number of dimensions to leave untouched at the end
Returns
-------
ndarray
partially vectorised tensor with the `skip_begin` first and `skip_end` last dimensions untouched
See also
--------
partial_vec_to_tensor : invert the partial_tensor_to_vec operation
"""
return partial_unfold(tensor, mode=0, skip_begin=skip_begin, skip_end=skip_end, ravel_tensors=True)
def partial_vec_to_tensor(matrix, shape, skip_begin=1, skip_end=0):
"""Refolds a partially vectorised tensor into a full one
Parameters
----------
matrix : ndarray
a partially vectorised tensor
shape : tuple
the shape of the original full tensor (including skipped dimensions)
skip_begin : int, optional, default is 1
number of dimensions to leave untouched at the beginning
skip_end : int, optional
number of dimensions to leave untouched at the end
Returns
-------
ndarray
full tensor
See also
--------
partial_tensor_to_vec : invert the partial_vec_to_tensor operation
"""
return partial_fold(matrix, mode=0, shape=shape, skip_begin=skip_begin, skip_end=skip_end)
```