forward

R2026b

Compute PyTorchModel output by invoking Python model on input

Since R2026b

Syntax

[Y1,...,YN] = forward(model,X1,...,XM)

[___] = forward(___,pyarg1=val1,...,pyargK=valK)

[___] = forward(___,ReturnAsPython=[tf1,...,tfN])

Description

[Y1,...,YN] = forward(model,X1,...,XM) passes X1,...,XM to Python^®, converting any numeric MATLAB^® arrays to torch.Tensor objects, and invokes the PyTorch^® model on the Python inputs.

forward invokes the model using Python function call syntax, which typically calls the forward() method of the model. This approach is recommended for performing inference or training with PyTorch models. The behavior depends on the TrainingMode property of the model: set it to "eval" for inference or "train" for training.

[___] = forward(___,pyarg1=val1,...,pyargK=valK) also passes Python keyword arguments to the model invocation command.

[___] = forward(___,ReturnAsPython=[tf1,...,tfN]) specifies which outputs to return as Python types (py.* objects) rather than converting them to MATLAB arrays. If you specify ReturnAsPython, it must appear last in the argument list.

Examples

Predict with Single-Input, Single-Output Model

Load a PyTorch model with input shape (B,2) and output shape (B,5), specifying dimension permutations for MATLAB-style CB format.

Load the model with data-transfer settings for CB format.

model = pyTorchModel("fooBarModel.pt",InputDimensionOrder=[2 1],...
                     InputDataType="float32",OutputDimensionOrder=[2 1]);

Create input data.

X = rand(2,17);

Compute the model output.

Y = forward(model,X);
size(Y)

ans = 1x2
     5    17

Predict with Multi-Input, Multi-Output Model

Load a PyTorch model with three inputs and two outputs, specifying different dimension orderings for each input.

Load the model with data-transfer settings for multiple inputs.

model = pyTorchModel("mimo32_Full.pt", NumInputs=3, ...
    InputDataType=["float32","float32","float32"],...
    InputDimensionOrder={[3 4 1 2],[2 3 1],[]});

Create input data.

X1 = rand([3 4 1 2]);
X2 = rand([6 1 5]);
X3 = rand([1 7 8]);

Compute the model outputs.

[Y1,Y2] = forward(model,X1,X2,X3);

Predict with Python Keyword Arguments

Pass Python keyword arguments to the model invocation.

Load a model and call forward with a Python keyword argument.

model = pyTorchModel("mimo32_full.pt",NumInputs=3, ...
    InputDimensionOrder={[3 4 1 2],[2 3 1],[]});
X1 = rand([3 4 1 2]);
X2 = rand([6 1 5]);
X3 = rand([1 7 8]);
[Y1,Y2] = forward(model,X1,X2,X3,prediction_length=24);

Predict with Preprocessed Python Inputs

Convert a MATLAB array to a torch.Tensor, apply Python preprocessing, and pass it as a py.* object to bypass automatic conversion.

Load a multi-input model.

model = pyTorchModel("mimo32_Full.pt",NumInputs=3, ...
    InputDataType=["float32","float32","float32"],...
    InputDimensionOrder={[3 4 1 2],[2 3 1],[]});

Convert the first input to a torch.Tensor and apply Python preprocessing. Then pass it as a py.* object. forward does not apply the stored data-transfer settings for the first input because it is not a numeric MATLAB array.

X1 = rand([3 4 1 2]);
X2 = rand([6 1 5]);
X3 = rand([1 7 8]);
pX1 = arrayToTorchTensor(X1,DimensionOrder=[3 4 1 2],Datatype="float");
pX1 = py.MyModule.preprocess(pX1);
[Y1,Y2] = forward(model,pX1,X2,X3);

Return Some Outputs as Python Objects

Use ReturnAsPython to keep selected outputs as py.* objects instead of converting them to MATLAB arrays.

Load a model and call forward, returning the first output as a Python object.

model = pyTorchModel("mimo32_full.pt",NumInputs=3, ...
    InputDataType=["float32","float32","float32"],...
    InputDimensionOrder={[3 4 1 2],[2 3 1],[]});
X1 = rand([3 4 1 2]);
X2 = rand([6 1 5]);
X3 = rand([1 7 8]);
[pY1,Y2] = forward(model,X1,X2,X3,ReturnAsPython=[true,false]);
class(pY1)

ans =
    'py.torch.Tensor'

forward converts the second output to a MATLAB array as normal.

class(Y2)

ans =
    'single'

Validate Imported Model Against PyTorch Source

Compare predictions of a PyTorch model to a dlnetwork imported from the same model.

Load SqueezeNet from torch.hub using a constructor command.

