(../index.

html)

NumPy.org (https://numpy.org/) Docs (https://numpy.org/doc)

NumPy v1.19 Manual (../index.html) NumPy Tutorials (tutorials_index.html)
index (../genindex.html) next (tutorial-svd.html) previous (misc.html)

Table of Contents (../contents.html)

NumPy for Matlab users
Introduction
Some Key Di erences
‘array’ or ‘matrix’? Which should I use?
Short answer
Long answer
Table of Rough MATLAB-NumPy Equivalents
General Purpose Equivalents
Linear Algebra Equivalents
Notes
Customizing Your Environment
Links

Previous topic
Miscellaneous (misc.html)

Next topic
Tutorial: Linear algebra on n-dimensional arrays (tutorial-svd.html)

Quick search
search

NumPy for Matlab users

Introduction
MATLAB® and NumPy/SciPy have a lot in common. But there are many di erences. NumPy and
SciPy were created to do numerical and scienti c computing in the most natural way with Python,
not to be MATLAB® clones. This page is intended to be a place to collect wisdom about the
di erences, mostly for the purpose of helping pro cient MATLAB® users become pro cient NumPy
and SciPy users.

Some Key Differences

/
 In MATLAB®, the basic data type is a In NumPy the basic type is a multidimensional
multidimensional array of double precision array. Operations on these arrays in all
oating point numbers. Most expressions take dimensionalities including 2D are element-
such arrays and return such arrays. Operations wise operations. One needs to use speci c
on the 2-D instances of these arrays are functions for linear algebra (though for matrix
designed to act more or less like matrix multiplication, one can use the @ operator in
operations in linear algebra. python 3.5 and above).
MATLAB® uses 1 (one) based indexing. The
Python uses 0 (zero) based indexing. The initial
initial element of a sequence is found using
element of a sequence is found using a[0].
a(1). See note INDEXING
NumPy is based on Python, which was
designed from the outset to be an excellent
MATLAB®’s scripting language was created for general-purpose programming language.
doing linear algebra. The syntax for basic While Matlab’s syntax for some array
matrix operations is nice and clean, but the API manipulations is more compact than NumPy’s,
for adding GUIs and making full- edged NumPy (by virtue of being an add-on to
applications is more or less an afterthought. Python) can do many things that Matlab just
cannot, for instance dealing properly with
stacks of matrices.
In MATLAB®, arrays have pass-by-value
semantics, with a lazy copy-on-write scheme to In NumPy arrays have pass-by-reference
prevent actually creating copies until they are semantics. Slice operations are views into an
actually needed. Slice operations copy parts of array.
the array.

‘array’ or ‘matrix’? Which should I use?

Historically, NumPy has provided a special matrix type, np.matrix, which is a subclass of ndarray
which makes binary operations linear algebra operations. You may see it used in some existing
code instead of np.array. So, which one to use?

Short answer

Use arrays.

They are the standard vector/matrix/tensor type of numpy. Many numpy functions return
arrays, not matrices.
There is a clear distinction between element-wise operations and linear algebra operations.
You can have standard vectors or row/column vectors if you like.

Until Python 3.5 the only disadvantage of using the array type was that you had to use dot instead
of * to multiply (reduce) two tensors (scalar product, matrix vector multiplication etc.). Since
Python 3.5 you can use the matrix multiplication @ operator.

Given the above, we intend to deprecate matrix eventually.

Long answer

NumPy contains both an array class and a matrix class. The array class is intended to be a
general-purpose n-dimensional array for many kinds of numerical computing, while matrix is
intended to facilitate linear algebra computations speci cally. In practice there are only a handful
of key di erences between the two.

Operators * and @, functions dot(), and multiply():

/
 For array, ``*`` means element-wise multiplication, while ``@`` means matrix
multiplication; they have associated functions multiply() and dot(). (Before python
3.5, @ did not exist and one had to use dot() for matrix multiplication).
For matrix, ``*`` means matrix multiplication, and for element-wise multiplication one
has to use the multiply() function.
Handling of vectors (one-dimensional arrays)

For array, the vector shapes 1xN, Nx1, and N are all di erent things. Operations like
A[:,1] return a one-dimensional array of shape N, not a two-dimensional array of shape
Nx1. Transpose on a one-dimensional array does nothing.
For matrix, one-dimensional arrays are always upconverted to 1xN or Nx1 matrices (row
or column vectors). A[:,1] returns a two-dimensional matrix of shape Nx1.
Handling of higher-dimensional arrays (ndim > 2)

array objects can have number of dimensions > 2;

matrix objects always have exactly two dimensions.
Convenience attributes

array has a .T attribute, which returns the transpose of the data.

matrix also has .H, .I, and .A attributes, which return the conjugate transpose, inverse,
and asarray() of the matrix, respectively.
Convenience constructor

The array constructor takes (nested) Python sequences as initializers. As in,

array([[1,2,3],[4,5,6]]).
The matrix constructor additionally takes a convenient string initializer. As in
matrix("[1 2 3; 4 5 6]").

There are pros and cons to using both:

array

:) Element-wise multiplication is easy: A*B.

