NumPy

https://numpy.org/doc/stable
Admin
NumPy is the fundamental package for scientific computing in Python, providing support for large,...
Tokens:2,378,701
Snippets:17,611
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Setup arrays for einsum examples

Source: https://numpy.org/doc/stable/reference/generated/numpy.einsum.html

Creates example arrays a, b, and c used in the subsequent einsum examples.

```python
>>> a = np.arange(25).reshape(5,5)
>>> b = np.arange(5)
>>> c = np.arange(6).reshape(2,3)
```

--------------------------------

### Setup for savez examples

Source: https://numpy.org/doc/stable/reference/generated/numpy.savez.html

Sets up the arrays and a temporary file used in the savez examples.

```python
>>> import numpy as np
>>> from tempfile import TemporaryFile
>>> outfile = TemporaryFile()
>>> x = np.arange(10)
>>> y = np.sin(x)

```

--------------------------------

### Example: Using numpy.matrix.A

Source: https://numpy.org/doc/stable/reference/generated/numpy.matrix.A.html

Shows how to create a matrix and use the .A property to get it as an ndarray. The example is from the documentation's Examples section.

```python
>>> x = np.matrix(np.arange(12).reshape((3,4))); x
matrix([[ 0,  1,  2,  3],
        [ 4,  5,  6,  7],
        [ 8,  9, 10, 11]])
>>> x.getA()
array([[ 0,  1,  2,  3],
       [ 4,  5,  6,  7],
       [ 8,  9, 10, 11]])
```

--------------------------------

### Create structured array for view examples

Source: https://numpy.org/doc/stable/reference/generated/numpy.char.chararray.view.html

Initializes a structured array with int8 fields 'a' and 'b', used as the starting point for the subsequent view examples.

```python
>>> import numpy as np
>>> x = np.array([(-1, 2)], dtype=[('a', np.int8), ('b', np.int8)])
```

--------------------------------

### Negative slicing with start and stop

Source: https://numpy.org/doc/stable/reference/generated/numpy.strings.slice.html

Slices from the start index to the end when stop is None, using negative start. The example uses np.strings.slice(b, -2, None) to get the last two characters.

```python
>>> np.strings.slice(b, -2, None)
array(['ld', 'με', '世界', ' 🌍'], dtype=StringDType())
```

--------------------------------

### Slicing with start and stop

Source: https://numpy.org/doc/stable/reference/generated/numpy.strings.slice.html

Slices from the start index to the end when stop is None. The example uses np.strings.slice(a, 2, None) to get the substring from index 2 onward.

```python
>>> np.strings.slice(a, 2, None)
array(['llo', 'rld'], dtype='<U5')
```

--------------------------------

### Aggregate setup.py with Extension for setuptools migration

Source: https://numpy.org/doc/stable/reference/distutils_status_migration.html

Example of aggregating nested setup.py files into a single setup.py using Extension instead of Configuration, as part of migrating from numpy.distutils to setuptools.

```python
from distutils.core import setup
from distutils.extension import Extension
setup(name='foobar',
      version='1.0',
      ext_modules=[
          Extension('foopkg.foo', ['foo.c']),
          Extension('barpkg.bar', ['bar.c']),
          ],
      )

```

--------------------------------

### Basic slicing with start

Source: https://numpy.org/doc/stable/reference/generated/numpy.strings.slice.html

Slices each string from the start index to the end. The example uses a = np.array(['hello', 'world']) and np.strings.slice(a, 2) to get the first two characters.

```python
>>> import numpy as np
>>> a = np.array(['hello', 'world'])
>>> np.strings.slice(a, 2)
array(['he', 'wo'], dtype='<U5')
```

--------------------------------

### Original ZADD subroutine in fixed-form Fortran

Source: https://numpy.org/doc/stable/f2py/advanced/boilerplating.html

Original Fortran subroutine ZADD from the F2PY user guide example, which adds two double complex arrays element-wise. This is the starting point for the boilerplate reduction example.

