matlab.engine.MatlabEngine

Python object using MATLAB as computational engine within Python session

Description

The MatlabEngine class uses a MATLAB^® process as a computational engine for Python^®. You can call MATLAB functions as methods of a MatlabEngine object because the functions are dynamically invoked when you call them. You also can call functions and scripts that you define. You can send data to, and retrieve data from, the MATLAB workspace associated with a MatlabEngine object.

Creation

The matlab.engine.start_matlab method creates a MatlabEngine object each time it is called. There is no need to call matlab.engine.MatlabEngine() to create MatlabEngine objects of your own.

Attributes

Attribute	Description
workspace	Python dictionary containing references to MATLAB variables. You can assign data to, and get data from, a MATLAB variable through the workspace. The name of each MATLAB variable you create becomes a key in the workspace dictionary. The keys in workspace must be valid MATLAB identifiers (for example, you cannot use numbers as keys).

Methods

Public Methods

The matlab::engine::MATLABEngine class provides these methods.

• matlab.engine.start_matlab — Start MATLAB

• matlab.engine.find_matlab — Find shared MATLAB sessions to connect to MATLAB Engine for Python

• matlab.engine.connect_matlab — Connect to shared MATLAB session

Specialized Operators and Functions

You can call any MATLAB function as a method of a MatlabEngine object. The engine dynamically invokes a MATLAB function when you call it. The syntax shows positional, keyword, and output arguments of a function call.

ret = MatlabEngine.matlabfunc(*args,nargout=1,background=False,stdout=sys.stsdout,stderr=sys.stderr)

Replace matlabfunc with the name of any MATLAB function (such as isprime or sqrt). Replace *args with input arguments for the MATLAB function you call. The keyword arguments specify:

• The number of output arguments the function returns

• Whether the engine calls the function asynchronously

• Where the engine sends standard output and standard error coming from the function

Specify keyword arguments only when specifying values that are not the default values shown in the syntax.

Input Arguments to MATLAB Function

Argument	Description	Python Type
*args	Input arguments to MATLAB function, specified as positional arguments	Any Python types that the engine can convert to MATLAB types

Keyword Arguments to Engine

Argument	Description	Python Type
nargout	Number of output arguments from MATLAB function	int Default: 1
background	Flag to call MATLAB function asynchronously background is an alias for async. However, for Python Version 3.7, async is a keyword and cannot be used as an argument. Use the background argument instead of async for all supported versions of Python.	bool Default: False
stdout	Standard output	StringIO.StringIO object (Python 2.7) io.StringIO object (Python 3.x) Default: sys.stdout
stderr	Standard error	StringIO.StringIO object (Python 2.7) io.StringIO object (Python 3.x) Default: sys.stderr

Output Arguments

Output Type	Description	Required Keyword Arguments
Python variable	One output argument from MATLAB function	Default values
tuple	Multiple output arguments from MATLAB function	nargout=n (where n > 1)
None	No output argument from MATLAB function	nargout=0
FutureResult object	A placeholder for output arguments from asynchronous call to MATLAB function	background=True

Exceptions

Exception	Description
MatlabExecutionError	Function call fails to execute
RejectedExecutionError	MATLAB engine terminated
SyntaxError	Syntax error in a function call
TypeError	Data type of an input or output argument not supported

Examples

Call MATLAB Functions from Python

Call the MATLAB sqrt function from Python using the engine.

import matlab.engine
eng = matlab.engine.start_matlab()
ret = eng.sqrt(4.0)
print(ret)

2.0

Put Array Into MATLAB Workspace

Create an array in Python and put it into the MATLAB workspace.

import matlab.engine
eng = matlab.engine.start_matlab()
px = eng.linspace(0.0,6.28,1000)

px is a MATLAB array, but eng.linspace returned it to Python. To use it in MATLAB, put the array into the MATLAB workspace.

eng.workspace['mx'] = px

When you add an entry to the engine workspace dictionary, you create a MATLAB variable, as well. The engine converts the data to a MATLAB data type.

Get Data from MATLAB Workspace

Get pi from the MATLAB workspace and copy it to a Python variable.

import matlab.engine
eng = matlab.engine.start_matlab()
eng.eval('a = pi;',nargout=0)
mpi = eng.workspace['a']
print(mpi)

3.14159265359