:( You have to remember that matrix multiplication has its own operator, @.
:) You can treat one-dimensional arrays as either row or column vectors. A @ v treats v
as a column vector, while v @ A treats v as a row vector. This can save you having to type
a lot of transposes.
:) array is the “default” NumPy type, so it gets the most testing, and is the type most
likely to be returned by 3rd party code that uses NumPy.
:) Is quite at home handling data of any number of dimensions.
:) Closer in semantics to tensor algebra, if you are familiar with that.
:) All operations ( *, /, +, - etc.) are element-wise.
:( Sparse matrices from scipy.sparse do not interact as well with arrays.
matrix

:\\ Behavior is more like that of MATLAB® matrices.

<:( Maximum of two-dimensional. To hold three-dimensional data you need array or
perhaps a Python list of matrix.
<:( Minimum of two-dimensional. You cannot have vectors. They must be cast as single-
column or single-row matrices.
<:( Since array is the default in NumPy, some functions may return an array even if
you give them a matrix as an argument. This shouldn’t happen with NumPy functions (if it
does it’s a bug), but 3rd party code based on NumPy may not honor type preservation like
NumPy does.
:) A*B is matrix multiplication, so it looks just like you write it in linear algebra (For Python
>= 3.5 plain arrays have the same convenience with the @ operator).
<:( Element-wise multiplication requires calling a function, multiply(A,B).

/
 <:( The use of operator overloading is a bit illogical: * does not work element-wise but /
does.
Interaction with scipy.sparse is a bit cleaner.

The array is thus much more advisable to use. Indeed, we intend to deprecate matrix
eventually.

Table of Rough MATLAB-NumPy Equivalents

The table below gives rough equivalents for some common MATLAB® expressions. These are not
exact equivalents, but rather should be taken as hints to get you going in the right direction. For
more detail read the built-in documentation on the NumPy functions.

In the table below, it is assumed that you have executed the following commands in Python:

from numpy import *

import scipy.linalg

Also assume below that if the Notes talk about “matrix” that the arguments are two-dimensional
entities.

General Purpose Equivalents

MATLAB numpy Notes

get help on the
help func info(func) or help(func) or func? (in Ipython)
function func
nd out where
which func see note HELP (numpy-for-matlab-users.notes)
func is de ned
print source for
type func source(func) or func?? (in Ipython) func (if not a
native function)
short-circuiting
logical AND
operator (Python
a && b a and b
native operator);
scalar arguments
only
short-circuiting
logical OR
operator (Python
a || b a or b
native operator);
scalar arguments
only
complex
1*i, 1*j, 1i, 1j 1j
numbers
Distance between
1 and the nearest
eps np.spacing(1)
oating point
number.
integrate an ODE
ode45 scipy.integrate.solve_ivp(f) with Runge-Kutta
4,5
integrate an ODE
ode15s scipy.integrate.solve_ivp(f, method='BDF')
with BDF method /
Linear Algebra Equivalents

MATLAB NumPy Notes

get the number of
ndims(a) ndim(a) or a.ndim
dimensions of an array
get the number of
numel(a) size(a) or a.size
elements of an array
get the “size” of the
size(a) shape(a) or a.shape
matrix
get the number of
elements of the n-th
dimension of array a.
(Note that MATLAB®
size(a,n) a.shape[n-1]
uses 1 based indexing
while Python uses 0
based indexing, See
note INDEXING)
[ 1 2 3; 4 5 6 ] array([[1.,2.,3.], [4.,5.,6.]]) 2x3 matrix literal
construct a matrix
[ a b; c d ] block([[a,b], [c,d]]) from blocks a, b, c,
and d
access last element in
a(end) a[-1]
the 1xn matrix a
access element in
a(2,5) a[1,4] second row, fth
column
a(2,:) a[1] or a[1,:] entire second row of a
a(1:5,:) a[0:5] or a[:5] or a[0:5,:] the rst ve rows of a
a(end-4:end,:) a[-5:] the last ve rows of a
rows one to three and
columns ve to nine of
a(1:3,5:9) a[0:3][:,4:9]
a. This gives read-only
access.
rows 2,4 and 5 and
columns 1 and 3. This
a([2,4,5],[1,3]) a[ix_([1,3,4],[0,2])] allows the matrix to be
modi ed, and doesn’t
require a regular slice.
every other row of a,
starting with the third
a(3:2:21,:) a[ 2:21:2,:]
and going to the
twenty- rst
every other row of a,
a(1:2:end,:) a[ ::2,:]
starting with the rst
a with rows in reverse
a(end:-1:1,:) or flipud(a) a[ ::-1,:]
order
a with copy of the rst
a([1:end 1],:) a[r_[:len(a),0]] row appended to the
end
a.' a.transpose() or a.T transpose of a

/
MATLAB NumPy Notes
conjugate transpose of
a' a.conj().transpose() or a.conj().T
a
a * b a @ b matrix multiply
a .* b a * b element-wise multiply
a./b a/b element-wise divide
element-wise
a.^3 a**3
exponentiation
matrix whose i,jth
element is (a_ij > 0.5).
The Matlab result is an
array of 0s and 1s. The
(a>0.5) (a>0.5)
NumPy result is an
array of the boolean
values False and
True.
nd the indices where
find(a>0.5) nonzero(a>0.5)
( a > 0.5)
extract the columms of
a(:,find(v>0.5)) a[:,nonzero(v>0.5)[0]]
a where vector v > 0.5
extract the columms of
a(:,find(v>0.5)) a[:,v.T>0.5] a where column vector
v > 0.5
a with elements less
a(a<0.5)=0 a[a<0.5]=0
than 0.5 zeroed out
a with elements less
a .* (a>0.5) a * (a>0.5)
than 0.5 zeroed out
set all values to the
a(:) = 3 a[:] = 3
same scalar value
numpy assigns by
y=x y = x.copy()
reference
numpy slices are by
y=x(2,:) y = x[1,:].copy()
reference
turn array into vector
(note that this forces a
copy). To obtain the
y=x(:) y = x.flatten()
same data ordering as
in Matlab, use
x.flatten('F').
create an increasing
arange(1.,11.) or r_[1.:11.] or
1:10 vector (see note
r_[1:10:10j]
RANGES)
create an increasing
arange(10.) or r_[:10.] or
0:9 vector (see note
r_[:9:10j]
RANGES)
[1:10]' arange(1.,11.)[:, newaxis] create a column vector
3x4 two-dimensional
zeros(3,4) zeros((3,4)) array full of 64-bit
oating point zeros

/
MATLAB NumPy Notes
3x4x5 three-
dimensional array full
zeros(3,4,5) zeros((3,4,5))
of 64-bit oating point
zeros
3x4 two-dimensional
ones(3,4) ones((3,4)) array full of 64-bit
oating point ones
eye(3) eye(3) 3x3 identity matrix
vector of diagonal
diag(a) diag(a)
elements of a
square diagonal matrix
diag(a,0) diag(a,0) whose nonzero values
are the elements of a
random.rand(3,4) or
rand(3,4) random 3x4 matrix
random.random_sample((3, 4))
4 equally spaced
linspace(1,3,4) linspace(1,3,4) samples between 1
and 3, inclusive
two 2D arrays: one of x
mgrid[0:9.,0:6.] or
[x,y]=meshgrid(0:8,0:5) values, the other of y
meshgrid(r_[0:9.],r_[0:6.]
values
ogrid[0:9.,0:6.] or the best way to eval
ix_(r_[0:9.],r_[0:6.] functions on a grid
[x,y]=meshgrid([1,2,4],[2,4,5]) meshgrid([1,2,4],[2,4,5])
the best way to eval
ix_([1,2,4],[2,4,5])
functions on a grid
create m by n copies of
repmat(a, m, n) tile(a, (m, n))
a
concatenate((a,b),1) or
concatenate columns
[a b] hstack((a,b)) or
of a and b
column_stack((a,b)) or c_[a,b]
concatenate((a,b)) or vstack((a,b)) concatenate rows of a
[a; b]
or r_[a,b] and b
maximum element of
max(max(a)) a.max() a (with ndims(a)<=2 for
matlab)
maximum element of
max(a) a.max(0) each column of matrix
a
maximum element of
max(a,[],2) a.max(1)
each row of matrix a
compares a and b
element-wise, and
max(a,b) maximum(a, b)
returns the maximum
value from each pair
norm(v) sqrt(v @ v) or np.linalg.norm(v) L2 norm of vector v
element-by-element
AND operator (NumPy
a & b logical_and(a,b)
ufunc) See note
LOGICOPS
/
MATLAB NumPy Notes
element-by-element
OR operator (NumPy
a | b logical_or(a,b)
ufunc) See note
LOGICOPS
bitwise AND operator
bitand(a,b) a & b (Python native and
NumPy ufunc)
bitwise OR operator
bitor(a,b) a | b (Python native and
NumPy ufunc)
inverse of square
inv(a) linalg.inv(a)
matrix a
pseudo-inverse of
pinv(a) linalg.pinv(a)
matrix a
matrix rank of a 2D
rank(a) linalg.matrix_rank(a)
array / matrix a
linalg.solve(a,b) if a is square;
a\b solution of a x = b for x
linalg.lstsq(a,b) otherwise
b/a Solve a.T x.T = b.T instead solution of x a = b for x
singular value
[U,S,V]=svd(a) U, S, Vh = linalg.svd(a), V = Vh.T
decomposition of a
cholesky factorization
of a matrix ( chol(a)
in matlab returns an
upper triangular
chol(a) linalg.cholesky(a).T
matrix, but
linalg.cholesky(a)
returns a lower
triangular matrix)
eigenvalues and
[V,D]=eig(a) D,V = linalg.eig(a)
eigenvectors of a
eigenvalues and
[V,D]=eig(a,b) D,V = scipy.linalg.eig(a,b)
eigenvectors of a, b
nd the k largest
[V,D]=eigs(a,k) eigenvalues and
eigenvectors of a
[Q,R,P]=qr(a,0) Q,R = scipy.linalg.qr(a) QR decomposition
LU decomposition
L,U = scipy.linalg.lu(a) or
[L,U,P]=lu(a) (note: P(Matlab) ==
LU,P=scipy.linalg.lu_factor(a)
transpose(P(numpy)) )
Conjugate gradients
conjgrad scipy.sparse.linalg.cg
solver
fft(a) fft(a) Fourier transform of a
inverse Fourier
ifft(a) ifft(a)
transform of a
sort(a) sort(a) or a.sort() sort the matrix
sort the rows of the
[b,I] = sortrows(a,i) I = argsort(a[:,i]), b=a[I,:]
matrix
regress(y,X) linalg.lstsq(X,y) multilinear regression

/
MATLAB NumPy Notes
downsample with low-
decimate(x, q) scipy.signal.resample(x, len(x)/q)
pass ltering
unique(a) unique(a)
squeeze(a) a.squeeze()

Notes
Submatrix: Assignment to a submatrix can be done with lists of indexes using the ix_ command.
E.g., for 2d array a, one might do: ind=[1,3]; a[np.ix_(ind,ind)]+=100.

HELP: There is no direct equivalent of MATLAB’s which command, but the commands help and
source will usually list the lename where the function is located. Python also has an inspect
module (do import inspect) which provides a getfile that often works.

INDEXING: MATLAB® uses one based indexing, so the initial element of a sequence has index 1.
Python uses zero based indexing, so the initial element of a sequence has index 0. Confusion and
amewars arise because each has advantages and disadvantages. One based indexing is
consistent with common human language usage, where the “ rst” element of a sequence has index
1. Zero based indexing simpli es indexing
(https://groups.google.com/group/comp.lang.python/msg/1bf4d925dfbf368?
q=g:thl3498076713d&hl=en). See also a text by prof.dr. Edsger W. Dijkstra
(https://www.cs.utexas.edu/users/EWD/transcriptions/EWD08xx/EWD831.html).

RANGES: In MATLAB®, 0:5 can be used as both a range literal and a ‘slice’ index (inside
parentheses); however, in Python, constructs like 0:5 can only be used as a slice index (inside
square brackets). Thus the somewhat quirky r_ object was created to allow numpy to have a
similarly terse range construction mechanism. Note that r_ is not called like a function or a
constructor, but rather indexed using square brackets, which allows the use of Python’s slice syntax
in the arguments.

LOGICOPS: & or | in NumPy is bitwise AND/OR, while in Matlab & and | are logical AND/OR. The
di erence should be clear to anyone with signi cant programming experience. The two can appear
to work the same, but there are important di erences. If you would have used Matlab’s & or |
operators, you should use the NumPy ufuncs logical_and/logical_or. The notable di erences
between Matlab’s and NumPy’s & and | operators are:

Non-logical {0,1} inputs: NumPy’s output is the bitwise AND of the inputs. Matlab treats any
non-zero value as 1 and returns the logical AND. For example (3 & 4) in NumPy is 0, while in
Matlab both 3 and 4 are considered logical true and (3 & 4) returns 1.
Precedence: NumPy’s & operator is higher precedence than logical operators like < and >;
Matlab’s is the reverse.

If you know you have boolean arguments, you can get away with using NumPy’s bitwise operators,
but be careful with parentheses, like this: z = (x > 1) & (x < 2). The absence of NumPy operator
forms of logical_and and logical_or is an unfortunate consequence of Python’s design.

RESHAPE and LINEAR INDEXING: Matlab always allows multi-dimensional arrays to be accessed
using scalar or linear indices, NumPy does not. Linear indices are common in Matlab programs, e.g.
nd() on a matrix returns them, whereas NumPy’s nd behaves di erently. When converting
Matlab code it might be necessary to rst reshape a matrix to a linear sequence, perform some
indexing operations and then reshape back. As reshape (usually) produces views onto the same
storage, it should be possible to do this fairly e ciently. Note that the scan order used by reshape
in NumPy defaults to the ‘C’ order, whereas Matlab uses the Fortran order. If you are simply
converting to a linear sequence and back this doesn’t matter. But if you are converting reshapes
from Matlab code which relies on the scan order, then this Matlab code: z = reshape(x,3,4); should
become z = x.reshape(3,4,order=’F’).copy() in NumPy.
/
Customizing Your Environment
In MATLAB® the main tool available to you for customizing the environment is to modify the
search path with the locations of your favorite functions. You can put such customizations into a
startup script that MATLAB will run on startup.

NumPy, or rather Python, has similar facilities.

To modify your Python search path to include the locations of your own modules, de ne the
PYTHONPATH environment variable.
To have a particular script le executed when the interactive Python interpreter is started,
de ne the PYTHONSTARTUP environment variable to contain the name of your startup script.

Unlike MATLAB®, where anything on your path can be called immediately, with Python you need to
rst do an ‘import’ statement to make functions in a particular le accessible.

For example you might make a startup script that looks like this (Note: this is just an example, not a
statement of “best practices”):

# Make all numpy available via shorter 'np' prefix

import numpy as np
# Make all matlib functions accessible at the top level via M.func()
import numpy.matlib as M
# Make some matlib functions accessible directly at the top level via, e.g. rand
(3,3)
from numpy.matlib import rand,zeros,ones,empty,eye
# Define a Hermitian function
def hermitian(A, **kwargs):
return np.transpose(A,**kwargs).conj()
# Make some shortcuts for transpose,hermitian:
# np.transpose(A) --> T(A)
# hermitian(A) --> H(A)
T = np.transpose
H = hermitian

Links
See http://mathesaurus.sf.net/ (http://mathesaurus.sf.net/) for another MATLAB®/NumPy cross-
reference.

An extensive list of tools for scienti c work with python can be found in the topical software page
(https://scipy.org/topical-software.html).

MATLAB® and SimuLink® are registered trademarks of The MathWorks.