NumPy for MATLAB users#
Introduction#
MATLAB® and NumPy have a lot in common, but NumPy was created to work with Python, not to be a MATLAB clone. This guide will help MATLAB users get started with NumPy.
Some key differences#
In MATLAB, the basic type, even for scalars, is a multidimensional array. Array assignments in MATLAB are stored as 2D arrays of double precision floating point numbers, unless you specify the number of dimensions and type. Operations on the 2D instances of these arrays are modeled on matrix operations in linear algebra. 
In NumPy, the basic type is a multidimensional 
MATLAB numbers indices from 1; 
NumPy, like Python, numbers indices from 0; 
MATLAB’s scripting language was created for linear algebra so the syntax for some array manipulations is more compact than NumPy’s. On the other hand, the API for adding GUIs and creating fullfledged applications is more or less an afterthought. 
NumPy is based on Python, a generalpurpose language. The advantage to NumPy is access to Python libraries including: SciPy, Matplotlib, Pandas, OpenCV, and more. In addition, Python is often embedded as a scripting language in other software, allowing NumPy to be used there too. 
MATLAB array slicing uses passbyvalue semantics, with a lazy copyonwrite scheme to prevent creating copies until they are needed. Slicing operations copy parts of the array. 
NumPy array slicing uses passbyreference, that does not copy the arguments. Slicing operations are views into an array. 
Rough equivalents#
The table below gives rough equivalents for some common MATLAB expressions. These are similar expressions, not equivalents. For details, see the documentation.
In the table below, it is assumed that you have executed the following commands in Python:
import numpy as np
from scipy import io, integrate, linalg, signal
from scipy.sparse.linalg import eigs
Also assume below that if the Notes talk about “matrix” that the arguments are twodimensional entities.
General purpose equivalents#
MATLAB 
NumPy 
Notes 



get help on the function func 

find out where func is defined 



print source for func (if not a native function) 


comment a line of code with the text 
for i=1:3
fprintf('%i\n',i)
end

for i in range(1, 4):
print(i)

use a forloop to print the numbers 1, 2, and 3 using 


shortcircuiting logical AND operator (Python native operator); scalar arguments only 


shortcircuiting logical OR operator (Python native operator); scalar arguments only 
>> 4 == 4
ans = 1
>> 4 == 5
ans = 0

>>> 4 == 4
True
>>> 4 == 5
False

The boolean objects
in Python are 
a=4
if a==4
fprintf('a = 4\n')
elseif a==5
fprintf('a = 5\n')
end

a = 4
if a == 4:
print('a = 4')
elif a == 5:
print('a = 5')

create an ifelse statement to check if 


complex numbers 


Upper bound to relative error due to rounding in 64bit floating point arithmetic. 


Load MATLAB variables saved to the file 


integrate an ODE with RungeKutta 4,5 


integrate an ODE with BDF method 
Linear algebra equivalents#
MATLAB 
NumPy 
Notes 



number of dimensions of array 


number of elements of array 


“size” of array 


get the number of elements of the nth dimension of array 


define a 2x3 2D array 


construct a matrix from blocks 


access last element in MATLAB vector (1xn or nx1) or 1D NumPy array



access element in second row, fifth column in 2D array 


entire second row of 2D array 


first 5 rows of 2D array 


last 5 rows of 2D array 


The first through third rows and fifth through ninth columns of a 2D array, 


rows 2,4 and 5 and columns 1 and 3. This allows the matrix to be modified, and doesn’t require a regular slice. 


every other row of 


every other row of 








transpose of 


conjugate transpose of 


matrix multiply 


elementwise multiply 


elementwise divide 


elementwise exponentiation 


matrix whose i,jth element is (a_ij > 0.5). The MATLAB result is an
array of logical values 0 and 1. The NumPy result is an array of the boolean
values 


