View source for NumPy

{{Short description|Python library for numerical programming}}
{{Infobox software
| title = NumPy
| name = NumPy
| logo = NumPy logo 2020.svg
| logo_size = 200px
| screenshot = NumPy Matplotlib sin x plotted with red dots.svg
| caption = Plot of y=sin(x) function, created with NumPy and [[Matplotlib]] libraries
| collapsible = 
| author = [[Travis Oliphant]]
| developer = Community project
| released = As Numeric, {{Start date|1995}}; as NumPy, {{Start date|2006}}
| discontinued = 
| latest release version = {{wikidata|property|reference|P348}}
| latest release date = {{start date and age|{{wikidata|qualifier|P348|P577}}}}
| latest preview version = 
| latest preview date = 
| programming language = [[Python (programming language)|Python]], [[C (programming language)|C]]
| operating system = [[Cross-platform]]
| platform = 
| size = 
| language = 
| genre = [[Numerical analysis]]
| license = [[BSD licenses|BSD]]<ref name="numpy_org">{{cite web |title=NumPy — NumPy |url=https://numpy.org/ |website=numpy.org |publisher=NumPy developers}}</ref>
}}
'''NumPy''' (pronounced {{IPAc-en|ˈ|n|ʌ|m|p|aɪ}} {{respell|NUM|py}}) is a [[Library (computing)|library]] for the [[Python (programming language)|Python programming language]], adding support for large, multi-dimensional [[Array data structure|arrays]] and [[matrix (mathematics)|matrices]], along with a large collection of [[High-level programming language|high-level]] [[mathematics|mathematical]] [[function (mathematics)|functions]] to operate on these arrays.<ref name="Nature">{{cite Q|Q99413970|display-authors=3}}</ref> The predecessor of NumPy, Numeric, was originally created by [[Jim Hugunin]] with contributions from several other developers. In 2005, [[Travis Oliphant]] created NumPy by incorporating features of the competing Numarray into Numeric, with extensive modifications. NumPy is [[open-source software]] and has many contributors. NumPy is fiscally sponsored by [[NumFOCUS]].<ref>{{cite web|title=NumFOCUS Sponsored Projects|url=https://numfocus.org/sponsored-projects|publisher=NumFOCUS|access-date=2021-10-25}}</ref>

== History ==
===matrix-sig===
The Python programming language was not originally designed for numerical computing, but attracted the attention of the scientific and engineering community early on. In 1995 the [[special interest group]] (SIG) ''matrix-sig'' was founded with the aim of defining an [[Array data type|array]] computing package; among its members was Python designer and maintainer [[Guido van Rossum]], who extended [[Python syntax and semantics|Python's syntax]] (in particular the indexing syntax<ref>{{Cite web|title=Indexing — NumPy v1.20 Manual|url=https://numpy.org/doc/stable/reference/arrays.indexing.html|access-date=2021-04-06|website=numpy.org}}</ref>) to make [[array programming|array computing]] easier.<ref name="millman"/>

===Numeric===
An implementation of a matrix package was completed by Jim Fulton, then generalized{{explain|From what to what?|date=April 2020}} by Jim Hugunin and called ''Numeric''<ref name="millman">{{cite journal
  |first1=K. Jarrod
  |last1=Millman
  |first2=Michael
  |last2=Aivazis
  |title=Python for Scientists and Engineers
  |journal=Computing in Science and Engineering
  |volume=13
  |number=2
  |pages=9–12
  |year=2011
  |doi=10.1109/MCSE.2011.36
 |bibcode=2011CSE....13b...9M
 |url=http://www.computer.org/csdl/mags/cs/2011/02/mcs2011020009.html
  |access-date=2014-07-07
  |archive-date=2019-02-19
  |archive-url=https://web.archive.org/web/20190219031439/https://www.computer.org/csdl/mags/cs/2011/02/mcs2011020009.html
  |url-status=dead
  }}</ref> (also variously known as the "Numerical Python extensions" or "NumPy"), with influences from the [[APL (programming language)|APL]] family of languages, Basis, [[MATLAB]], [[FORTRAN]], [[S (programming language)|S]] and [[S-PLUS|S+]], and others.<ref name="cise2">{{cite journal |author=Travis Oliphant |title=Python for Scientific Computing |journal=Computing in Science and Engineering |year=2007 |url=http://www.vision.ime.usp.br/~thsant/pool/oliphant-python_scientific.pdf |access-date=2013-10-12 |archive-url=https://web.archive.org/web/20131014035918/http://www.vision.ime.usp.br/~thsant/pool/oliphant-python_scientific.pdf |archive-date=2013-10-14 |url-status=dead }}</ref><ref name="numerical">{{cite web |author1=David Ascher |author2=Paul F. Dubois |author3=Konrad Hinsen |author4=Jim Hugunin |author5=Travis Oliphant |title=Numerical Python |url=http://www.cs.mcgill.ca/~hv/articles/Numerical/numpy.pdf |year=1999}}</ref>
Hugunin, a graduate student at the [[Massachusetts Institute of Technology]] (MIT),<ref name="numerical"/>{{rp|10}} joined the [[Corporation for National Research Initiatives]] (CNRI) in 1997 to work on [[Jython|JPython]],<ref name="millman"/> leaving Paul Dubois of [[Lawrence Livermore National Laboratory]] (LLNL) to take over as maintainer.<ref name="numerical"/>{{rp|10}} Other early contributors include David Ascher, Konrad Hinsen and [[Travis Oliphant]].<ref name="numerical"/>{{rp|10}}

===Numarray===
A new package called ''Numarray'' was written as a more flexible replacement for Numeric.<ref name="cise"/><!--for sure not "cise2"? --> Like Numeric, it too is now deprecated.<ref>{{cite web| title = Numarray Homepage | url = http://www.stsci.edu/resources/software_hardware/numarray | access-date = 2006-06-24}}</ref><ref name="NumPyBook">{{cite book
  | title = Guide to NumPy
  | author = Travis E. Oliphant
  | date = 7 December 2006
  | url = https://archive.org/details/NumPyBook
  | access-date = 2 February 2017
}}</ref> Numarray had faster operations for large arrays, but was slower than Numeric on small ones,<ref>{{cite web| title = <nowiki>[Numpy-discussion]</nowiki> Status of Numeric
  | author = Travis Oliphant and other SciPy developers
  | url = https://mail.scipy.org/pipermail/numpy-discussion/2004-January/002645.html
  | access-date = 2 February 2017
}}</ref> so for a time both packages were used in parallel for different use cases. The last version of Numeric (v24.2) was released on 11 November 2005, while the last version of numarray (v1.5.2) was released on 24 August 2006.<ref>{{cite web| title = NumPy Sourceforge Files | url = http://sourceforge.net/project/showfiles.php?group_id=1369 | access-date = 2008-03-24}}</ref>

There was a desire to get Numeric into the Python standard library, but Guido van Rossum decided that the code was not maintainable in its state then.{{when|date=October 2013}}<ref>{{cite web|url=https://scipy.github.io/old-wiki/pages/History_of_SciPy.html|title=History_of_SciPy - SciPy wiki dump|website=scipy.github.io}}</ref>

===NumPy===
In early 2005, NumPy developer Travis Oliphant wanted to unify the community around a single array package and ported Numarray's features to Numeric, releasing the result as NumPy 1.0 in 2006.<ref name="cise"/><!--for sure not "cise2"? --> This new project was part of [[SciPy]]. To avoid installing the large SciPy package just to get an array object, this new package was separated and called NumPy. Support for Python 3 was added in 2011 with NumPy version 1.5.0.<ref>{{cite web| title = NumPy 1.5.0 Release Notes | url = http://sourceforge.net/projects/numpy/files//NumPy/1.5.0/NOTES.txt/view | access-date = 2011-04-29 }}</ref>

In 2011, [[PyPy]] started development on an implementation of the NumPy API for PyPy.<ref>{{cite web| title=PyPy Status Blog: NumPy funding and status update | url = http://morepypy.blogspot.com/2011/10/numpy-funding-and-status-update.html | access-date = 2011-12-22 }}</ref> As of 2023, it is not yet fully compatible with NumPy.<ref>{{cite web| title=NumPyPy Status | url = http://buildbot.pypy.org/numpy-status/latest.html | access-date = 2023-12-19 }}</ref>

== Features ==
NumPy targets the [[CPython]] [[reference implementation]] of Python, which is a non-optimizing [[bytecode]] [[Interpreter (computing)|interpreter]]. [[List of algorithms#Computational mathematics|Mathematical algorithms]] written for this version of Python often run much slower than [[Compiler|compiled]] equivalents due to the absence of compiler optimization. NumPy addresses the slowness problem partly by providing multidimensional arrays and functions and operators that operate efficiently on arrays; using these requires rewriting some code, mostly [[inner loop]]s, using NumPy.

Using NumPy in Python gives functionality comparable to [[MATLAB]] since they are both interpreted,<ref>{{cite web
  | title = NumPy for Matlab users
  | author = The SciPy Community
  | url = https://docs.scipy.org/doc/numpy-dev/user/numpy-for-matlab-users.html
  | access-date = 2 February 2017
}}</ref> and they both allow the user to write fast programs as long as most operations work on [[Array|arrays]] or matrices instead of [[scalar (computing)|scalars]]. In comparison, MATLAB boasts a large number of additional toolboxes, notably [[Simulink]], whereas NumPy is intrinsically integrated with Python, a more modern and complete [[programming language]]. Moreover, complementary Python packages are available; SciPy is a library that adds more MATLAB-like functionality and [[Matplotlib]] is a [[Plot (graphics)|plotting]] package that provides MATLAB-like plotting functionality. Although matlab can perform sparse matrix operations, numpy alone cannot perform such operations and requires the use of the scipy.sparse library. Internally, both MATLAB and NumPy rely on [[Basic Linear Algebra Subprograms|BLAS]] and [[LAPACK]] for efficient [[linear algebra]] computations.

Python [[Language binding|bindings]] of the widely used [[computer vision]] library [[OpenCV]] utilize NumPy arrays to store and operate on data.
Since images with multiple channels are simply represented as three-dimensional arrays, indexing, [[Array slicing#1991: Python|slicing]] or [[Mask (computing)#Image masks|masking]] with other arrays are very efficient ways to access specific pixels of an image.
The NumPy array as universal data structure in OpenCV for images, extracted [[Interest point detection|feature points]], [[Kernel (image processing)|filter kernels]] and many more vastly simplifies the programming workflow and [[Debugger|debugging]].{{cn|date=December 2023}}

Importantly, many NumPy operations release the [[global interpreter lock]], which allows for multithreaded processing.<ref>{{Cite web |title=numpy release notes |url=https://numpy.org/doc/stable/release/1.9.0-notes.html}}</ref>

NumPy also provides a C API, which allows Python code to interoperate with external libraries written in low-level languages.<ref>{{cite book |last1=McKinney |first1=Wes |title=Python for Data Analysis |date=2014 |publisher=O'Reilly |isbn=978-1-449-31979-3 |page=79 |edition=First Edition, Third release |chapter=NumPy Basics: Arrays and Vectorized Computation}}</ref> 

=== The ndarray data structure ===
The core functionality of NumPy is its "ndarray", for ''n''-dimensional array, [[data structure]]. These arrays are [[Stride of an array|strided]] views on memory.<ref name="cise">{{cite journal |title=The NumPy array: a structure for efficient numerical computation |first1=Stéfan |last1=van der Walt |first2=S. Chris |last2=Colbert |first3=Gaël |last3=Varoquaux |year=2011 |journal=Computing in Science and Engineering |volume=13 |issue=2 |page=22 |publisher=IEEE |doi=10.1109/MCSE.2011.37 |arxiv=1102.1523|bibcode=2011CSE....13b..22V |s2cid=16907816 }}</ref> In contrast to Python's built-in list data structure, these arrays are homogeneously typed: all elements of a single array must be of the same type.

Such arrays can also be views into memory buffers allocated by [[C (programming language)|C]]/[[C++]], [[Python (programming language)|Python]], and [[Fortran]] extensions to the CPython interpreter without the need to copy data around, giving a degree of compatibility with existing numerical libraries. This functionality is exploited by the SciPy package, which wraps a number of such libraries (notably BLAS and LAPACK). NumPy has built-in support for [[memory-mapped file|memory-mapped]] ndarrays.<ref name="cise"/>

===Limitations===
Inserting or appending entries to an array is not as trivially possible as it is with Python's lists.
The {{code|np.pad(...)}} routine to extend arrays actually creates new arrays of the desired shape and padding values, copies the given array into the new one and returns it.
NumPy's {{code|np.concatenate([a1,a2])}} operation does not actually link the two arrays but returns a new one, filled with the entries from both given arrays in sequence.
Reshaping the dimensionality of an array with {{code|np.reshape(...)}} is only possible as long as the number of elements in the array does not change.
These circumstances originate from the fact that NumPy's arrays must be views on contiguous [[Data buffer|memory buffers]].

[[Algorithm|Algorithms]] that are not expressible as a vectorized operation will typically run slowly because they must be implemented in "pure Python", while vectorization may increase [[Space complexity|memory complexity]] of some operations from constant to linear, because temporary arrays must be created that are as large as the inputs. Runtime compilation of numerical code has been implemented by several groups to avoid these problems; open source solutions that interoperate with NumPy include numexpr<ref>{{cite web |title=numexpr |url=https://github.com/pydata/numexpr |author=Francesc Alted |website=[[GitHub]] |access-date=8 March 2014}}</ref> and [[Numba]].<ref>{{cite web |title=Numba |url=http://numba.pydata.org/ |access-date=8 March 2014}}</ref> Cython and [[Pythran]] are static-compiling alternatives to these.

Many modern [[Big data|large-scale]] scientific computing applications have requirements that exceed the capabilities of the NumPy arrays.
For example, NumPy arrays are usually loaded into a computer's [[Volatile memory|memory]], which might have insufficient capacity for the analysis of large [[Data set|datasets]].
Further, NumPy operations are executed on a single [[Central processing unit|CPU]].
However, many linear algebra operations can be accelerated by executing them on [[Computer cluster|clusters]] of CPUs or of specialized hardware, such as [[Graphics processing unit|GPUs]] and [[Tensor Processing Unit|TPUs]], which many [[deep learning]] applications rely on.
As a result, several alternative array implementations have arisen in the scientific python ecosystem over the recent years, such as [[Dask (software)|Dask]] for distributed arrays and [[TensorFlow]] or [[Google JAX|JAX]]<ref> Documentationː {{URL|https://jax.readthedocs.io/}} </ref> for computations on GPUs.
Because of its popularity, these often implement a [[subset]] of NumPy's [[API]] or mimic it, so that users can change their array implementation with minimal changes to their code required.<ref name="Nature" /> A library named [[CuPy]],<ref>{{Citation|title=Shohei Hido - CuPy: A NumPy-compatible Library for GPU - PyCon 2018|url=https://www.youtube.com/watch?v=MAz1xolSB68 |archive-url=https://ghostarchive.org/varchive/youtube/20211221/MAz1xolSB68 |archive-date=2021-12-21 |url-status=live|language=en|access-date=2021-05-11}}{{cbignore}}</ref> accelerated by [[Nvidia]]'s [[CUDA]] framework, has also shown potential for faster computing, being a '[[drop-in replacement]]' of NumPy.<ref>{{Cite web|last=Entschev|first=Peter Andreas|date=2019-07-23|title=Single-GPU CuPy Speedups|url=https://medium.com/rapids-ai/single-gpu-cupy-speedups-ea99cbbb0cbb|access-date=2021-05-11|website=Medium|language=en}}</ref>

== Examples ==
<syntaxhighlight lang="numpy">
import numpy as np
from numpy.random import rand
from numpy.linalg import solve, inv
a = np.array([[1, 2, 3, 4], [3, 4, 6, 7], [5, 9, 0, 5]])
a.transpose()
</syntaxhighlight>

=== Basic operations ===
<syntaxhighlight lang="numpy">
>>> a = np.array([1, 2, 3, 6])
>>> b = np.linspace(0, 2, 4)  # create an array with four equally spaced points starting with 0 and ending with 2.
>>> c = a - b
>>> c
array([ 1.        ,  1.33333333,  1.66666667,  4.        ])
>>> a**2
array([ 1,  4,  9, 36])
</syntaxhighlight>

=== Universal functions ===
<syntaxhighlight lang="numpy">
>>> a = np.linspace(-np.pi, np.pi, 100) 
>>> b = np.sin(a)
>>> c = np.cos(a)
>>>
>>> # Functions can take both numbers and arrays as parameters.
>>> np.sin(1)
0.8414709848078965
>>> np.sin(np.array([1, 2, 3]))
array([0.84147098, 0.90929743, 0.14112001])
</syntaxhighlight>

=== Linear algebra ===
<syntaxhighlight lang="numpy">
>>> from numpy.random import rand
>>> from numpy.linalg import solve, inv
>>> a = np.array([[1, 2, 3], [3, 4, 6.7], [5, 9.0, 5]])
>>> a.transpose()
array([[ 1. ,  3. ,  5. ],
       [ 2. ,  4. ,  9. ],
       [ 3. ,  6.7,  5. ]])
>>> inv(a)
array([[-2.27683616,  0.96045198,  0.07909605],
       [ 1.04519774, -0.56497175,  0.1299435 ],
       [ 0.39548023,  0.05649718, -0.11299435]])
>>> b =  np.array([3, 2, 1])
>>> solve(a, b)  # solve the equation ax = b
array([-4.83050847,  2.13559322,  1.18644068])
>>> c = rand(3, 3) * 20  # create a 3x3 random matrix of values within [0,1] scaled by 20
>>> c
array([[  3.98732789,   2.47702609,   4.71167924],
       [  9.24410671,   5.5240412 ,  10.6468792 ],
       [ 10.38136661,   8.44968437,  15.17639591]])
>>> np.dot(a, c)  # matrix multiplication
array([[  53.61964114,   38.8741616 ,   71.53462537],
       [ 118.4935668 ,   86.14012835,  158.40440712],
       [ 155.04043289,  104.3499231 ,  195.26228855]])
>>> a @ c # Starting with Python 3.5 and NumPy 1.10
array([[  53.61964114,   38.8741616 ,   71.53462537],
       [ 118.4935668 ,   86.14012835,  158.40440712],
       [ 155.04043289,  104.3499231 ,  195.26228855]])
</syntaxhighlight>

===   Multidimensional arrays  ===
<syntaxhighlight lang="numpy">
>>> M = np.zeros(shape=(2, 3, 5, 7, 11))
>>> T = np.transpose(M, (4, 2, 1, 3, 0))
>>> T.shape
(11, 5, 3, 7, 2)
</syntaxhighlight>

=== Incorporation with OpenCV ===
<syntaxhighlight lang="numpy">
>>> import numpy as np
>>> import cv2
>>> r = np.reshape(np.arange(256*256)%256,(256,256))  # 256x256 pixel array with a horizontal gradient from 0 to 255 for the red color channel
>>> g = np.zeros_like(r)  # array of same size and type as r but filled with 0s for the green color channel
>>> b = r.T  # transposed r will give a vertical gradient for the blue color channel
>>> cv2.imwrite("gradients.png", np.dstack([b,g,r]))  # OpenCV images are interpreted as BGR, the depth-stacked array will be written to an 8bit RGB PNG-file called "gradients.png"
True
</syntaxhighlight>

=== Nearest-neighbor search ===
Iterative Python algorithm and vectorized NumPy version.

<syntaxhighlight lang="numpy">
>>> # # # Pure iterative Python # # #
>>> points = [[9,2,8],[4,7,2],[3,4,4],[5,6,9],[5,0,7],[8,2,7],[0,3,2],[7,3,0],[6,1,1],[2,9,6]]
>>> qPoint = [4,5,3]
>>> minIdx = -1
>>> minDist = -1
>>> for idx, point in enumerate(points):  # iterate over all points
...     dist = sum([(dp-dq)**2 for dp,dq in zip(point,qPoint)])**0.5  # compute the euclidean distance for each point to q
...     if dist < minDist or minDist < 0:  # if necessary, update minimum distance and index of the corresponding point
...         minDist = dist
...         minIdx = idx

>>> print(f"Nearest point to q: {points[minIdx]}")
Nearest point to q: [3, 4, 4]

>>> # # # Equivalent NumPy vectorization # # #
>>> import numpy as np
>>> points = np.array([[9,2,8],[4,7,2],[3,4,4],[5,6,9],[5,0,7],[8,2,7],[0,3,2],[7,3,0],[6,1,1],[2,9,6]])
>>> qPoint = np.array([4,5,3])
>>> minIdx = np.argmin(np.linalg.norm(points-qPoint, axis=1))  # compute all euclidean distances at once and return the index of the smallest one
>>> print(f"Nearest point to q: {points[minIdx]}")
Nearest point to q: [3 4 4]
</syntaxhighlight>

=== F2PY ===
Quickly wrap native code for faster scripts.<ref>{{cite web |title=F2PY docs from NumPy |url=https://numpy.org/doc/stable/f2py/usage.html?highlight=f2py |publisher=NumPy |access-date=18 April 2022}}</ref><ref>{{cite web |last1=Worthey |first1=Guy |title=A python vs. Fortran smackdown |url=https://guyworthey.net/2022/01/03/a-python-vs-fortran-smackdown/ |website=Guy Worthey |date=3 January 2022 |publisher=Guy Worthey |access-date=18 April 2022}}</ref><ref>{{cite web |last1=Shell |first1=Scott |title=Writing fast Fortran routines for Python |url=https://sites.engineering.ucsb.edu/~shell/che210d/f2py.pdf |website=UCSB Engineering Department |publisher=University of California, Santa Barbara |access-date=18 April 2022}}</ref>

<syntaxhighlight lang="fortran">
! Python Fortran native code call example
! f2py -c -m foo *.f90
! Compile Fortran into python named module using intent statements
! Fortran subroutines only not functions--easier than JNI with C wrapper
! requires gfortran and make
subroutine ftest(a, b, n, c, d)
  implicit none
  integer, intent(in)  :: a, b, n
  integer, intent(out) :: c, d
  integer :: i
  c = 0
  do i = 1, n
    c = a + b + c
  end do
  d = (c * n) * (-1)
end subroutine ftest
</syntaxhighlight>
<syntaxhighlight lang="pycon">
>>> import numpy as np
>>> import foo
>>> a = foo.ftest(1, 2, 3)  # or c,d = instead of a.c and a.d
>>> print(a)
(9,-27)
>>> help("foo.ftest")  # foo.ftest.__doc__
</syntaxhighlight>

== See also ==
* [[Array programming]]
* [[List of numerical-analysis software]]
* [[Theano (software)]]
* [[Matplotlib]]
* [[Fortran]]
*[[Row- and column-major order]]
*[[f2c]]

== References ==
{{Reflist|2}}

== Further reading ==
* {{cite book |first=Wes |last=McKinney |title=Python for Data Analysis |publisher=O'Reilly |year=2022 |edition=3rd |isbn=978-1098104030 |url=https://wesmckinney.com/book/}}
* {{cite book|last=Bressert|first=Eli|title=Scipy and Numpy: An Overview for Developers.|year=2012|publisher=O'Reilly |isbn=978-1-4493-0546-8}}
* {{cite book |first=Jake |last=VanderPlas |chapter=Introduction to NumPy |pages=33–96 |title=Python Data Science Handbook: Essential Tools for Working with Data |publisher=O'Reilly |year=2016 |isbn=978-1-4919-1205-8 }}

== External links ==
{{Sister project links
|commons=Category:NumPy
|b=Python Programming/numpy
|v=Python/Quizzes/NumPy & Co.
|wikt=no|s=no|n=no|q=no}}
* {{official website}}
* [https://numpy.org/numpy-tutorials/ NumPy tutorials]
* [https://scipy.github.io/old-wiki/pages/History_of_SciPy History of NumPy]

{{SciPy ecosystem}}

{{DEFAULTSORT:Numpy}}
[[Category:Array programming languages]]
[[Category:Articles with example Python (programming language) code]]
[[Category:Free mathematics software]]
[[Category:Free science software]]
[[Category:Numerical analysis software for Linux]]
[[Category:Numerical analysis software for macOS]]
[[Category:Numerical analysis software for Windows]]
[[Category:Numerical programming languages]]
[[Category:Python (programming language) scientific libraries]]
[[Category:Software using the BSD license]]