```fortran
C
      SUBROUTINE ZADD(A,B,C,N)
C
      DOUBLE COMPLEX A(*)
      DOUBLE COMPLEX B(*)
      DOUBLE COMPLEX C(*)
      INTEGER N
      DO 20 J = 1, N
         C(J) = A(J)+B(J)
 20   CONTINUE
      END

```

--------------------------------

### Install the build

Source: https://numpy.org/doc/stable/building/understanding_meson.html

Install the compiled files into the target directory defined during the configuration stage.

```bash
meson install -C build
```

--------------------------------

### Slicing with start, stop, and step

Source: https://numpy.org/doc/stable/reference/generated/numpy.strings.slice.html

Slices with a step of 2. The example uses np.strings.slice(a, 1, 5, 2) to get characters at indices 1 and 3.

```python
>>> np.strings.slice(a, 1, 5, 2)
array(['el', 'ol'], dtype='<U5')
```

--------------------------------

### Old workflow: build wheel and install

Source: https://numpy.org/doc/stable/building/distutils_equivalents.html

Builds a wheel in the current environment and installs it with pip.

```bash
python setup.py bdist_wheel
```

```bash
pip install dist/numpy*.whl
```

--------------------------------

### setup.py using skbuild.setup for a minimal package

Source: https://numpy.org/doc/stable/f2py/buildtools/skbuild.html

Defines a minimal package named 'fibby' with a Fortran extension. Requires scikit-build and is used with a pyproject.toml to build the extension via cmake.

```python
from skbuild import setup

setup(
    name="fibby",
    version="0.0.1",
    description="a minimal example package (fortran version)",
    license="MIT",
    packages=['fibby'],
    python_requires=">=3.7",
)

```

--------------------------------

### Configure the build

Source: https://numpy.org/doc/stable/building/understanding_meson.html

Run the configure stage to set up the build directory and define the installation prefix.

```bash
meson setup build --prefix=$PWD/build-install
```

--------------------------------

### Basic arange examples

Source: https://numpy.org/doc/stable/reference/generated/numpy.arange.html

Basic usage examples of numpy.arange with one, two, and three arguments. Shows that arange(stop) generates values in [0, stop), arange(start, stop) in [start, stop), and arange(start, stop, step) with given spacing.

```python
>>> import numpy as np
>>> np.arange(3)
array([0, 1, 2])
>>> np.arange(3.0)
array([ 0.,  1.,  2.])
>>> np.arange(3,7)
array([3, 4, 5, 6])
>>> np.arange(3,7,2)
array([3, 5])
```

--------------------------------

### setup.py for npufunc module

Source: https://numpy.org/doc/stable/user/c-info.ufunc-tutorial.html

Setuptools build script that compiles the C source into the npufunc extension module. It includes the numpy headers and defines the extension module.

```python
from setuptools import setup, Extension
from numpy import get_include

npufunc = Extension('npufunc',
                    sources=['single_type_logit.c'],
                    include_dirs=[get_include()])

setup(name='npufunc', version='1.0', ext_modules=[npufunc])

```

--------------------------------

### Install Airspeed Velocity and virtualenv

Source: https://numpy.org/doc/stable/benchmarking.html

Install the required tools for benchmarking: asv and virtualenv. This is a prerequisite before running benchmarks.

```bash
pip install asv
pip install virtualenv

```

--------------------------------

### setuptools build configuration for spam extension

Source: https://numpy.org/doc/stable/user/c-info.ufunc-tutorial.html

Build configuration files for the spam extension using setuptools. Includes pyproject.toml and setup.py to compile the C source into a Python extension module.

```text
[project]
name = "spam"
version = "0.1"

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

```

```python
from setuptools import setup, Extension

spammodule = Extension('spam', sources=['spammodule.c'])

setup(name='spam', version='1.0',
      ext_modules=[spammodule])

```

--------------------------------

### Install scipy-doctest

Source: https://numpy.org/doc/stable/reference/testing.html

Install scipy-doctest to check that NumPy documentation code examples (doctests) are correct.

