NumPy

https://numpy.org/doc/2.4/
Admin
NumPy is the fundamental package for scientific computing in Python, providing multidimensional...
Tokens:2,574,953
Snippets:18,705
Trust Score:10
Update:8 hours ago
Show doc for...
Tokens:
Raw
### config.add_data_dir examples

Source: https://numpy.org/doc/2.4/reference/distutils_guide.html

Shows how to add entire directories recursively to the package installation. The first example adds a directory under its basename, the second and third use tuples to specify a custom installation suffix. The output shows the resulting installation tree.

```python
config.add_data_dir('fun')  # fun/ contains foo.dat bar/car.dat
config.add_data_dir(('sun','fun'))
config.add_data_dir(('gun','/full/path/to/fun'))
```

```text
<installation path of config.name package>/
  fun/
     foo.dat
     bar/
        car.dat
  sun/
     foo.dat
     bar/
        car.dat
  gun/
     foo.dat
     bar/
        car.dat
```

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

### config.add_data_files example

Source: https://numpy.org/doc/2.4/reference/distutils_guide.html

Shows how to add data files to a package installation. The first argument is a file path, the second is a tuple where the first element is the installation subdirectory suffix and the second is a list of file paths. Files are installed under the package installation directory.

```python
config.add_data_files('foo.dat',
                      ('fun',['gun.dat','nun/pun.dat','/tmp/sun.dat']),
                      'bar/car.dat'.
                      '/full/path/to/can.dat',
                      )
```

```text
<installation path of config.name package>/
  foo.dat
  fun/
    gun.dat
    pun.dat
    sun.dat
  bar/
    car.dat
  can.dat
```

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

### Setup arrays for savez examples

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

Initializes NumPy, a temporary file, and sample arrays x and y used by the subsequent savez examples. This is the first block of the interactive example in the documentation.

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

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

### Specifying config_fc options for libraries in setup.py

Source: https://numpy.org/doc/2.4/reference/distutils_guide.html

Shows how to pass config_fc options when adding a library in a setup.py script. The example disables optimization for the library sources by using {'noopt':(__file__,1)}. Only compiler-independent config_fc options are recommended.

```python
config.add_library('library',
                   sources=[...],
                   config_fc={'noopt':(__file__,1)})

```

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

### Use config.todict() with setup()

Source: https://numpy.org/doc/2.4/reference/distutils.html

Returns a dictionary compatible with the keyword arguments of the distutils setup function. The example shows passing the result directly to setup().

```python
>>> setup(**config.todict())                           
```

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

### Data files installation layout example

Source: https://numpy.org/doc/2.4/reference/distutils.html

Shows the directory layout where data files are installed relative to the package install directory, such as '/usr/lib/python2.4/site-packages/mypackage'.

```text
<package install directory>/
 foo.dat
 fun/
   gun.dat
   nun/
     pun.dat
 sun.dat
 bar/
   car.dat
 can.dat
```

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

### Setup arrays for einsum examples

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

Creates the arrays used in the following einsum examples: a 5x5 matrix, a 1-D array of length 5, and a 2x3 matrix.

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

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

### Import StringIO and numpy for genfromtxt examples

Source: https://numpy.org/doc/2.4/reference/generated/numpy.genfromtxt.html

Initial setup for the genfromtxt examples, importing StringIO from io and numpy.

```python
>>> from io import StringIO
>>> import numpy as np
```

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

### cpuinfo

Source: https://numpy.org/doc/2.4/reference/distutils_guide.html

Provides CPU information. Useful for build configuration.

```APIDOC
## cpuinfo

### Description
Provides CPU information. Useful for build configuration.

### Method
Attribute

### Endpoint
numpy.distutils.cpuinfo.cpuinfo

### Parameters
None

### Response
#### Success Response
- Returns CPU information object.
```

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

### Import numpy and create structured array

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

Initial setup for the examples: imports numpy and creates a structured array x with fields 'a' and 'b' of type int8.

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

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

### Run full test suite

