pyTorchModel

R2026b

Reference to a PyTorch model for Python execution

Since R2026b

Description

A PyTorchModel object is a wrapper for a PyTorch^® model that facilitates execution in Python^® using the MATLAB^® Python interface.

PyTorchModel is a handle object that holds a reference to a PyTorch model instance in Python and settings specifying how MATLAB input data must be converted to torch.Tensor objects for input to the methods of the model. Use this object to load a PyTorch model, invoke it on inputs, call its other Python object methods, and save it in a different format.

Creation

Syntax

model = pyTorchModel(modelfile)

model = pyTorchModel(pythonObject)

model = pyTorchModel(modelfile,ConstructorCommand=command)

model = pyTorchModel(ConstructorCommand=command)

model = pyTorchModel(___,Property=Value)

Description

model = pyTorchModel(modelfile) loads a PyTorch model from the file modelfile and returns a PyTorchModel object.

model = pyTorchModel(pythonObject) wraps a MATLAB object with the py. prefix representing a PyTorch model in a PyTorchModel object.

model = pyTorchModel(modelfile,ConstructorCommand=command) instantiates a PyTorch model using the constructor command in Python, loads the weights from the file modelfile, and wraps the result in a PyTorchModel object. For this syntax, modelfile must be a weight file (saved with torch.save(model.state_dict(),modelfile)).

model = pyTorchModel(ConstructorCommand=command) instantiates a PyTorch model by executing the specified constructor command in Python and wraps the result in a PyTorchModel object.

model = pyTorchModel(___,Property=Value) loads or wraps a PyTorch model and sets Properties using one or more name-value arguments.

Input Arguments

modelfile — Name of PyTorch model file

string | character vector

Name of a PyTorch model file, specified as a string or a character vector. The file can contain a full model (architecture and weights saved with torch.save(model,modelfile)), a weight file (saved with torch.save(model.state_dict(),modelfile)), a traced or scripted model (saved with torch.jit.save), or an exported program (saved with torch.export.save).

Data Types: char | string

pythonObject — Object representing PyTorch model

MATLAB object with py. prefix

Object representing a PyTorch model, specified as a MATLAB object with the py. prefix.

command — Python command returning a PyTorch model instance

string | character vector | cell array

Python command, specified as:

• A string to be executed in Python that returns a PyTorch model instance

• A cell array containing a command string followed by arguments that are evaluated in MATLAB and can include Python objects

Example: ConstructorCommand="myModule.myObj(12,arg2=13)" or ConstructorCommand={"myModule.myObj",12,pyargs(arg2=12+1)}

Data Types: char | string | cell

Properties

Model Properties

PythonObject — Reference to PyTorch model instance in Python

MATLAB object with py. prefix

Reference to the loaded PyTorch model instance in Python, specified as a MATLAB object with the py. prefix.

ModelType — Type of PyTorch model

Read-only: "torch.nn.Module" | "ExportedProgram" | "TracedOrScripted" | "Custom"

This property is read-only.

Type of PyTorch model, returned as "torch.nn.Module", "ExportedProgram", "TracedOrScripted", or "Custom".

Data Types: string

TrainingMode — Training mode of model and modules

"eval" (default) | "train" | "mixed"

Training mode of the PyTorch model and its modules, specified as "train", "eval", or "mixed". To set this property, specify one of these values for the TrainingMode name-value argument:

• "eval" — Set the model and all its modules to evaluation mode.

• "train" — Set the model and all its modules to training mode.

• "as-is" — Do not change the training mode of the original model. pyTorchModel checks each module of the original model and set the resulting property to "train", "eval", or "mixed" (if some modules are in the training mode and some are in the evaluation mode).

For example, you can specify TrainingMode="train". Setting this property recursively sets all modules in the model to the specified training mode.

You can use strings or character vectors when specifying the TrainingMode name-value argument. The property value is stored as string.

Data Types: string

Model Loading Properties

FileName — Name of file from which model was loaded

Read-only: string

This property is read-only.

Name of the file from which the model was loaded, returned as a string.

Data Types: string

ModulePath — Path to Python module defining model class

[] (default) | string | character vector

Path to the directory containing the Python module that defines the PyTorch model class, specified as a string or a character vector. Use the ModulePath name-value argument to set this property when the module is not on the Python path. For example, you can specify ModulePath="/home/user/models".

You can use strings or character vectors when specifying the ModulePath name-value argument. The property value is stored as string.

