Main Content

matlab Python Module

The matlab Python® module provides array classes to represent arrays of MATLAB® numeric types as Python variables so that MATLAB arrays can be passed between Python and MATLAB.

MATLAB Classes in the Python Module

  • You can use MATLAB numeric arrays in Python code by importing the Python package and calling the necessary constructors. For example: The name of the constructor indicates the MATLAB numeric type. You can pass MATLAB arrays as input arguments to MATLAB functions called from Python. When a MATLAB function returns a numeric array as an output argument, the array is returned to Python.

  • You can initialize an array with an optional initializer input argument that contains numbers. The initializer argument must be a Python sequence type such as a list or a tuple, or other sequence type.

  • You can initialize an array with an optional vector input argument that contains input of size 1-by-N. If you use vector, you cannot use initializer.

  • The optional size input argument sets the size of the initialized array. To create multidimensional arrays, specify initializer to contain multiple sequences of numbers, or specify size to be multidimensional. You can create a MATLAB array of complex numbers by setting the optional is_complex keyword argument to True.

  • You can use custom types for initializing MATLAB double arrays in Python. The custom type should implement the Python buffer protocol. For example ndarray in NumPy.

Class from matlab Python Package

Constructor Call in Python

Examples

matlab.double

matlab.double(initializer=None|vector=None,
size=None,
is_complex=False)
>>> a = matlab.double(4)
>>> b = matlab.double(vector=[11, 22, 33])
>>> c = matlab.double([[10, 20],[30,40]])
>>> d = matlab.double(initializer=[[10, 20],[30,40]], size=[2,2],is_complex=False)
>>> e = matlab.double(vector=range(0, 20))
>>> f = matlab.double(vector=[x*x for x in range(0, 10, 2)])
>>> g = matlab.double([[1.1+2.4j, 3+4j],[5.3,6.7]], is_complex=True)

matlab.single

matlab.single(initializer=None|vector=None,
size=None,
is_complex=False)
>>> a = matlab.single([[1.1, 2.2, 3.3],[4.4, 5.5, 6.6]])
>>> a = matlab.single(vector=[11, 22, 33], is_complex=False)

matlab.int8

matlab.int8(initializer=None|vector=None,
size=None,
is_complex=False)
>>> a = matlab.int8([[11, 22, 33],[44, 55, 66]])
>>> a = matlab.int8(vector=[11, 22, 33], is_complex=False)

matlab.int16

matlab.int16(initializer=None|vector=None,
size=None,
is_complex=False)
>>> e = matlab.int16([[1+2j, 3+4j],[-5,6]], is_complex=True)

matlab.int32

matlab.int32(initializer=None|vector=None,
size=None,
is_complex=False)
>>> a = matlab.int32(initializer=[[11, 22, 33],[44, -55, 66]], size=[2,3], is_complex=False)

matlab.int64

matlab.int64(initializer=None|vector=None,
size=None,
is_complex=False)
>>> a = matlab.int64([[11, 22, 33],[44, -55, 66]])

matlab.uint8

matlab.uint8(initializer=None|vector=None,
size=None,
is_complex=False)
>>> a = matlab.uint8([[11, 22, 33],[44, 55, 66]])
>>> b = matlab.uint8(vector=[11, 22, 33], is_complex=False)

matlab.uint16

matlab.uint16(initializer=None|vector=None,
size=None,
is_complex=False)
>>> a = matlab.uint16(initializer=[[11, 22, 33],[44, 55, 66]], size=[2,3], is_complex=False)
>>> b = matlab.uint16(vector=[11, 22, 33], is_complex=False)
>>> c = matlab.uint16([[11, 22, 33],[44, 55, 66]])

matlab.uint32

matlab.uint32(initializer=None|vector=None,
size=None,
is_complex=False)
>>> a = matlab.uint32(vector=[11, 22, 33], is_complex=False)
>>> b = matlab.uint32([[11, 22, 33],[44, 55, 66]])

matlab.uint64

matlab.uint64(initializer=None|vector=None,
size=None,
is_complex=False)
>>> a = matlab.uint64([[11, 22, 33],[44, 55, 66]])
>>> b = matlab.uint64(vector=[11, 22, 33], is_complex=False)

matlab.logical

matlab.logical(initializer=None|vector=None,
size=None)a
>>> a = matlab.logical(initializer=[[True, False, True],[True, True, True]], size=[2,3])
>>> b = matlab.logical([[True, False, True],[True, True, True]])
>>> c = matlab.logical(vector=[True, False, True])
>>> d = matlab.logical([True, False, True])

a Logicals cannot be made into an array of complex numbers.

Properties and Methods of MATLAB Classes in the matlab Python Package

All MATLAB arrays created with package constructors have the following properties and methods:

Properties

Property NameDescriptionExamples

size

A tuple of integers representing the dimensions of an array

>>> a = matlab.int16([[1, 2, 3],[4, 5, 6]]) 
>>> a.size 
(2, 3)

itemsize

An integer representing the size in bytes of an element of the array