Source: https://numpy.org/doc/2.4/dev/releasing.html

Sanity check before tagging the release.

```bash
$ python3 -m spin test -m full
```

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

### show_all()

Source: https://numpy.org/doc/2.4/reference/distutils_guide.html

Displays all available system information. Useful for debugging build configuration.

```APIDOC
## show_all()

### Description
Displays all available system information. Useful for debugging build configuration.

### Method
Function call

### Endpoint
numpy.distutils.system_info.show_all()

### Parameters
None

### Response
#### Success Response
- Prints all system information to stdout.
```

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

### config.add_data_dir(data_path)

Source: https://numpy.org/doc/2.4/reference/distutils_guide.html

Adds a directory recursively to data_files. The whole directory tree starting at data_path will be copied under the package installation directory.

```APIDOC
## config.add_data_dir(data_path)

### Description
Adds a directory recursively to data_files. The whole directory tree starting at data_path will be copied under the package installation directory.

### Method
add_data_dir

### Parameters
- **data_path** (string or tuple) - Required - Path to the data directory, or a tuple (suffix, path) to specify installation location.

### Example
```
config.add_data_dir('fun')
config.add_data_dir(('sun','fun'))
config.add_data_dir(('gun','/full/path/to/fun'))
```

```

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

### Build command: python setup_example.py build

Source: https://numpy.org/doc/2.4/f2py/buildtools/distutils.html

Builds the two extension modules 'scalar' and 'fib2' into the build directory. This command is run after creating the setup_example.py file.

```bash
python setup_example.py build
```

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

### Create array and check shape

Source: https://numpy.org/doc/2.4/reference/generated/numpy.expand_dims.html

Initializes a 1-D array and prints its shape. This is the starting point for the expand_dims examples that follow.

```python
>>> import numpy as np
>>> x = np.array([1, 2])
>>> x.shape
(2,)
```

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

### Configure Meson build with setup

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

Runs the configure stage, detecting compilers, dependencies, and build options, and creates the build directory and build.ninja file. Places build artifacts in build/ and local install under build-install/.

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

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

### Editable install with setup.py develop

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

Old workflow similar to in-place build but makes the build permanently visible in the environment.

```bash
python setup.py develop
```

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

### Get indices with offset using np.mask_indices(3, np.triu, 1)

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

Passes an offset of 1 to the masking function to get indices starting on the first diagonal right of the main one.

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

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

### config.add_scripts(*files)

Source: https://numpy.org/doc/2.4/reference/distutils_guide.html

Prepends files to the scripts list. Scripts will be installed under <prefix>/bin/ directory.

```APIDOC
## config.add_scripts(*files)

### Description
Prepends files to the scripts list. Scripts will be installed under <prefix>/bin/ directory.

### Method
add_scripts

### Parameters
- **files** (string) - Required - One or more script file paths.

```

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

### Cython setup.py with build_ext and NumPy include

Source: https://numpy.org/doc/2.4/user/c-info.python-as-glue.html

Use this setup.py to build a Cython extension module from a .pyx source. It uses Cython's build_ext class and includes the NumPy include directory, which is necessary only when using NumPy arrays in the extension module.

```python
from Cython.Distutils import build_ext
from distutils.extension import Extension
from distutils.core import setup
import numpy

setup(name='mine', description='Nothing',
      ext_modules=[Extension('filter', ['filter.pyx'],
                             include_dirs=[numpy.get_include()])],
      cmdclass = {'build_ext':build_ext})
```

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

### config.add_headers(*files)

Source: https://numpy.org/doc/2.4/reference/distutils_guide.html

Prepends files to the headers list. By default, headers will be installed under <prefix>/include/pythonX.X/<config.name.replace('.','/')>/ directory.

```APIDOC
## config.add_headers(*files)

### Description
Prepends files to the headers list. By default, headers will be installed under <prefix>/include/pythonX.X/<config.name.replace('.','/')>/ directory.

### Method
add_headers

### Parameters
- **files** (string or tuple) - Required - One or more header file paths or tuples (suffix, path).

```

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

