mygrad.atleast_3d#

mygrad.atleast_3d(tensors: ArrayLike, *, constant: bool | None = None) → Tensor[source]#
mygrad.atleast_3d(*tensors: ArrayLike, constant: bool | None = None) → List[Tensor]

Convert inputs to tensors with at least one dimension.

Scalar inputs are converted to 3-dimensional tensors, whilst higher-dimensional inputs are preserved.

This docstring was adapted from numpy.atleast_3d.

Parameters:
tens1, tens2, …ArrayLike

One or more input tensors.

Returns:
retTensor | List[Tensor]

A tensor, or list of tensors, each with a.ndim >= 3. Copies are made only if necessary. For example, a 1-D tensor of shape (N,) becomes a view of shape (1, N, 1), and a 2-D tensor of shape (M, N) becomes a view of shape (M, N, 1).

See also

atleast_1d, atleast_3d

Examples

>>> import mygrad as mg
>>> mg.atleast_3d(3.0)
Tensor([[[3.]]])

>>> x = mg.arange(3.0)
>>> mg.atleast_3d(x).shape
(1, 3, 1)
>>> mg.atleast_3d(x).base is x
True

>>> x = mg.arange(12.0).reshape(4,3)
>>> mg.atleast_3d(x).shape
(4, 3, 1)

>>> mg.atleast_3d(1, [[1, 2]], [[[[1, 2]]]])
[Tensor([[[1]]]), Tensor([[[1, 2]]]), Tensor([[[[1, 2]]]])]

numpy.atleast_3d will dispatch appropriately on tensors.

>>> x = mg.tensor(2.)
>>> np.atleast_3d(x)
Tensor([[[2.]]])

>>> np.atleast_3d(x).backward()
>>> x.grad
array(1.)

If any argument to numpy.atleast_3d is a Tensor, mygrad.atleast_3d will be dispatched on all of the arguments.

>>> np.atleast_3d(x, 1.)
[Tensor([[[2.]]]), Tensor([[[1.]]])]