callFunction

R2026b

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

Since R2026b

collapse all in page

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.

example

[___] = 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

collapse all

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);

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);

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

collapse all

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

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

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).

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.

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

collapse all

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

collapse all

Version History

Introduced in R2026b

See Also

Functions

Objects

Topics