Data Types: string

ModuleName — Name of Python module defining model class

string | character vector

Name of the Python module defining the model class, specified as a string or a character vector. Use the ModuleName name-value argument to set this property when you provide a new module name for models originally defined in the Python __main__ module. For example, you can specify ModuleName="myModelModule".

You can use strings or character vectors when specifying the ModuleName name-value argument. The property value is stored as string.

Data Types: string

Data Transfer Properties

PyTorchFunctions — Data-transfer settings for Python functions

Read-only: struct

This property is read-only.

Data-transfer settings for each Python function that has been added for this model, returned as a struct. Settings for each added function are in a nested structure.

Data Types: struct

NumInputs — Number of positional inputs to forward

1 (default) | positive integer

Number of required positional arguments to the forward method of the PyTorch model, specified as a positive integer. For example, you can specify NumInputs=3.

Data Types: double

InputDimensionOrder — Permutation for converting MATLAB inputs to torch.Tensor

{[]} (default) | numeric row vector | cell array of numeric row vectors

Permutation to apply to each MATLAB numeric input array to make its dimension ordering match what is required by the PyTorch model, specified as a numeric row vector or a cell array of numeric row vectors. For models with multiple inputs, specify a cell array with one element per input. For example, you can specify InputDimensionOrder=[4 3 1 2].

If you specify a numeric row vector, the property value is stored as a cell array containing one numeric vector.

Data Types: cell

InputNumDimensions — Number of dimensions for each input torch.Tensor

{[]} (default) | positive integer | cell array of positive integers

Final number of dimensions each torch.Tensor must have, specified as a positive integer or a cell array of positive integers. For example, you can specify InputNumDimensions=4. Trailing singleton dimensions are removed or added after the permutation to achieve this number. Use this argument when the PyTorch model requires true 0-D or 1-D tensors.

If you specify a positive integer, the property value is stored as a cell array containing one positive integer.

Data Types: cell

InputDataType — Python data type for input tensors

"" (default) | string array

Python data type each input torch.Tensor must have, specified as a string array. MATLAB arrays are converted to these data types. For example, you can specify InputDataType="float32". When empty, the MATLAB–Python interface determines the data type passed to the PyTorch model.

Data Types: string

InputKeyNames — Field names for keyword argument inputs

"" (default) | string array

Field names for keyword argument inputs, specified as a string array. For example, you can specify InputKeyNames=["input_ids","attention_mask"]. Set this property when the PyTorch model takes only keyword arguments as input. When you specify InputKeyNames, the data-transfer properties InputDimensionOrder, InputNumDimensions, and InputDataType apply to these field names in the order given.

Data Types: string

OutputDimensionOrder — Permutation for converting torch.Tensor outputs to MATLAB arrays

{[]} (default) | numeric row vector | cell array of numeric row vectors

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 models with multiple outputs, specify a cell array with one element per output. For example, you can specify OutputDimensionOrder=[3 4 1 2].

If you specify a numeric row vector, the property value is stored as a cell array containing one numeric row vector.

Data Types: cell

OutputDataType — MATLAB data type for output arrays

"" (default) | string array

MATLAB data type each output array must have, specified as a string array. For example, you can specify OutputDataType=["single","double"]. When empty, the numeric function of the MATLAB Python interface determines the data type.

Data Types: string

OutputKeyNames — Key names for dictionary output fields

"" (default) | string array

Key names for dictionary output fields, specified as a string array. For example, you can specify OutputKeyNames=["logits","hidden_states"]. When the PyTorch model returns a single dictionary, these names specify which fields have data-transfer settings applied. The OutputDimensionOrder argument applies to these key names in the order given.

Data Types: string

Object Functions

forward	Compute PyTorchModel output by invoking Python model on input
addFunction	Configure data transfer settings for Python method or function of PyTorchModel
callFunction	Call method of underlying Python PyTorch model instance or function taking model as its first argument
export	Save underlying PyTorch model in different PyTorch file format
reload	Reload PyTorch model from stored model loading properties

Examples

Load PyTorch Model from a Full Model File

Load a PyTorch model from a full model file that contains both the network architecture and the weights.

Load a PyTorch model from a file created by calling torch.save(model,modelfile) in Python.

modelfile = "model1OnPath.pt";
model = pyTorchModel(modelfile)