find the indices where ( 


extract the columns of 


extract the columns of 








set all values to the same scalar value 


NumPy assigns by reference 


NumPy slices are by reference 


turn array into vector (note that this forces a copy). To obtain the
same data ordering as in MATLAB, use 


create an increasing vector (see note RANGES) 


create an increasing vector (see note RANGES) 


create a column vector 


3x4 twodimensional array full of 64bit floating point zeros 


3x4x5 threedimensional array full of 64bit floating point zeros 


3x4 twodimensional array full of 64bit floating point ones 


3x3 identity matrix 


returns a vector of the diagonal elements of 2D array, 


returns a square diagonal matrix whose nonzero values are the elements of
vector, 
rng(42,'twister')
rand(3,4)

from numpy.random import default_rng
rng = default_rng(42)
rng.random(3, 4)
or older version: 
generate a random 3x4 array with default random number generator and seed = 42 


4 equally spaced samples between 1 and 3, inclusive 


two 2D arrays: one of x values, the other of y values 

the best way to eval functions on a grid 





the best way to eval functions on a grid 



create m by n copies of 


concatenate columns of 


concatenate rows of 


maximum element of 


maximum element of each column of array 


maximum element of each row of array 


compares 


L2 norm of vector 


elementbyelement AND operator (NumPy ufunc) See note LOGICOPS 


elementbyelement OR operator (NumPy ufunc) See note LOGICOPS 


bitwise AND operator (Python native and NumPy ufunc) 


bitwise OR operator (Python native and NumPy ufunc) 


inverse of square 2D array 


pseudoinverse of 2D array 


matrix rank of a 2D array 


solution of a x = b for x 

Solve 
solution of x a = b for x 


singular value decomposition of 


Cholesky factorization of a 2D array ( 


eigenvalues \(\lambda\) and eigenvectors \(\bar{v}\) of 


eigenvalues \(\lambda\) and eigenvectors \(\bar{v}\) of



find the 


QR decomposition 


LU decomposition (note: P(MATLAB) == transpose(P(NumPy))) 


Conjugate gradients solver 


Fourier transform of 


inverse Fourier transform of 


sort each column of a 2D array, 


sort the each row of 2D array, 


save the array 


perform a linear regression of the form \(\mathbf{Zx}=\mathbf{y}\) 


downsample with lowpass filtering 


a vector of unique values in array 


remove singleton dimensions of array 
Notes#
Submatrix: Assignment to a submatrix can be done with lists of
indices 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 numpy.source
will usually list the filename
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 flamewars arise because each has advantages and disadvantages. One based indexing is consistent with common human language usage, where the “first” element of a sequence has index 1. Zero based indexing simplifies indexing. See also a text by prof.dr. Edsger W. Dijkstra.
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 two can appear to work the same,
but there are important differences. If you would have used MATLAB’s &
or 
operators, you should use the NumPy ufuncs
logical_and
/logical_or
. The notable differences between MATLAB’s and
NumPy’s &
and 
operators are:
Nonlogical {0,1} inputs: NumPy’s output is the bitwise AND of the inputs. MATLAB treats any nonzero value as 1 and returns the logical AND. For example
(3 & 4)
in NumPy is0
, while in MATLAB both3
and4
are considered logical true and(3 & 4)
returns1
.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 multidimensional
arrays to be accessed using scalar or linear indices, NumPy does not.
Linear indices are common in MATLAB programs, e.g. find()
on a matrix
returns them, whereas NumPy’s find behaves differently. When converting
MATLAB code it might be necessary to first 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 efficiently. 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.
‘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 support multidimensional array algebra that is supported in MATLAB
They are the standard vector/matrix/tensor type of NumPy. Many NumPy functions return arrays, not matrices.
There is a clear distinction between elementwise 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 generalpurpose ndimensional array
for many kinds of numerical computing, while matrix
is intended to
facilitate linear algebra computations specifically. In practice there
are only a handful of key differences between the two.
Operators
*
and@
, functionsdot()
, andmultiply()
:For
array
, ``*`` means elementwise multiplication, while ``@`` means matrix multiplication; they have associated functionsmultiply()
anddot()
. (Before Python 3.5,@
did not exist and one had to usedot()
for matrix multiplication).For
matrix
, ``*`` means matrix multiplication, and for elementwise multiplication one has to use themultiply()
function.
Handling of vectors (onedimensional arrays)
For
array
, the vector shapes 1xN, Nx1, and N are all different things. Operations likeA[:,1]
return a onedimensional array of shape N, not a twodimensional array of shape Nx1. Transpose on a onedimensionalarray
does nothing.For
matrix
, onedimensional arrays are always upconverted to 1xN or Nx1 matrices (row or column vectors).A[:,1]
returns a twodimensional matrix of shape Nx1.
Handling of higherdimensional 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, andasarray()
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 inmatrix("[1 2 3; 4 5 6]")
.
There are pros and cons to using both:
array
:)
Elementwise multiplication is easy:A*B
.:(
You have to remember that matrix multiplication has its own operator,@
.:)
You can treat onedimensional arrays as either row or column vectors.A @ v
treatsv
as a column vector, whilev @ A
treatsv
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 elementwise.:(
Sparse matrices fromscipy.sparse
do not interact as well with arrays.
matrix
:\\
Behavior is more like that of MATLAB matrices.<:(
Maximum of twodimensional. To hold threedimensional data you needarray
or perhaps a Python list ofmatrix
.<:(
Minimum of twodimensional. You cannot have vectors. They must be cast as singlecolumn or singlerow matrices.<:(
Sincearray
is the default in NumPy, some functions may return anarray
even if you give them amatrix
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).<:(
Elementwise multiplication requires calling a function,multiply(A,B)
.<:(
The use of operator overloading is a bit illogical:*
does not work elementwise 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.
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, define the
PYTHONPATH
environment variable.To have a particular script file executed when the interactive Python interpreter is started, define 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 first do an ‘import’ statement to make functions in a particular file 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 the SciPy linear algebra functions available as linalg.func()
# e.g. linalg.lu, linalg.eig (for general l*[email protected][email protected] solution)
from scipy import linalg
#
# Define a Hermitian function
def hermitian(A, **kwargs):
return np.conj(A,**kwargs).T
# Make a shortcut for hermitian:
# hermitian(A) > H(A)
H = hermitian
To use the deprecated matrix and other matlib functions:
# 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 matrix,rand,zeros,ones,empty,eye
Links#
Another somewhat outdated MATLAB/NumPy crossreference can be found at http://mathesaurus.sf.net/
An extensive list of tools for scientific work with Python can be found in the topical software page.
See List of Python software: scripting for a list of software that use Python as a scripting language
MATLAB® and SimuLink® are registered trademarks of The MathWorks, Inc.