```bash
$ pip install scipy-doctest

```

--------------------------------

### numpy.logspace with base=2

Source: https://numpy.org/doc/stable/user/how-to-partition.html

In linear space, the sequence starts at base ** start and ends with base ** stop. This example uses base=2.

```python
>>> np.logspace(2, 3, num=5, base=2)
array([4.        , 4.75682846, 5.65685425, 6.72717132, 8.        ])

```

--------------------------------

### Build and test the extension in-place

Source: https://numpy.org/doc/stable/f2py/buildtools/skbuild.html

Shows the commands to build the extension in-place and run a quick test. The output shows the expected Fibonacci sequence printed by the module.

```bash
ls .
# CMakeLists.txt fib1.f pyproject.toml setup.py
python setup.py build_ext --inplace
python -c "import numpy as np; import fibby.fibby; a = np.zeros(9); fibby.fibby.fib(a); print (a)"
# [ 0.  1.  1.  2.  3.  5.  8. 13.  21.]

```

--------------------------------

### New workflow: build wheel and install

Source: https://numpy.org/doc/stable/building/distutils_equivalents.html

Builds a wheel without isolation using pypa/build and installs it with pip.

```bash
python -m build --no-isolation
```

```bash
pip install dist/numpy*.whl
```

--------------------------------

### numpy.rollaxis example

Source: https://numpy.org/doc/stable/reference/generated/numpy.rollaxis.html

Interactive example showing how numpy.rollaxis changes the shape of a 4D array when rolling different axes to different start positions.

```python
>>> import numpy as np
>>> a = np.ones((3,4,5,6))
>>> np.rollaxis(a, 3, 1).shape
(3, 6, 4, 5)
>>> np.rollaxis(a, 2).shape
(5, 3, 4, 6)
>>> np.rollaxis(a, 1, 4).shape
(3, 5, 6, 4)
```

--------------------------------

### setuptools pyproject.toml for npufunc

Source: https://numpy.org/doc/stable/user/c-info.ufunc-tutorial.html

Alternative build configuration using setuptools. Declares the project name, dependencies, and build system requirements.

```toml
[project]
name = "npufunc"
dependencies = ["numpy"]
version = "0.1"

[build-system]
requires = ["setuptools", "numpy"]
build-backend = "setuptools.build_meta"

```

--------------------------------

### Get upper triangular indices with offset

Source: https://numpy.org/doc/stable/reference/generated/numpy.mask_indices.html

Get indices for the upper triangular part starting from the first diagonal right of the main one.

```python
>>> iu1 = np.mask_indices(3, np.triu, 1)

```

--------------------------------

### Example: Get data and mask addresses for a masked array

Source: https://numpy.org/doc/stable/reference/generated/numpy.ma.MaskedArray.ids.html

Shows how to call `ids()` on a masked array to get the addresses of the data and mask. The output addresses are illustrative and will vary.

```python
>>> import numpy as np
>>> x = np.ma.array([1, 2, 3], mask=[0, 1, 1])
>>> x.ids()
(166670640, 166659832) # may vary
```

--------------------------------

### Build and run fibby example

Source: https://numpy.org/doc/stable/f2py/buildtools/meson.html

Commands to compile and run the fibby example. The output shows the Fibonacci sequence printed as expected.

```bash
rm -rf builddir
meson setup builddir
meson compile -C builddir
cd builddir
python -c "import numpy as np; import fibby; a = np.zeros(9); fibby.fib(a); print (a)"
# [ 0.  1.  1.  2.  3.  5.  8. 13. 21.]

```

--------------------------------

### Example: Using numpy.flatnonzero

Source: https://numpy.org/doc/stable/reference/generated/numpy.flatnonzero.html

Shows how to use numpy.flatnonzero to get indices of non-zero elements in a flattened array. The example creates an array with np.arange(-2, 3) and prints the result.

```python
>>> import numpy as np
>>> x = np.arange(-2, 3)
>>> x
array([-2, -1,  0,  1,  2])
>>> np.flatnonzero(x)
array([0, 1, 3, 4])
```