ptSqueezenet = pyTorchModel(ConstructorCommand=...
    "torch.hub.load('pytorch/vision:v0.10.0','squeezenet1_0',pretrained=True)",...
    InputDimensionOrder=[4 3 1 2],InputDataType="float32");

Export the model to a traced format and import as a dlnetwork.

X = rand([224 224 3 1]);
export(ptSqueezenet,"traced","Squeezenet_traced.pt",X);
dlnet = importNetworkFromPyTorch("Squeezenet_traced.pt");
inputLayer = imageInputLayer([224 224 3],Normalization="none");
dlnet = addInputLayer(dlnet,inputLayer,Initialize=true);

Compare predictions of the PyTorch model and the imported dlnetwork.

ptOut = forward(ptSqueezenet,X);
mOut = predict(dlnet,X);
max(abs(ptOut(:)-mOut(:)))

ans = single
    2.3842e-06

Input Arguments

model — Reference to a PyTorch model

PyTorchModel object

Reference to a PyTorch model, specified as a PyTorchModel object.

X1,...,XM — Input data

numeric arrays | logical arrays | dlarray objects | gpuArray objects | py.* objects | table | struct | ...

Input data, each specified as one of these values:

• Numeric array, logical, dlarray, or gpuArray (Parallel Computing Toolbox) — forward automatically converts these to a torch.Tensor using the data-transfer settings stored in the model.

• py.* object — forward passes these to Python without any conversion.

• Other MATLAB data types compatible with the MATLAB Python interface, for example a table or struct — forward converts these to Python using the default rules of the MATLAB–Python interface. For more information, see Pass Data Between MATLAB and Python from MATLAB.

To prevent forward from converting a MATLAB numeric array to a torch.Tensor, convert it to the required Python type and pass it as a py.* object. For example, to pass a scalar as an integer instead of a torch.Tensor, pass py.int(x).

pyarg1=val1,...,pyargK=valK — Python keyword arguments

parameter_name=value pairs

Python keyword arguments, specified as parameter_name=value pairs. forward converts all values to Python using the default rules of the MATLAB Python interface and passes the pairs to the Python model invocation.

tf1,...,tfN — Outputs to return as Python types

vector of false (default) | logical vector

Outputs to return as Python types (py.* objects) rather than converting them to MATLAB arrays, specified as a logical vector. The length of this vector must match the number of outputs. The MATLAB Python interface still applies its default rules to outputs where ReturnAsPython is true, but in most cases the result is a py.* object.

Example: ReturnAsPython=[true false]

Data Types: logical

Output Arguments

Y1,...,YN — Output data

numeric arrays | logical arrays | gpuArray objects | py.* objects

Output data of the model, returned as MATLAB arrays, logical arrays, gpuArray objects, or py.* objects. Using GPU with PyTorchModel requires Parallel Computing Toolbox™.

forward converts outputs that are torch.Tensor objects to MATLAB arrays using the data-transfer settings stored in the model. forward returns outputs for which ReturnAsPython is true as Python types (py.* objects). forward converts all other outputs to MATLAB using the default rules of the MATLAB Python interface.

Tips

• forward supports a fixed number of mandatory positional arguments followed by optional keyword arguments. The number of mandatory positional arguments is set by the NumInputs property of the model at construction time. At call time, you must pass exactly NumInputs positional arguments, followed by any number of keyword arguments.

• If the underlying Python forward() method accepts optional or variadic positional arguments, write a separate standalone Python function for each number of positional inputs you need, then use addFunction and callFunction to call them individually. For example, define forward_2() that accepts two inputs, add it with addFunction(model,"myModule.forward_2",NumInputs=2), and call it with callFunction(model,"myModule.forward_2",X1,X2).

• Mandatory Python keyword arguments are handled by the optional keyword argument mechanism. If you omit a required keyword argument, Python issues an error at runtime.

• Python uses zero-based indexing (the first item in a tensor is at index 0), while MATLAB uses one-based indexing (the first item in an array is at index 1). Ensure that you use zero-based indexing when passing index integers to your model.

Algorithms

CPU and GPU Behavior

Device Selection and Input Movement

If any input is a gpuArray or a py.torch.Tensor whose device attribute is "cuda*", forward selects the GPU of the first such input as the execution device. Otherwise, forward uses the CPU. Using GPU with PyTorchModel requires Parallel Computing Toolbox.

forward copies all MATLAB numeric array inputs and py.torch.Tensor inputs in X1,...,XM to the selected device if they are not already there.

Model Movement

For models with ModelType equal to "torch.nn.Module", "ExportedProgram", or "TracedOrScripted", forward moves the model parameters to the selected device if they are not already there.

For models with ModelType equal to "Custom", forward leaves the model device unchanged. You can modify properties of the Python model object through the PythonObject property.

Version History

Introduced in R2026b