addFunction

R2026b

Configure data transfer settings for Python method or function of PyTorchModel

Since R2026b

collapse all in page

    Syntax

    addFunction(model,functionName,Name=Value)

    Description

    addFunction(model,functionName,Name=Value) adds or replaces the data-transfer configuration for the specified Python® method or function in the PyTorchModel object. The name-value arguments describe how callFunction converts MATLAB® numeric arrays to torch.Tensor objects, and vice versa, when calling functionName using callFunction.

    Given a PyTorchModel object, you can call any method of the underlying PyTorch® model, or function taking the model as first argument, using callFunction without declaring that method or function. Use addFunction to change the data-transfer settings, or to declare multiple inputs.

    addFunction stores function configurations in the PyTorchFunctions property of the PyTorchModel object.

    example

    Examples

    collapse all

    Configure the predict method of a PyTorch model to convert a numeric MATLAB array to a torch.Tensor with the required dimension ordering.

    Load a PyTorch sequence model from a local file.

    model = pyTorchModel("mySequenceModel.pt");

    Configure the predict method 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 the PyTorchModel to 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);

    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

    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: addFunction(model,"predict",InputDimensionOrder=[2 1 3],InputNumDimensions=3)

    Number of required positional arguments to the PyTorch method, not including the model object itself, specified as a positive integer. callFunction uses this value to separate positional arguments from keyword arguments when calling the method.

    Example: NumInputs=2

    Data Types: double

    Permutation to apply to each MATLAB numeric input array to make its dimension ordering match what is required by the PyTorch method, specified as a numeric row vector or a cell array of numeric row vectors. For methods with multiple inputs, specify a cell array with one element per input.

    When empty, the MATLAB–Python interface determines the dimension order.

    Example: InputDimensionOrder=[2 1 3]

    Data Types: double | cell

    Final number of dimensions each torch.Tensor must have, specified as a positive integer or a cell array of positive integers. callFunction removes or adds trailing singleton dimensions after the permutation to achieve this number. Use this argument when the PyTorch method requires true 0-D or 1-D tensors.

    When empty, the MATLAB Python interface determines the number of dimensions.

    Example: InputNumDimensions=3

    Data Types: double | cell

    Python data type each input torch.Tensor must have, specified as a string array.

    When empty, the MATLAB Python interface determines the data type.

    Example: InputDataType="float32"

    Data Types: string

    Field names for keyword argument inputs, specified as a string array. Set this argument when the PyTorch method takes only keyword arguments as input and you pass a MATLAB struct. The name-value arguments InputDimensionOrder, InputNumDimensions, and InputDataType apply to these field names in the order given.

    Example: InputKeyNames=["input_ids","attention_mask"]

    Data Types: string

    Permutation to apply to each returned torch.Tensor to make its dimension ordering match what you want in MATLAB, specified as a numeric row vector or a cell array of numeric row vectors. For methods with multiple outputs, specify a cell array with one element per output.

    When empty, the MATLAB–Python interface determines the dimension order.

    Example: OutputDimensionOrder=[3 1 2]

    Data Types: double | cell

    MATLAB data type each output array must have, specified as a string array.

    When empty, the numeric function of the MATLAB Python interface determines the data type.

    Example: OutputDataType="single"

    Data Types: string

    Key names for dictionary output fields, specified as a string array. When the PyTorch method returns a single dictionary, these names specify which fields callFunction applies data-transfer settings to. The OutputDimensionOrder argument applies to these key names in the order given.

    Example: OutputKeyNames=["logits","hidden_states"]

    Data Types: string

    Tips

    • The NumInputs argument declares a fixed number of mandatory positional arguments for the function. At call time, callFunction requires exactly NumInputs positional arguments, followed by any number of optional 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 add each one individually with addFunction. For example, if you sometimes pass two inputs and sometimes three, define my_func_2(model,x1,x2) and my_func_3(model,x1,x2,x3), and add them with addFunction(model,"myModule.my_func_2",NumInputs=2) and addFunction(model,"myModule.my_func_3",NumInputs=3).

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

    Version History

    Introduced in R2026b

    See Also

    Functions

    Objects

    Topics