--------------------------------

### Use np.get_include() in setuptools Extension

Source: https://numpy.org/doc/stable/reference/generated/numpy.get_include.html

Use this in setup.py with setuptools to add the NumPy include directory to the Extension's include_dirs. The ellipses (...) are placeholders for the rest of the setup code.

```python
import numpy as np
...
Extension('extension_name', ...
          include_dirs=[np.get_include()])
...

```

--------------------------------

### Run tests with spin after configuration

Source: https://numpy.org/doc/stable/building/compilers_and_options.html

Runs the linalg test suite using the spin interface. Works because Meson remembers the configuration options from the initial setup.

```bash
spin test -s linalg

```

--------------------------------

### Setup for object array tensordot example

Source: https://numpy.org/doc/stable/reference/generated/numpy.linalg.tensordot.html

Sets up an extended example using object arrays to demonstrate overloading of + and * in np.tensordot. Defines a 3D integer array and a 2D object array.

```python
>>> a = np.array(range(1, 9)).reshape((2, 2, 2))
>>> A = np.array(('a', 'b', 'c', 'd'), dtype=np.object_)
>>> A = A.reshape((2, 2))
>>> a; A
array([[[1, 2],
        [3, 4]],
       [[5, 6],
        [7, 8]]])
array([['a', 'b'],
       ['c', 'd']], dtype=object)
```

--------------------------------

### Per-element start and stop

Source: https://numpy.org/doc/stable/reference/generated/numpy.strings.slice.html

Allows different start and stop for each element using arrays. The example uses np.strings.slice(a, np.array([1, 2]), np.array([4, 5])) to slice each string individually.

```python
>>> np.strings.slice(a, np.array([1, 2]), np.array([4, 5]))
array(['ell', 'rld'], dtype='<U5')
```

--------------------------------

### Initialize the development environment

Source: https://numpy.org/doc/stable/building/understanding_meson.html

Clone the repository, initialize submodules, and create the conda environment.

```bash
git clone git@github.com:numpy/numpy.git
git submodule update --init
mamba env create -f environment.yml
mamba activate numpy-dev
```

--------------------------------

### Import Polynomial and create instance

Source: https://numpy.org/doc/stable/reference/routines.polynomials.classes

Import the Polynomial class and create an instance with coefficients [1,2,3]. The long printout shows coefficients, domain, and window.

```python
>>> from numpy.polynomial import Polynomial as P
>>> p = P([1,2,3])
>>> p
Polynomial([1., 2., 3.], domain=[-1.,  1.], window=[-1.,  1.], symbol='x')

```

--------------------------------

### Get include directory with numpy-config and pkg-config

Source: https://numpy.org/doc/stable/reference/generated/numpy.get_include.html

Shows how to get the include directory using the numpy-config CLI tool (introduced in NumPy 2.0) or via pkg-config. The output paths are examples and may vary.

```bash
$ numpy-config --cflags
-I/path/to/site-packages/numpy/_core/include

# Or rely on pkg-config:
$ export PKG_CONFIG_PATH=$(numpy-config --pkgconfigdir)
$ pkg-config --cflags
-I/path/to/site-packages/numpy/_core/include

```

--------------------------------

### Get itemsize of a structured dtype

Source: https://numpy.org/doc/stable/reference/generated/numpy.dtype.itemsize.html

Shows how to get the itemsize of a structured dtype with a string field and a float64 field. The example creates a dtype with a 16-character string and a (2,) float64 field, and prints the itemsize, which is 80.

```python
>>> dt = np.dtype([('name', np.str_, 16), ('grades', np.float64, (2,))])
>>> dt.itemsize
80
```

--------------------------------

### Reduction iteration with reduce_ok and buffering

Source: https://numpy.org/doc/stable/reference/arrays.nditer.html

Demonstrates reduction iteration using the reduce_ok flag and buffering with delay_bufalloc. The example sums along the last axis of a 3D array, initializing the reduction operand to zero before iteration.

