arrayToTorchTensor

R2026b

Convert MATLAB numeric array to PyTorch Tensor

Since R2026b

collapse all in page

Syntax

torchTensor = arrayToTorchTensor(matlabArray)
torchTensor = arrayToTorchTensor(matlabArray,Name=Value)

Description

torchTensor = arrayToTorchTensor(matlabArray) converts a MATLAB® numeric array to a PyTorch® Tensor.

example

torchTensor = arrayToTorchTensor(matlabArray,Name=Value) uses additional arguments to specify permutation, number of dimensions, and torch datatype.

example

Examples

collapse all

Convert MATLAB arrays to PyTorch tensors without specifying additional arguments. The tensor shape follows the MATLAB–Python® interface conventions.

Convert a 3-D array. For arrays with more than two dimensions, the tensor shape matches the MATLAB size.

A = rand(2,3,4);
T = arrayToTorchTensor(A);
T.shape
ans = 
  Python Size with no properties.
    torch.Size([2, 3, 4])

Convert a column vector. Column vectors remain 2-D tensors.

A = rand(3,1);
T = arrayToTorchTensor(A);
T.shape
ans = 
  Python Size with no properties.
    torch.Size([3, 1])

Convert a row vector. Row vectors become 1-D tensors.

A = rand(1,5);
T = arrayToTorchTensor(A);
T.shape
ans = 
  Python Size with no properties.
    torch.Size([5])

Convert a scalar. Scalars become 0-D tensors (empty shape).

A = 42;
T = arrayToTorchTensor(A);
T.shape
ans = 
  Python Size with no properties.
    torch.Size([])

Use the DimensionOrder argument to reorder dimensions during conversion. The number of output dimensions defaults to the length of the DimensionOrder vector.

Permute a 3-D array. The output shape reflects the reordered dimensions.

A = rand(2,3,4);
T = arrayToTorchTensor(A,DimensionOrder=[2 3 1]);
T.shape
ans = 
  Python Size with no properties.
    torch.Size([3, 4, 2])

Index a trailing singleton dimension to increase dimensionality. Here, the permutation references dimension 4 (a trailing singleton in the 3-D input), producing a 4-D tensor.

A = rand(2,3,4);
T = arrayToTorchTensor(A,DimensionOrder=[4 2 3 1]);
T.shape
ans = 
  Python Size with no properties.
    torch.Size([1, 3, 4, 2])

arrayToTorchTensor retains trailing singleton dimensions that appear within the length of the permutation vector.

A = rand(2,1,4);
T = arrayToTorchTensor(A,DimensionOrder=[3 1 2]);
T.shape
ans = 
  Python Size with no properties.
    torch.Size([4, 2, 1])

Prevent a scalar from collapsing to 0-D by specifying a 2-element permutation. The identity permutation [1 2] preserves shape while enforcing 2-D output.

A = rand(1,1);
T = arrayToTorchTensor(A,DimensionOrder=[1 2]);
T.shape
ans = 
  Python Size with no properties.
    torch.Size([1, 1])

Preserve a row vector as 2-D instead of collapsing to 1-D.

A = rand(1,5);
T = arrayToTorchTensor(A,DimensionOrder=[1 2]);
T.shape
ans = 
  Python Size with no properties.
    torch.Size([1, 5])

Use the NumDimensions argument to control the number of dimensions of the output tensor. Trailing singleton dimensions are added or removed to achieve the specified number. When combined with DimensionOrder, the permutation is applied first.

Expand a 2-D array to 4-D by adding trailing singleton dimensions.

A = rand(2,3);
T = arrayToTorchTensor(A,NumDimensions=4);
T.shape
ans = 
  Python Size with no properties.
    torch.Size([2, 3, 1, 1])

Reduce a 3-D array to 1-D by permuting and then removing trailing singleton dimensions.

A = rand(1,1,2);
T = arrayToTorchTensor(A,DimensionOrder=[3 2 1],NumDimensions=1);
T.shape
ans = 
  Python Size with no properties.
    torch.Size([2])

Prevent a scalar from collapsing to 0-D by specifying 2 output dimensions.

A = rand(1,1);
T = arrayToTorchTensor(A,NumDimensions=2);
T.shape
ans = 
  Python Size with no properties.
    torch.Size([1, 1])

Remove trailing singleton dimensions after a permutation.

A = rand(2,1,4);
T = arrayToTorchTensor(A,DimensionOrder=[3 1 2],NumDimensions=2);
T.shape
ans = 
  Python Size with no properties.
    torch.Size([4, 2])

Use the DataType argument to specify the PyTorch data type of the output tensor, including types such as bfloat16 that have no MATLAB equivalent.

By default, the tensor data type follows the MATLAB-Python interface conventions.

A = rand(2,3,4);
T = arrayToTorchTensor(A);
T.dtype
ans =
 
  Python dtype with properties:
           is_complex: 0
    is_floating_point: 1
            is_signed: 1
             itemsize: [1×1 py.int]
 
    torch.float64
A = single(rand(2,3,4));
T = arrayToTorchTensor(A);
T.dtype
ans =
 
  Python dtype with properties:
           is_complex: 0
    is_floating_point: 1
            is_signed: 1
             itemsize: [1×1 py.int]

    torch.float32

Override the default by specifying a PyTorch data type directly. This is useful for types like bfloat16 that have no MATLAB equivalent.

A = rand(2,3,4);
T = arrayToTorchTensor(A,DataType="bfloat16");
T.dtype
ans =
 
  Python dtype with properties:
           is_complex: 0
    is_floating_point: 1
            is_signed: 1
             itemsize: [1×1 py.int]

    torch.bfloat16

Input Arguments

collapse all

MATLAB array, specified as a numeric array, logical array, dlarray, or gpuArray object. Using GPU requires Parallel Computing Toolbox™.

Name-Value Arguments

collapse all

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: T = arrayToTorchTensor(A,DimensionOrder=[4 3 1 2])

Permutation vector to define ordering of dimensions in torch.Tensor. specified as a numeric row vector. The permutation applies to MATLAB array with dimensions 1,2,3,... to make its dimension ordering match what is required by the PyTorch Tensor.

Example: DimensionOrder=[4 3 1 2]

Final number of dimensions a torch.Tensor must have, specified as a nonnegative integer. Trailing singleton dimensions are removed or added after the permutation to achieve this number.

Example: NumDimensions=4

PyTorch data type for resulting tensor, specified as a string representing a valid PyTorch dtype.

Example: DataType="float32"

Example: DataType="bfloat16"

Example: DataType="int8"

Output Arguments

collapse all

PyTorch Tensor, returned as a MATLAB object of class py.torch.Tensor.

Algorithms

arrayToTorchTensor determines the number of dimensions of the resulting torch.Tensor using the following precedence (highest to lowest):

  1. Explicit NumDimensions. If NumDimensions is specified, it is used directly.

  2. DimensionOrder: If DimensionOrder is specified, NumDimensions is set to the length of DimensionOrder.

  3. dlarray input. If matlabArray is a dlarray, the number of dimensions is set to ndims(matlabArray).

  4. MATLAB–Python interface rules. If none of the above apply, dimensions are set to size[a b …]→shape[a b …], except for these two cases:

    • size[1 k] → shape[k] for k>1. In this case, the result is 1-D torch.Tensor.

    • size[1 1]→ shape[]. This is the empty shape, which corresponds to scalar torch.Tensor.

    For more information, see Pass Data Between MATLAB and Python from MATLAB.

Extended Capabilities

expand all

Version History

Introduced in R2026b

See Also

Functions

Objects

Topics