### Migrating from numpy.distutils to setuptools: setup.py with Extension

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

Example of consolidating nested setup.py files into a single setup.py using Extension instead of Configuration, as recommended when moving to setuptools. This is for projects that only use nested setup.py files and can aggregate their content.

```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']),
          ],
      )
```

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

### Get indices of matched values with np.nonzero

Source: https://numpy.org/doc/2.4/reference/generated/numpy.isin.html

After obtaining the boolean mask from np.isin, np.nonzero returns the indices where the mask is True. The output shows the row and column indices of the matched elements.

```python
>>> np.nonzero(mask)
(array([0, 1]), array([1, 0]))
```

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

### config.add_data_files(*files)

Source: https://numpy.org/doc/2.4/reference/distutils_guide.html

Prepends files to the data_files list. Files can be specified as strings or tuples where the first element defines the installation suffix and the second specifies the path to the data files.

```APIDOC
## config.add_data_files(*files)

### Description
Prepends files to the data_files list. Files can be specified as strings or tuples where the first element defines the installation suffix and the second specifies the path to the data files.

### Method
add_data_files

### Parameters
- **files** (string or tuple) - Required - One or more file paths or tuples (suffix, path) to add.

### Example
```
config.add_data_files('foo.dat',
                      ('fun',['gun.dat','nun/pun.dat','/tmp/sun.dat']),
                      'bar/car.dat',
                      '/full/path/to/can.dat')
```

```

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

### Startup script to import NumPy and SciPy linalg

Source: https://numpy.org/doc/2.4/user/numpy-for-matlab-users.html

Example startup script for the interactive Python interpreter, set via the PYTHONSTARTUP environment variable. It imports NumPy with the 'np' prefix, makes SciPy linear algebra functions available as linalg.func(), defines a hermitian() function, and creates a shortcut H. This is an example, not a statement of best practices.

```python
# 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*B@u==A@u 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
```

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

### get_numpy_include_dirs()

Source: https://numpy.org/doc/2.4/reference/distutils_guide.html

Returns a list of NumPy base include directories containing header files such as numpy/arrayobject.h and numpy/funcobject.h. For installed NumPy the list has length 1, but when building NumPy it may contain more directories.

```APIDOC
## get_numpy_include_dirs()

### Description
Returns a list of NumPy base include directories containing header files such as numpy/arrayobject.h and numpy/funcobject.h. For installed NumPy the list has length 1, but when building NumPy it may contain more directories.

### Method
Function call

### Endpoint
numpy.distutils.misc_util.get_numpy_include_dirs()

### Parameters
None

### Response
#### Success Response
- Returns a list of strings representing include directories.
```

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

### setup_example.py: Build scalar and fib2 extensions with numpy.distutils

Source: https://numpy.org/doc/2.4/f2py/buildtools/distutils.html

Defines two Extension modules, 'scalar' from scalar.f and 'fib2' from fib2.pyf plus fib1.f, then calls setup() to build them. The fib2 extension uses an F2PY signature file, so its name must match the module name in the signature file. Run 'python setup_example.py build' to compile both extensions into the build directory.

```python
from numpy.distutils.core import Extension

ext1 = Extension(name='scalar',
                 sources=['scalar.f'])
ext2 = Extension(name='fib2',
                 sources=['fib2.pyf', 'fib1.f'])

if __name__ == "__main__":
    from numpy.distutils.core import setup
    setup(name='f2py_example',
          description="F2PY Users Guide examples",
          author="Pearu Peterson",
          author_email="pearu@cens.ioc.ee",
          ext_modules=[ext1, ext2]
          )
# End of setup_example.py
```

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

### In-place build with setup.py build_ext -i

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

Old workflow to build extensions in-place and set PYTHONPATH to the repo root for development.

```bash
python setup.py build_ext -i
```

```bash
export PYTHONPATH=/home/username/path/to/numpy/reporoot
```

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

### Test fib2.fib in Python

