Raw File
"""
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)
back to top