```python
>>> import numpy as np


```

```python
>>> a = np.arange(24).reshape(2,3,4)
>>> it = np.nditer([a, None], flags=['reduce_ok',
...                                  'buffered', 'delay_bufalloc'],
...             op_flags=[['readonly'], ['readwrite', 'allocate']],
...             op_axes=[None, [0,1,-1]])
>>> with it:
...     it.operands[1][...] = 0
...     it.reset()
...     for x, y in it:
...         y[...] += x
...     result = it.operands[1]
...
>>> result
array([[ 6, 22, 38],
       [54, 70, 86]])

>>> np.sum(a, axis=2)
array([[ 6, 22, 38],
       [54, 70, 86]])
```

--------------------------------

### Example: Get itemsize for float64 and complex128 arrays

Source: https://numpy.org/doc/stable/reference/generated/numpy.char.chararray.itemsize.html

Shows how to use the itemsize attribute on numpy arrays. The example creates arrays with dtype float64 and complex128, then prints their itemsize values (8 and 16 respectively).

```python
>>> import numpy as np
>>> x = np.array([1,2,3], dtype=np.float64)
>>> x.itemsize
8
>>> x = np.array([1,2,3], dtype=np.complex128)
>>> x.itemsize
16
```

--------------------------------

### Build with cpu-dispatch and cpu-baseline options

Source: https://numpy.org/doc/stable/reference/simd/build-options.html

Shows how to pass CPU feature options to the build using -Dcpu-dispatch and -Dcpu-baseline. The first command sets cpu-dispatch to max-X86_V4, the second sets cpu-baseline to min+X86_V4.

```bash
python -m build --wheel -Csetup-args=-Dcpu-dispatch="max-X86_V4"
python -m build --wheel -Csetup-args=-Dcpu-baseline="min+X86_V4"

```

--------------------------------

### Get total elements with ndarray.size

Source: https://numpy.org/doc/stable/user/absolute_beginners.html

Returns the total number of elements in the array. For the example array, the result is 24.

```python
>>> array_example.size
24

```

--------------------------------

### pkg-config file contents for nonstandard library (e.g., armpl_lp64)

Source: https://numpy.org/doc/stable/building/blas_lapack.html

Create a pkg-config .pc file for a standalone shared library (e.g., armpl_lp64.so) in a nonstandard location. Set PKG_CONFIG_PATH to the directory containing this file. Adjust libdir, includedir, version, and extralib as needed.

```text
libdir=/path/to/library-dir      # e.g., /a/random/path/lib
includedir=/path/to/include-dir  # e.g., /a/random/path/include
version=1.2.3                    # set to actual version
extralib=-lm -lpthread -lgfortran   # if needed, the flags to link in dependencies
Name: armpl_lp64
Description: ArmPL - Arm Performance Libraries
Version: ${version}
Libs: -L${libdir} -larmpl_lp64      # linker flags
Libs.private: ${extralib}
Cflags: -I${includedir}
```

--------------------------------

### Get number of dimensions with ndarray.ndim

Source: https://numpy.org/doc/stable/user/absolute_beginners.html

Returns the number of axes (dimensions) of the array. For the example array, the result is 3.

```python
>>> array_example.ndim
3

```

--------------------------------

### Project layout for f2py Meson example

Source: https://numpy.org/doc/stable/f2py/usage.html

Shows the directory structure for the f2py_examples project. The add.pyf file is optional; f2py can often determine annotations automatically.

```text
f2py_examples/
  meson.build
  add.f
  add.pyf (optional)
  __init__.py  (can be empty)

```

--------------------------------

### numpy.logspace example

Source: https://numpy.org/doc/stable/user/how-to-partition.html

numpy.logspace is similar to numpy.geomspace but with start and end points specified as logarithms (base 10 by default).

```python
>>> np.logspace(2, 3, num=5)
array([ 100.        ,  177.827941  ,  316.22776602,  562.34132519, 1000.        ])

```
Tokens:
Raw