Source: https://numpy.org/doc/2.4/f2py/f2py.getting-started.html

Imports the built module and demonstrates the new Python signature. The docstring shows the wrapper takes n as input and returns an array, and the example call returns the first 8 Fibonacci numbers.

```python
>>> import fib2
>>> print(fib2.fib.__doc__)
a = fib(n)

Wrapper for ``fib``.

Parameters
----------
n : input int

Returns
-------
a : rank-1 array('d') with bounds (n)

>>> print(fib2.fib(8))
[  0.   1.   1.   2.   3.   5.   8.  13.]
```

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

### Setuptools build files for npufunc module

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

Sample pyproject.toml and setup.py for building the npufunc module with setuptools. Uses numpy's get_include() to locate headers and compiles single_type_logit.c into an extension.

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

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

```

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

```

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

### njoin(*path)

Source: https://numpy.org/doc/2.4/reference/distutils_guide.html

Joins pathname components, converts '/' separated paths to os.sep separated paths, and resolves '..' and '.' from paths. Example: njoin('a',['b','./c'],'..','g') -> os.path.join('a','b','g').

```APIDOC
## njoin(*path)

### Description
Joins pathname components, converts '/' separated paths to os.sep separated paths, and resolves '..' and '.' from paths. Example: njoin('a',['b','./c'],'..','g') -> os.path.join('a','b','g').

### Method
Function call

### Endpoint
numpy.distutils.misc_util.njoin(*path)

### Parameters
- **path** (variable arguments) - Required - Path components to join.

### Response
#### Success Response
- Returns the joined and normalized path string.
```

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

### Build wheel with setup.py bdist_wheel

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

Old workflow to build a wheel in the current environment and install it.

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

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

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

### Setuptools build configuration for spam extension (pyproject.toml and setup.py)

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

Sample project files for building the spam extension with setuptools. The pyproject.toml defines the build backend as setuptools.build_meta, and setup.py creates an Extension object for 'spam' from spammodule.c.

```TOML
[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])

```

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

### numpy.char.startswith example

Source: https://numpy.org/doc/2.4/reference/generated/numpy.char.startswith.html

Shows how to use numpy.char.startswith to check which strings in an array start with a given prefix. The example creates an array of strings and tests for the prefix 'fo', then tests for 'o' with start and end positions.

```python
>>> import numpy as np
>>> s = np.array(['foo', 'bar'])
>>> s
array(['foo', 'bar'], dtype='<U3')
>>> np.strings.startswith(s, 'fo')
array([True,  False])
>>> np.strings.startswith(s, 'o', start=1, end=2)
array([True,  False])
```

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

### Import numpy for memmap example

Source: https://numpy.org/doc/2.4/reference/arrays.classes.html

First step of the memory-mapped file example: import numpy.

```python
>>> import numpy as np
```

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

### 2-D diagonal extraction with numpy.diagonal

Source: https://numpy.org/doc/2.4/reference/generated/numpy.diagonal.html

Shows basic diagonal extraction on a 2-D array, including the main diagonal and an offset diagonal. The returned array is a read-only view starting in NumPy 1.9; writing to it raises an error. Use np.diagonal(a).copy() to get a writable copy.

```python
>>> import numpy as np
>>> a = np.arange(4).reshape(2,2)
>>> a
array([[0, 1],
       [2, 3]])
>>> a.diagonal()
array([0, 3])
>>> a.diagonal(1)
array([1])
```

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

### Basic usage of numpy.isin with element and test_elements

Source: https://numpy.org/doc/2.4/reference/generated/numpy.isin.html

Shows how to create an input array, define test values, and use np.isin to get a boolean mask. The mask is then used to index the original array, returning only the matched elements. Outputs are shown for each step.

```python
>>> import numpy as np
>>> element = 2*np.arange(4).reshape((2, 2))
>>> element
array([[0, 2],
       [4, 6]])
>>> test_elements = [1, 2, 4, 8]
>>> mask = np.isin(element, test_elements)
>>> mask
array([[False,  True],
       [ True, False]])
>>> element[mask]
array([2, 4])
```

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