>>> a = matlab.int16() 
>>> a.itemsize 
2 
>>> b = matlab.int32() 
>>> b.itemsize 
4

Methods

Method NamePurposeExamples
clone()

Return a new distinct object with contents identical to the contents of the original object

>>> a = matlab.int16([[1, 2, 3],[4, 5, 6]]) 
>>> b = a.clone() 
>>> print(b)
[[1,2,3],[4,5,6]]
>>> b[0][0] = 100 
>>> b matlab.int16([[100,2,3],[4,5,6]]) 
>>> print(a )
[[1,2,3],[4,5,6]]
real()

Return the real parts of elements that are complex numbers, in column-major order, as a 1-by-N array

>>> a = matlab.int16([[1 + 10j, 2 + 20j, 3 + 30j],[4, 5, 6]], is_complex=True) 
>>> print(a.real())
[1,4,2,5,3,6]
imag()

Return the imaginary parts of elements that are complex numbers, in column-major order, as a 1-by-N array

>>> a = matlab.int16([[1 + 10j, 2 + 20j, 3 + 30j],[4, 5, 6]], is_complex=True) 
>>> print(a.imag()) 
[10,0,20,0,30,0]
noncomplex()

Return elements that are not complex numbers, in column-major order, as a 1-by-N array

>>> a = matlab.int16([[1, 2, 3],[4, 5, 6]]) 
>>> print(a.noncomplex()) 
[1,4,2,5,3,6]
  • reshape(dim1,dim2,...,dimN)

  • reshape([dim1,dim2,...,dimN)]

Reshape the array according to the dimensions and return the result

>>> a = matlab.int16([[1, 2, 3],[4, 5, 6]]) 
>>> print(a)
[[1,2,3],[4,5,6]]
>>> a.reshape(3, 2)
>>> print(a) 
[[1,5],[4,3],[2,6]]
toarray()

Return a standard Python array.array object constructed from the contents. Applicable for one-dimensional sequences only.

>>> a = matlab.int16([[1, 2, 3],[4, 5, 6]]) 
>>> a[0].toarray() 
array('h', [1, 2, 3]) 
>>> b = matlab.int16([[1 + 10j, 2 + 20j, 3 + 30j],[4, 5, 6]], is_complex=True) 
>>> b.real().toarray() 
array('h', [1, 4, 2, 5, 3, 6])
tomemoryview()

Return a standard Python memoryview object constructed from the contents

>>> a = matlab.int16([[1, 2, 3],[4, 5, 6]]) 
>>> b = a.tomemoryview() 
>>> b.tolist() 
[[1, 2, 3], [4, 5, 6]] 
>>> b.shape 
(2, 3)

Create a MATLAB Array with N Elements

When you create an array with N elements, the size is 1-by-N because it is a MATLAB array.

import matlab
A = matlab.int8([1,2,3,4,5])
print(A.size)

(1, 5)

The initializer is a Python list containing five numbers. The MATLAB array size is 1-by-5, indicated by the tuple (1,5).

Multidimensional MATLAB Arrays in Python

In Python, you can create multidimensional MATLAB arrays of any numeric type. Use two Python lists of floats to create a 2-by-5 MATLAB array of doubles.

import matlab
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]]

The size attribute of A shows it is a 2-by-5 array.

print(A.size)

(2, 5)

Index Into MATLAB Arrays in Python

You can index into MATLAB arrays just as you can index into Python lists and tuples.

import matlab
A = matlab.int8([1,2,3,4,5])
print(A[0])

[1,2,3,4,5]

The size of the MATLAB array is (1,5); therefore, A[0] is [1,2,3,4,5]. Index into the array to get 3.

print(A[0][2])

3

Python indexing is zero-based. When you access elements of MATLAB arrays in a Python session, use zero-based indexing.

This example shows how to index into a multidimensional MATLAB array.

A = matlab.double([[1,2,3,4,5], [6,7,8,9,10]])
print(A[1][2])

8.0

Slice MATLAB Arrays in Python

You can slice MATLAB arrays just as you can slice Python lists and tuples.

import matlab
A = matlab.int8([[1,2,3,4,5]])
print(A[0][1:4])

[2,3,4]

You can assign data to a slice. This example shows an assignment from a Python list to the array.

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]]

You can assign data from another MATLAB array, or from any Python iterable that contains numbers.

You can specify slices for assignment, as shown in this example.

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]]

Reshaping MATLAB Arrays in Python

You can reshape a MATLAB array in Python with the reshape method. The input argument, size, must be a sequence that does not change the number of elements in the array. Use reshape to change a 1-by-9 MATLAB array to 3-by-3.

import matlab
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]]

Use Custom Types to Initialize MATLAB Arrays

You can use custom types such as the ndarray in NumPy for initializing MATLAB arrays in Python. The custom type should implement the Python buffer protocol.

import matlab
import numpy

nf = numpy.array([[1.1, 2,2, 3.3], [4.4, 5.5, 6.6]])
md = matlab.double(nf)
ni32 = numpy.array([[1, 2, 3], [4, 5, 6]], dtype='int32')
mi32 = matlab.int32(ni32)

Related Topics