callFunction

R2026b

Call method of underlying Python PyTorch model instance or function taking model as its first argument

Since R2026b

Syntax

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

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

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

Description

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

[___] = callFunction(___,pyarg1=val1,...,pyargK=valK) also passes Python keyword arguments to the function call.

[___] = callFunction(___,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 after all Python keyword arguments.

Examples

Configure and Call Model Method with Tensor Input

Configure the predict method of a PyTorch^® model to convert a numeric MATLAB array to a torch.Tensor, then call it.

Load a PyTorch sequence model from a local file.

model = pyTorchModel("mySequenceModel.pt");

Configure predict to convert a CBT MATLAB input to a BCT torch.Tensor.

addFunction(model,"predict",InputDimensionOrder=[2 1 3]);

Call the method, passing a MATLAB array in CBT dimension ordering.

mInput = randn(4,32,100);  % CBT: 4 channels, 32 batches, 100 time steps
output = callFunction(model,"predict",mInput,num_steps=24);

Call Standalone Function on Model

Configure and call a standalone Python function that takes the model as its first argument.

Load a PyTorch model from a local file.

model = pyTorchModel("mySequenceModel.pt");

Configure the PyTorchModel to call the standalone function myPostProcess.extractFeatures.

addFunction(model,"myPostProcess.extractFeatures",InputDimensionOrder=[2 1 3]);

Call the function, passing a MATLAB array in CBT dimension ordering.

mInput = randn(4,32,100);  % CBT: 4 channels, 32 batches, 100 time steps
features = callFunction(model,"myPostProcess.extractFeatures",mInput, ...
    window_size=16,normalize=true);

Call Model Method on Table Input

Load a PyTorch model and call its predict_from_table method, passing a MATLAB table that is automatically converted to a pandas.DataFrame.

Load a PyTorch model by running a Python script, then wrap the model.

net = pyrunfile("build_model.py","net");
model = pyTorchModel(net);

Read a table of input data to pass to the model.

inputTbl = readtable("sensorReadings.csv");

Call the predict_from_table method, passing the MATLAB table. The Python interface automatically converts it to a pandas.DataFrame.

predictions = callFunction(model,"predict_from_table",inputTbl, ...
    num_steps=24,confidence_level=0.95);

Since you are using the default data-transformation settings, you do not need to call addFunction before callFunction. You can call callFunction on any method of the underlying model without declaring it first, if you are not specifying any data-transformation arguments.

Input Arguments

model — Reference to a PyTorch model

PyTorchModel object

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

functionName — Name of Python method or function to call

string | character vector

Name of the PyTorch object method or standalone function to call, specified as a string or character vector. This argument can be the name of a method of the PyTorch model or a fully-qualified Python function name that takes the model as its first argument.

Example: "predict"

Example: "myPostProcess.extractFeatures"

Data Types: string | char

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 array, dlarray, or gpuArray (Parallel Computing Toolbox) — automatically converted to a torch.Tensor using the data-transfer settings stored in the model. Using GPU with PyTorchModel requires Parallel Computing Toolbox™.

• py.* object — passed to Python as-is.

• Other MATLAB data types compatible with the MATLAB Python interface, for example a table or struct — converted 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 callFunction 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

name-value pairs | 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 | py.* objects | gpuArray objects

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

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

Tips

• callFunction supports a fixed number of mandatory positional arguments followed by optional keyword arguments. The number of mandatory positional arguments is set by the NumInputs argument of addFunction (default 1). At call time, you must pass exactly NumInputs positional arguments after functionName, followed by any number of keyword arguments.

• If the underlying Python function 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 my_func_2(model,x1,x2) that takes two inputs, add it with addFunction(model,"myModule.my_func_2",NumInputs=2), and call it with callFunction(model,"myModule.my_func_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.

• If you get an "index out of range" error when calling the model, check whether any of the input tensors represent indices. PyTorch uses 0-based indexing, so you must subtract 1 from MATLAB 1-based indices before passing them to the 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*", callFunction selects the GPU of the first such input as the execution device. Otherwise, callFunction uses the CPU. Using GPU with PyTorchModel requires Parallel Computing Toolbox.

callFunction 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", callFunction moves the model parameters to the selected device if they are not already there.

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

Version History

Introduced in R2026b