matlab.engine.MatlabEngine

Pythonobject usingMATLABas computational engine withinPythonsession

expand all in page

Description

TheMatlabEngineclass uses a MATLAB^®process as a computational engine for Python^®. You can call MATLAB functions as methods of aMatlabEngineobject 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 aMatlabEngineobject.

Creation

Thematlab.engine.start_matlabmethod creates aMatlabEngineobject each time it is called. There is no need to callmatlab.engine.MatlabEngine()to createMatlabEngineobjects 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

Thematlab::engine::MATLABEngineclass 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 aMatlabEngineobject. 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)

Replacematlabfuncwith the name of any MATLAB function (such asisprimeorsqrt). Replace*argswith 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 toMATLABFunction

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, as of Python Version 3.7,`async`一个关键字,不能吗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

expand all

CallMATLABFunctions fromPython

Call the MATLABsqrtfunction from Python using the engine.

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

2.0

Put Array IntoMATLABWorkspace

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)

pxis a MATLAB array, buteng.linspacereturned 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 engineworkspacedictionary, you create a MATLAB variable, as well. The engine converts the data to a MATLAB data type.

Get Data fromMATLABWorkspace

Getpifrom 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

Version History

Introduced in R2014b