python调用matlab API 汇总（全）
目录
启动用于 Python 的 MATLAB 引擎
运行多个引擎
停止引擎
使用启动选项启动引擎
异步启动引擎
通过 Python 调用 MATLAB 函数
从 MATLAB 函数返回输出参数
从 MATLAB 函数返回多个输出参数
不从 MATLAB 函数返回任何输出参数
停止执行函数
Get Help for MATLAB Functions from Python
How to Find MATLAB Help
Open MATLAB Help Browser from Python
Note
Display MATLAB Help at Python Prompt
将 Python 连接到正在运行的 MATLAB 会话
连接到共享 MATLAB 会话
异步连接到共享 MATLAB 会话
连接到多个共享 MATLAB 会话
使用启动选项启动共享 MATLAB 会话
在 Python 中使用 MATLAB 引擎工作区
在 Python 中使用 MATLAB 数组
通过 Python 调用 MATLAB 函数
从 MATLAB 函数返回输出参数
从 MATLAB 函数返回多个输出参数
不从 MATLAB 函数返回任何输出参数
停止执行函数
MATLAB 数组作为 Python 变量
在 Python 中创建 MATLAB 数组
Python 中的 MATLAB 数组属性和方法
Python 中的多维 MATLAB 数组
在 Python 中对 MATLAB 数组进行索引
在 Python 中对 MATLAB 数组进行切片
注意
在 Python 中重构 MATLAB 数组
从 Python 将数据传递到 MATLAB
Python 类型到 MATLAB 标量类型的映射
Python 容器到 MATLAB 数组类型的映射
不支持的 Python 类型
Use MATLAB Handle Objects in Python
Default Numeric Types in MATLAB and Python
Redirect Standard Output and Error to Python
Call MATLAB Functions Asynchronously from Python
Sort and Plot MATLAB Data from Python
See Also
启动用于 Python 的 MATLAB 引擎
-
在操作系统提示符下启动 Python®。
-
将
matlab.engine包导入您的 Python 会话中。 -
通过调用
start_matlab启动新的 MATLAB® 进程。start_matlab函数返回 Python 对象eng，您可以通过该对象传递数据和调用由 MATLAB 执行的函数。
import matlab.engine
eng = matlab.engine.start_matlab()
运行多个引擎
分别启动每个引擎。每个引擎启动自己的 MATLAB 进程并与之通信。
eng1 = matlab.engine.start_matlab()
eng2 = matlab.engine.start_matlab()
停止引擎
调用 exit 或 quit 函数。
eng.quit()
如果在引擎仍在运行的情况下退出 Python，Python 会自动停止引擎及其 MATLAB 进程。
使用启动选项启动引擎
启动引擎，并将选项作为输入参数字符串传递给 matlab.engine.start_matlab。例如，随桌面启动 MATLAB。
eng = matlab.engine.start_matlab("-desktop")
您可以使用单个字符串定义多个启动选项。例如，启动桌面并将数值显示格式设置为 short。
eng = matlab.engine.start_matlab("-desktop -r 'format short'")
您也可以在启动引擎后启动桌面。
import matlab.engine
eng = matlab.engine.start_matlab()
eng.desktop(nargout=0)
异步启动引擎
以异步方式启动引擎。在 MATLAB 启动时，您可以在 Python 命令行中输入命令。
import matlab.engine
future = matlab.engine.start_matlab(async=True)
future = matlab.engine.start_matlab(background=True)
创建 MATLAB 实例，以便在 MATLAB 中执行计算。
eng = future.result()通过 Python 调用 MATLAB 函数
从 MATLAB 函数返回输出参数
您可以直接调用任何 MATLAB® 函数并将结果返回到 Python®。例如，要确定某个数是否为质数，请使用该引擎调用 isprime 函数。
import matlab.engine
eng = matlab.engine.start_matlab()
tf = eng.isprime(37)
print(tf)
True
从 MATLAB 函数返回多个输出参数
当使用引擎调用函数时，默认情况下该引擎会返回单个输出参数。如果您知道函数可能返回多个参数，请使用 nargout 参数指定输出参数的数量。
要确定两个数的最大公分母，请使用 gcd 函数。设置 nargout 以从 gcd 返回三个输出参数。
import matlab.engine
eng = matlab.engine.start_matlab()
t = eng.gcd(100.0,80.0,nargout=3)
print(t)
(20.0, 1.0, -1.0)
不从 MATLAB 函数返回任何输出参数
有些 MATLAB 函数不会返回任何输出参数。如果函数不返回任何参数，则将 nargout 设为 0。
通过 Python 打开 MATLAB 帮助浏览器。
import matlab.engine
eng = matlab.engine.start_matlab()
eng.doc(nargout=0)
MATLAB doc 函数将打开浏览器，但不会返回输出参数。如果您没有指定 nargout=0，引擎将报告错误。
停止执行函数
要停止执行 MATLAB 函数，请按 Ctrl+C。控制权将返回给 Python。
Get Help for MATLAB Functions from Python
How to Find MATLAB Help
From Python®, you can access supporting documentation for all MATLAB® functions. This documentation includes examples and describes input arguments, output arguments, and calling syntax for each function.
The MATLAB Engine API for Python enables you to use the MATLAB doc and help functions. Use doc to open the MATLAB Help browser. Use help to get a brief description of a MATLAB function at the Python prompt.
Open MATLAB Help Browser from Python
From Python, you can use the Help browser to open MATLAB function reference pages and search the documentation.
For example, display the reference page for the MATLAB plot function. (Since doc returns no output arguments, you must set nargout=0. )
import matlab.engine
eng = matlab.engine.start_matlab()
eng.doc("plot",nargout=0)
The reference page includes a description of the function, examples, and links to related documentation.
Note
Click an example title, or on the arrow next to a title, if you do not see the examples on a MATLAB reference page. Examples can be collapsed or expanded within a page.
If you call eng.doc with no positional arguments, it opens the Help browser. (You still must set the keyword argument nargout=0).
eng.doc(nargout=0)
To search the MATLAB documentation, type an expression in the search box at the top of any page in the Help browser. The browser returns a list of search results, highlighting words that match the expression.
Alternatively, you can search the documentation with the docsearch function. For example, search for pages that mention plot.
eng.docsearch("plot",nargout=0)
Display MATLAB Help at Python Prompt
To display help text for a function at the Python prompt, call the MATLAB help function. For example, display the help text for erf.
import matlab.engine
eng = matlab.engine.start_matlab()
eng.help("erf",nargout=0)
ERF Error function.
Y = ERF(X) is the error function for each element of X. X must be
real. The error function is defined as:
erf(x) = 2/sqrt(pi) * integral from 0 to x of exp(-t^2) dt.
See also ERFC, ERFCX, ERFINV, ERFCINV.
Other functions named erf:
codistributed/erf
gpuArray/erf
sym/erf
Reference page in Help browser
doc erf将 Python 连接到正在运行的 MATLAB 会话
您可以将用于 Python® 的 MATLAB® 引擎连接到已在您的本地机器上运行的共享 MATLAB 会话。您也可以从单一 Python 会话连接到多个共享 MATLAB 会话。您可以在 MATLAB 会话期间的任何时间共享该会话，也可以在使用启动选项启动该会话时共享它。
连接到共享 MATLAB 会话
首先，将您的 MATLAB 会话转换为共享会话。从 MATLAB 调用 matlab.engine.shareEngine。
matlab.engine.shareEngine
在操作系统提示符下启动 Python。要连接到共享 MATLAB 会话，请从 Python 中调用 matlab.engine.connect_matlab。您可以从 Python 中调用任何 MATLAB 函数。
import matlab.engine
eng = matlab.engine.connect_matlab()
eng.sqrt(4.0)
2.0
您可以按名称连接到共享会话。要查找共享会话的名称，请从 Python 调用 matlab.engine.find_matlab。
matlab.engine.find_matlab()
('MATLAB_13232',)matlab.engine.find_matlab 返回一个 tuple，其中包含您的本地机器上所有共享 MATLAB 会话的名称。在本示例中，matlab.engine.shareEngine 为共享会话提供了默认名称 MATLAB_13232，其中 13232 是 MATLAB 进程的 ID。每当您启动 MATLAB 时，操作系统都会为 MATLAB 会话提供一个不同的进程 ID。
按名称连接到 MATLAB 会话。
eng.quit()
newEngine = matlab.engine.connect_matlab('MATLAB_13232')
如果您未指定具体共享会话的名称，则 matlab.engine.connect_matlab 会连接到由 matlab.engine.find_matlab 返回的 tuple 中指定的第一个会话。
异步连接到共享 MATLAB 会话
从 MATLAB 中，将您的 MATLAB 会话转换为共享会话。
matlab.engine.shareEngine
在操作系统提示符下启动 Python。异步连接到共享 MATLAB 会话。
import matlab.engine
future = matlab.engine.connect_matlab(async=True)
eng = future.result()
从 Python 调用 MATLAB 函数。
eng.sqrt(4.0)
2.0
连接到多个共享 MATLAB 会话
您可以从 Python 连接到多个共享 MATLAB 会话。
启动另一个 MATLAB 会话。从 MATLAB 调用 matlab.engine.shareEngine。为第二个共享会话命名。该名称必须是有效的 MATLAB 变量名称。有关有效变量名称的信息，请参阅变量名称。
matlab.engine.shareEngine('MATLABEngine2')
从 Python 中查找所有共享 MATLAB 会话。
import matlab.engine
matlab.engine.find_matlab()
('MATLAB_13232','MATLABEngine2')
要连接到共享 MATLAB 会话，请从 Python 中调用 matlab.engine.connect_matlab。
eng1 = matlab.engine.connect_matlab('MATLAB_13232')
eng2 = matlab.engine.connect_matlab('MATLABEngine2')
使用启动选项启动共享 MATLAB 会话
默认情况下，MATLAB 会话不共享。但是，您可以使用启动选项将 MATLAB 作为共享会话启动。
在操作系统提示符下启动共享 MATLAB 会话。
matlab -r "matlab.engine.shareEngine"
matlab -r "matlab.engine.shareEngine('MATLABEngine3')"
您可以使用默认名称启动会话，或者用单引号括起名称来启动会话。
在 Python 中使用 MATLAB 引擎工作区
此示例说明如何在 Python® 中将变量添加到 MATLAB® 引擎工作区。
当您启动引擎时，它提供与所有 MATLAB 变量的集合的一个接口。此集合名为 workspace，它被实现为附加到引擎的 Python 字典。每个 MATLAB 变量的名称都成为 workspace 字典中的一个键。workspace 中的键必须是有效的 MATLAB 标识符（例如，您不能将数字用作键）。您可以在 Python 中将变量添加到引擎工作区，然后即可在 MATLAB 函数中使用这些变量。
将变量添加到引擎工作区。
import matlab.engine
eng = matlab.engine.start_matlab()
x = 4.0
eng.workspace['y'] = x
a = eng.eval('sqrt(y)')
print(a)
2.0
在本示例中，x 仅作为 Python 变量存在。其值被赋给引擎工作区中的一个新条目 y，从而创建一个 MATLAB 变量。然后，您可以调用 MATLAB eval 函数以在 MATLAB 中执行 sqrt(y) 语句并将输出值 2.0 返回到 Python。
在 Python 中使用 MATLAB 数组
此示例说明如何在 Python® 中创建 MATLAB® 数组并将其作为输入参数传递给 MATLAB sqrt 函数。
matlab 包提供了构造函数以支持在 Python 中创建 MATLAB 数组。用于 Python 的 MATLAB 引擎 API 可以将此类数组作为输入参数传递给 MATLAB 函数，并且可以将此类数组作为输出参数返回给 Python。您可以从 Python 序列类型创建任何 MATLAB 数值或逻辑值类型的数组。
从 Python list 创建一个 MATLAB 数组。对该数组调用 sqrt 函数。
import matlab.engine
eng = matlab.engine.start_matlab()
a = matlab.double([1,4,9,16,25])
b = eng.sqrt(a)
print(b)
[[1.0,2.0,3.0,4.0,5.0]]
引擎返回 b，它是 1×5 的 matlab.double 数组。
创建一个多维数组。magic 函数将一个二维 matlab.double 数组返回给 Python。使用 for 循环分行打印数组中的每行。（当看到 ... 提示时再次按 Enter 以关闭循环并打印。）
a = eng.magic(6)
for x in a: print(x)
...
[35.0,1.0,6.0,26.0,19.0,24.0]
[3.0,32.0,7.0,21.0,23.0,25.0]
[31.0,9.0,2.0,22.0,27.0,20.0]
[8.0,28.0,33.0,17.0,10.0,15.0]
[30.0,5.0,34.0,12.0,14.0,16.0]
[4.0,36.0,29.0,13.0,18.0,11.0]
调用 tril 函数来获取 a 的下三角部分。在一个单独的行上打印数组中的每行。
b = eng.tril(a)
for x in b: print(x)
...
[35.0,0.0,0.0,0.0,0.0,0.0]
[3.0,32.0,0.0,0.0,0.0,0.0]
[31.0,9.0,2.0,0.0,0.0,0.0]
[8.0,28.0,33.0,17.0,0.0,0.0]
[30.0,5.0,34.0,12.0,14.0,0.0]
[4.0,36.0,29.0,13.0,18.0,11.0]通过 Python 调用 MATLAB 函数
从 MATLAB 函数返回输出参数
您可以直接调用任何 MATLAB® 函数并将结果返回到 Python®。例如，要确定某个数是否为质数，请使用该引擎调用 isprime 函数。
import matlab.engine
eng = matlab.engine.start_matlab()
tf = eng.isprime(37)
print(tf)
True
从 MATLAB 函数返回多个输出参数
当使用引擎调用函数时，默认情况下该引擎会返回单个输出参数。如果您知道函数可能返回多个参数，请使用 nargout 参数指定输出参数的数量。
要确定两个数的最大公分母，请使用 gcd 函数。设置 nargout 以从 gcd 返回三个输出参数。
import matlab.engine
eng = matlab.engine.start_matlab()
t = eng.gcd(100.0,80.0,nargout=3)
print(t)
(20.0, 1.0, -1.0)
不从 MATLAB 函数返回任何输出参数
有些 MATLAB 函数不会返回任何输出参数。如果函数不返回任何参数，则将 nargout 设为 0。
通过 Python 打开 MATLAB 帮助浏览器。
import matlab.engine
eng = matlab.engine.start_matlab()
eng.doc(nargout=0)
MATLAB doc 函数将打开浏览器，但不会返回输出参数。如果您没有指定 nargout=0，引擎将报告错误。
停止执行函数
要停止执行 MATLAB 函数，请按 Ctrl+C。控制权将返回给 Python。
MATLAB 数组作为 Python 变量
matlab Python® 包提供数组类以将 MATLAB® 数值类型的数组表示为 Python 变量，以便 MATLAB 数组可以在 Python 和 MATLAB 之间传递。
在 Python 中创建 MATLAB 数组
您可以通过从 matlab Python 包中调用构造函数（例如 matlab.double、matlab.int32）在 Python 会话中创建 MATLAB 数值数组。构造函数的名称表示 MATLAB 数值类型。
您可以在 Python 中使用自定义类型初始化 MATLAB 双精度数组。要使用该自定义类型进行初始化，它必须继承自 Python 抽象基类 collections.Sequence。
您可以将 MATLAB 数组作为输入参数传递给由用于 Python 的 MATLAB 引擎 API 调用的函数。当 MATLAB 函数将数值数组作为输出参数返回时，引擎会将该数组返回到 Python。
您可以使用包含数字的可选 initializer 输入参数初始化数组。initializer 必须是 Python 序列类型，例如 list、tuple 或其他序列类型。可选的 size 输入参数根据序列来设置数组大小。您可以通过指定 initializer 包含多个数字序列或通过指定 size 为多维来创建多维数组。通过将可选的 is_complex 输入参数设置为 True，可以创建复数 MATLAB 数组。matlab 包提供了下表中列出的 MATLAB 数组构造函数。
|
|
Python 中的构造函数调用 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
没有构造函数。当函数返回 MATLAB 对象的句柄时，引擎将 |
| [a] In Python 2.7 on Windows, [b] In Python 2.7 on Windows, [c] Logicals cannot be made into an array of complex numbers. |
|
当创建具有 N 个元素的数组时，数组大小为 1×N，因为它是 MATLAB 数组。
import matlab.engine
A = matlab.int8([1,2,3,4,5])
print(A.size)
(1, 5)
使用包含五个数字的 Python list 进行初始化。MATLAB 数组大小为 1×5，由 tuple (1,5) 指示。
Python 中的 MATLAB 数组属性和方法
所有使用 matlab 包构造函数创建的 MATLAB 数组都具有下表中列出的属性和方法。
| 属性或方法 |
用途 |
|---|---|
|
|
数组大小返回为 |
|
|
按照序列 |
Python 中的多维 MATLAB 数组
在 Python 中，您可以创建任何数值类型的多维 MATLAB 数组。使用两个 Python list 变量创建一个 2×5 MATLAB 双精度数组。
import matlab.engine
A = matlab.double([[1,2,3,4,5], [6,7,8,9,10]])
print(A)
[[1.0,2.0,3.0,4.0,5.0],[6.0,7.0,8.0,9.0,10.0]]
A 的 size 属性显示它是 2×5 数组。
print(A.size)
(2, 5)
在 Python 中对 MATLAB 数组进行索引
就像您可以对 Python list 和 tuple 变量进行索引一样，您也可以对 MATLAB 数组进行索引。
import matlab.engine
A = matlab.int8([1,2,3,4,5])
print(A[0])
[1,2,3,4,5]
MATLAB 数组的大小为 (1,5)；因此，A[0] 是 [1,2,3,4,5]。对该数组进行索引会得到 3。
print(A[0][2])
3
Python 索引是从零开始的。当在 Python 会话中访问 MATLAB 数组的元素时，请使用从零开始的索引。
对多维 MATLAB 数组进行索引。
A = matlab.double([[1,2,3,4,5], [6,7,8,9,10]])
print(A[1][2])
8.0
在 Python 中对 MATLAB 数组进行切片
您可以像对 Python list 和 tuple 变量进行切片一样，对 MATLAB 数组进行切片。
import matlab.engine
A = matlab.int8([1,2,3,4,5])
print(A[0][1:4])
[2,3,4]
您可以将数据分配到一个切片。以下代码显示从 Python list 到一个数组切片的分配。
A = matlab.double([[1,2,3,4],[5,6,7,8]]);
A[0] = [10,20,30,40]
print(A)
[[10.0,20.0,30.0,40.0],[5.0,6.0,7.0,8.0]]
您可以分配来自另一个 MATLAB 数组或来自包含数字的任何 Python 可迭代对象的数据。
您可以为分配指定切片，如下所示。
A = matlab.int8([1,2,3,4,5,6,7,8]);
A[0][2:4] = [30,40]
A[0][6:8] = [70,80]
print(A)
[[1,2,30,40,5,6,70,80]]
注意
对 MATLAB 数组进行切片与对 Python list 进行切片在行为上有所不同。对 MATLAB 数组进行切片将返回视图而不是浅拷贝。
假定 MATLAB 数组和 Python list 具有相同的值，分配切片也会产生不同结果，如以下代码所示。
A = matlab.int32([[1,2],[3,4],[5,6]])
L = [[1,2],[3,4],[5,6]]
A[0] = A[0][::-1]
L[0] = L[0][::-1]
print(A)
[[2,2],[3,4],[5,6]]
print(L)
[[2, 1], [3, 4], [5, 6]]
在 Python 中重构 MATLAB 数组
您可以使用 reshape 方法在 Python 中重构 MATLAB 数组。输入参数 size 必须是保留元素数量的一个序列。使用 reshape 将 1×9 MATLAB 数组更改为 3×3。
import matlab.engine
A = matlab.int8([1,2,3,4,5,6,7,8,9])
A.reshape((3,3))
print(A)
[[1,4,7],[2,5,8],[3,6,9]]
从 Python 将数据传递到 MATLAB
Python 类型到 MATLAB 标量类型的映射
当您将 Python® 数据作为输入参数传递到 MATLAB® 函数时，用于 Python 的 MATLAB 引擎会将数据转换为等效的 MATLAB 数据类型。
| Python 输入参数类型 - |
生成的 MATLAB 数据类型 |
|---|---|
|
|
|
|
|
复数 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
如果所有键都是字符串，则为结构体 |
Python 容器到 MATLAB 数组类型的映射
| Python 输入参数类型 - |
生成的 MATLAB 数据类型 |
|---|---|
|
|
数值数组 |
|
|
|
|
|
|
|
|
元胞数组 |
|
|
元胞数组 |
|
|
元胞数组 |
不支持的 Python 类型
MATLAB 引擎 API 不支持以下 Python 类型。
-
array.array（请改用 MATLAB 数值数组对象；请参阅MATLAB 数组作为 Python 变量） -
None -
module.type
Use MATLAB Handle Objects in Python
This example shows how to create an object from a MATLAB® handle class and call its methods in Python®.
In your current folder, create a MATLAB handle class in a file named Triangle.m.
classdef Triangle < handle
properties (SetAccess = private)
Base = 0;
Height = 0;
end
methods
function TR = Triangle(b,h)
TR.Base = b;
TR.Height = h;
end
function a = area(TR)
a = 0.5 .* TR.Base .* TR.Height;
end
function setBase(TR,b)
TR.Base = b;
end
function setHeight(TR,h)
TR.Height = h;
end
end
end
Start Python. Create a Triangle handle object and call its area method with the engine. Pass the handle object as the first positional argument.
import matlab.engine
eng = matlab.engine.start_matlab()
tr = eng.Triangle(5.0,3.0)
a = eng.area(tr)#tr是class的实例，eng.area是调用tr的实例化方法
print(a)
7.5
Copy tr to the MATLAB workspace. You can use eval to access the properties of a handle object from the workspace.
eng.workspace["wtr"] = tr
b = eng.eval("wtr.Base")
print(b)
5.0
Change the height with the setHeight method. If your MATLAB handle class defines get and set methods for properties, you can access properties without using the MATLAB workspace.
eng.setHeight(tr,8.0,nargout=0)
a = eng.area(tr)
print(a)20.0Default Numeric Types in MATLAB and Python
MATLAB® stores all numeric values as double-precision floating point numbers by default. In contrast, Python® stores some numbers as integers by default. Because of this difference, you might pass integers as input arguments to MATLAB functions that expect double-precision numbers.
Consider these variable assignments in MATLAB:
x = 4;
y = 4.0;Both x and y are of data type double. Now consider the same assignments in Python:
x = 4
y = 4.0
x and y are of different numeric data types.
print(type(x))
print(type(y))
Most MATLAB functions take numeric input arguments of data type double. The best practice is to ensure that numbers you pass as input arguments to MATLAB functions are of Python data type float, not Python data type int. You can ensure that Python variables are floating point numbers if you:
-
Make literals floating point numbers. For example, type
4.0instead of4. -
Convert to data type
float. For example,x = float(4)casts the number to data typefloat. -
Create a
matlab.doublearray from a number or sequence. For example,x = matlab.double([1,2,3,4,5])creates an array of MATLAB data typedoublefrom alistof Python integers.
When you pass an integer to a MATLAB function that takes an input argument of data type double, the engine raises an error. See MatlabExecutionError: Undefined Function for an example.
When you call a MATLAB function that does take integers as numeric input arguments, you can pass input arguments of Python data type int to the function.
Redirect Standard Output and Error to Python
This example shows how to redirect standard output and standard error from a MATLAB® function to Python® StringIO objects.
In Python 2.7, use the StringIO module to create StringIO objects. To capture a warning message from dec2hex, specify stdout and stderr.
import matlab.engine
eng = matlab.engine.start_matlab()
import StringIO
out = StringIO.StringIO()
err = StringIO.StringIO()
ret = eng.dec2hex(2**60,stdout=out,stderr=err)
print(out.getvalue())Warning: At least one of the input numbers is larger than the largest integer-valued
floating-point number (2^52). Results may be unpredictable.In Python 3.x, use the io module to create StringIO objects.
import matlab.engine
eng = matlab.engine.start_matlab()
import io
out = io.StringIO()
err = io.StringIO()
ret = eng.dec2base(2**60,16,stdout=out,stderr=err)
dec2base raises an exception when an input argument is greater than 2^52. Display the error message captured in err.
print(err.getvalue())Error using dec2base (line 22)
First argument must be an array of integers, 0 <= D <= 2^52.
Call MATLAB Functions Asynchronously from Python
This example shows how to call the MATLAB® sqrt function asynchronously from Python® and retrieve the square root later.
The engine calls MATLAB functions synchronously by default. Control returns to Python only when the MATLAB function finishes. But the engine also can call functions asynchronously. Control immediately returns to Python while MATLAB is still executing the function. The engine stores the result in a Python variable that can be inspected after the function finishes.
Use the background argument to call a MATLAB function asynchronously.
import matlab.engine
eng = matlab.engine.start_matlab()
future = eng.sqrt(4.0,background=True)
ret = future.result()
print(ret)
2.0
Use the done method to check if an asynchronous call finished.
tf = future.done()
print(tf)
True
To stop execution of the function before it finishes, call future.cancel().
Sort and Plot MATLAB Data from Python
This example shows how to sort data about patients into lists of smokers and nonsmokers in Python® and plot blood pressure readings for the patients with MATLAB®.
Start the engine, and read data about a set of patients into a MATLAB table. MATLAB provides a sample comma-delimited file, patients.dat, which contains information on 100 different patients.
import matlab.engine
eng = matlab.engine.start_matlab()
eng.eval("T = readtable('patients.dat');",nargout=0)
The MATLAB readtable function reads the data into a table. The engine does not support the MATLAB table data type. However, with the MATLAB table2struct function you can convert the table to a scalar structure, which is a data type the engine does support.
eng.eval("S = table2struct(T,'ToScalar',true);",nargout=0)
eng.eval("disp(S)",nargout=0)
LastName: {100x1 cell}
Gender: {100x1 cell}
Age: [100x1 double]
Location: {100x1 cell}
Height: [100x1 double]
Weight: [100x1 double]
Smoker: [100x1 double]
Systolic: [100x1 double]
Diastolic: [100x1 double]
SelfAssessedHealthStatus: {100x1 cell}
You can pass S from the MATLAB workspace into your Python session. The engine converts S to a Python dictionary, D.
D = eng.workspace["S"]
S has fields that contain arrays. The engine converts cell arrays to Python list variables, and numeric arrays to MATLAB arrays. Therefore, D["LastName"] is of data type list, and D["Age"] is of data type matlab.double.
Sort blood pressure readings into lists of smokers and nonsmokers. In patients.dat, the column Smoker indicated a smoker with logical 1 (true), and a nonsmoker with a logical 0 (false). Convert D["Smoker"] to a matlab.logical array for sorting.
smoker = matlab.logical(D["Smoker"])
Convert the Diastolic blood pressure readings and Smoker indicators into 1-by-100 MATLAB arrays for sorting.
pressure = D["Diastolic"]
pressure.reshape((1,100))
pressure = pressure[0]
smoker.reshape((1,100))
smoker = smoker[0]
Sort the pressure array into lists of blood pressure readings for smokers and non-smokers. Python list comprehensions provide a compact method for iterating over sequences. With the Python zip function, you can iterate over multiple sequences in a single for loop.
sp = [p for (p,s) in zip(pressure,smoker) if s is True]
nsp = [p for (p,s) in zip(pressure,smoker) if s is False]
Display the length of sp, the blood pressure readings for smokers in a list.
print(len(sp))
34
Display the length of nsp, the list of readings for nonsmokers.
print(len(nsp))
66
Calculate the mean blood pressure readings for smokers and nonsmokers. Convert sp and nsp to MATLAB arrays before passing them to the MATLAB mean function.
sp = matlab.double(sp)
nsp = matlab.double(nsp)
print(eng.mean(sp))
89.9117647059
Display the mean blood pressure for the nonsmokers.
print(eng.mean(nsp))
79.3787878788
Plot blood pressure readings for the smokers and nonsmokers. To define two x-axes for plotting, call the MATLAB linspace function. You can plot the 34 smokers and 66 nonsmokers on the same scatter plot.
sdx = eng.linspace(1.0,34.0,34)
nsdx = eng.linspace(1.0,34.0,66)
Show the axes boundaries with the box function.
eng.figure(nargout=0)
eng.hold("on",nargout=0)
eng.box("on",nargout=0)
You must call the figure, hold, and box functions with nargout=0, because these functions do not return output arguments.
Plot the blood pressure readings for the smokers and nonsmokers, and label the plot. For many MATLAB functions, the engine can return a handle to a MATLAB graphics object. You can store a handle to a MATLAB object in a Python variable, but you cannot manipulate the object properties in Python. You can pass MATLAB objects as input arguments to other MATLAB functions.
eng.scatter(sdx,sp,10,'blue')
In the rest of this example, assign the output argument of MATLAB functions to h as a placeholder.
h = eng.scatter(nsdx,nsp,10,'red')
h = eng.xlabel("Patient (Anonymized)")
h = eng.ylabel("Diastolic Blood Pressure (mm Hg)")
h = eng.title("Blood Pressure Readings for All Patients")
h = eng.legend("Smokers","Nonsmokers")
Draw lines showing the average blood pressure readings for smokers and nonsmokers.
x = matlab.double([0,35])
y = matlab.double([89.9,89.9])
h = eng.line(x,y,"Color","blue")
h = eng.text(21.0,88.5,"89.9 (Smoker avg.)","Color","blue")
y = matlab.double([79.4,79.4])
h = eng.line(x,y,"Color","red")
h = eng.text(5.0,81.0,"79.4 (Nonsmoker avg.)","Color","red")
See Also