### Test documentation in browser

Source: https://numpy.org/doc/2.4/dev/releasing.html

Opens the built documentation locally to verify links work. The version dropdown will not change because it pulls from numpy.org.

```bash
$ firefox index.html  # or google-chrome, etc.
```

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

### Compile and run fibby example

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

Build the fibby extension and run a Python test that prints the Fibonacci numbers.

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

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

### Get the indices of the diagonal elements

Source: https://numpy.org/doc/2.4/reference/generated/numpy.diag_indices_from.html

Use diag_indices_from to get the indices of the main diagonal of the array.

```python
>>> di = np.diag_indices_from(a)
>>> di
(array([0, 1, 2, 3]), array([0, 1, 2, 3]))
```

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

### Create new release notes skeleton and add to index

Source: https://numpy.org/doc/2.4/dev/releasing.html

Copy the template to create new release notes, edit it with the correct version, and add both the notes file and the index to git.

```bash
$ cp doc/source/release/template.rst doc/source/release/2.4.0-notes.rst
$ gvim doc/source/release/2.4.0-notes.rst  # put the correct version
$ git add doc/source/release/2.4.0-notes.rst
$ gvim doc/source/release.rst  # add new notes to notes index
$ git add doc/source/release.rst
```

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

### Prepare documentation build

Source: https://numpy.org/doc/2.4/dev/releasing.html

Cleans the repository, checks out the release tag, removes the build directory, and merges documentation into doc/build/merge.

```bash
$ git clean -xdfq
$ git co v2.4.0
$ rm -rf doc/build  # want version to be current
$ python -m spin docs merge-doc --build
$ pushd doc/build/merge
```

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

### Getting extra Fortran 77 compiler options from source

Source: https://numpy.org/doc/2.4/reference/distutils_guide.html

Pattern that numpy.distutils Fortran compilers look for in the first 20 lines of a source file to apply per-source compiler flags. The first character 'C' is optional, and f77flags are used for the specified fcompiler type.

```fortran
CF77FLAGS(<fcompiler type>) = <fcompiler f77flags>

```

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

### Create sample arrays a and b for norm examples

Source: https://numpy.org/doc/2.4/reference/generated/numpy.linalg.norm.html

Sets up the 1-D array a and 2-D array b used throughout the norm examples. The output shows the resulting arrays.

```python
>>> import numpy as np
>>> from numpy import linalg as LA
>>> a = np.arange(9) - 4
>>> a
array([-4, -3, -2, ...,  2,  3,  4])
>>> b = a.reshape((3, 3))
>>> b
array([[-4, -3, -2],
       [-1,  0,  1],
       [ 2,  3,  4]])
```

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

### Install Scoop via PowerShell

Source: https://numpy.org/doc/2.4/f2py/windows/conda.html

Downloads and installs Scoop, a package manager for Windows that allows installing tools without administrative access. Run this command in PowerShell.

```powershell
Invoke-Expression (New-Object System.Net.WebClient).DownloadString('https://get.scoop.sh')
```

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

### get_ext_source_files(ext)

Source: https://numpy.org/doc/2.4/reference/distutils_guide.html

Returns source files for an extension. Useful for build configuration.

```APIDOC
## get_ext_source_files(ext)

### Description
Returns source files for an extension. Useful for build configuration.

### Method
Function call

### Endpoint
numpy.distutils.misc_util.get_ext_source_files(ext)

### Parameters
- **ext** (Extension) - Required - The extension object.

### Response
#### Success Response
- Returns a list of source file paths.
```

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

### add_data_dir resulting installation locations

Source: https://numpy.org/doc/2.4/reference/distutils.html

Shows the installation locations for data files after calling add_data_dir with the example arguments.

```text
<package install directory>/
  fun/
    foo.dat
    bar/
      car.dat
  sun/
    foo.dat
    bar/
      car.dat
  gun/
    foo.dat
    car.dat
```
Tokens:
Raw