model =
  PyTorchModel with properties:

         PythonObject: [1x1 py.myModel.MyModelClass1]
            ModelType: "torch.nn.Module"
             FileName: "model1OnPath.pt"
           ModulePath: ""
           ModuleName: ""
    PyTorchFunctions: [1x1 struct]
            NumInputs: 1
  InputDimensionOrder: {[]}
   InputNumDimensions: {[]}
        InputDataType: ""
       InputKeyNames: [1x0 string]
 OutputDimensionOrder: {[]}
       OutputDataType: ""
      OutputKeyNames: [1x0 string]

Load PyTorch Model From Weight File and Constructor Command

Load a PyTorch model by providing a weight file and a constructor command that instantiates the model.

Specify the path to a weight file created by calling torch.save(model.state_dict(),modelfile) in Python. Provide a constructor command string that includes the module name, class name, and any arguments required to create the model. Use pyTorchModel to instantiate the model and load the weights.

modelfile = "model1OnPathWeights.pth";
constructorCommand = "myModels1.MyModelClass1(2,3,5)";
model = pyTorchModel(modelfile,ConstructorCommand=constructorCommand)

model = 
  PyTorchModel with properties:
         PythonObject: [1×1 py.myModels1.MyModelClass1]
            ModelType: "torch.nn.Module"
             FileName: "model1OnPathWeights.pth"
           ModulePath: ""
           ModuleName: ""
        PyTorchFunctions: [1×1 struct]
            NumInputs: 1
     InputDimensionOrder: {[]}
         InputNumDimensions: {[]}
        InputDataType: ""
           InputKeyNames: [1×0 string]
    OutputDimensionOrder: {[]}
       OutputDataType: ""
          OutputKeyNames: [1×0 string]

Load PyTorch Model Using Python Command and Wrap It

Load a PyTorch model using a Python command and wrap the resulting Python object in a PyTorchModel.

Load a PyTorch model directly in Python using torch.load and verify its class.

pythonObject = py.torch.load("model1OnPath.pt",weights_only=false);
class(pythonObject)

ans =
    'py.myModels1.MyModelClass1'

Wrap the Python object in a PyTorchModel object.

 model = pyTorchModel(pythonObject)

model = 
  PyTorchModel with properties:
         PythonObject: [1×1 py.myModels1.MyModelClass1]
            ModelType: "torch.nn.Module"
             FileName: ""
           ModulePath: ""
           ModuleName: ""
        PyTorchFunctions: [1×1 struct]
            NumInputs: 1
     InputDimensionOrder: {[]}
         InputNumDimensions: {[]}
        InputDataType: ""
           InputKeyNames: [1×0 string]
    OutputDimensionOrder: {[]}
           OutputDataType: ""
          OutputKeyNames: [1×0 string]

Configure Data Transfer for Multiple Inputs

Configure the forward method to transform multiple inputs with different dimension orderings.

Load a PyTorch model with 3 inputs, specifying different input dimension orders for each input.

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

model =
  PyTorchModel with properties:

         PythonObject: [1x1 py.mimo32.MIMO32]
            ModelType: "torch.nn.Module"
             FileName: "mimo32_Full.pt"
           ModulePath: ""
           ModuleName: ""
    PyTorchFunctions: [1x1 struct]
            NumInputs: 3
  InputDimensionOrder: {[3 4 1 2] [2 3 1] []}
   InputNumDimensions: {[4] [] [3]}
        InputDataType: ["float32" "float32" "float32"]
       InputKeyNames: [1x0 string]
 OutputDimensionOrder: {[]}
       OutputDataType: ""
      OutputKeyNames: [1x0 string]

Validate Imported Model Against PyTorch Source

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

Load a PyTorch image classification model from a local file.

ptModel = pyTorchModel("myImageClassifier.pt", ...
    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(ptModel,"traced","myImageClassifier_traced.pt",X);
dlnet = importNetworkFromPyTorch("myImageClassifier_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(ptModel,X);
mOut = predict(dlnet,X);
max(abs(ptOut(:)-mOut(:)))

ans = single
    2.3842e-06

Tips

• All numeric inputs passed to the forward method are automatically converted to torch.Tensor objects using the data-transfer settings stored in the PyTorchModel object.

• Use the addFunction method to configure data-transfer settings for model methods other than forward.

• When the model takes only keyword arguments, pass a MATLAB struct to forward. The struct is automatically converted to a Python dictionary, with numeric arrays converted to torch.Tensor objects for the fields specified in InputKeyNames.

• 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