NumPy: numpy.require() function

Last update on March 24 2023 09:43:17 (UTC/GMT +8 hours)

numpy.require() function

The numpy.require() function returns an ndarray of the provided type that satisfies requirements.

This function is useful when working with libraries that require a specific array type or memory layout. For example, some libraries may require arrays to be in C-contiguous or Fortran-contiguous layout, or require a certain data type.

Syntax:

numpy.require(a, dtype=None, requirements=None)

Parameters:

Name	Description	Required / Optional
a	The object to be converted to a type-and-requirement-satisfying array.	Required
dtype	The required data-type. If None preserve the current dtype. If your application requires the data to be in native byteorder, include a byteorder specification as a part of the dtype specification.	Required
requirements	The requirements list can be any of the following 'F_CONTIGUOUS' ('F') - ensure a Fortran-contiguous array 'C_CONTIGUOUS' ('C') - ensure a C-contiguous array 'ALIGNED' ('A') - ensure a data-type aligned array 'WRITEABLE' ('W') - ensure a writable array 'OWNDATA' ('O') - ensure an array that owns its own data 'ENSUREARRAY', ('E') - ensure a base array, instead of a subclass	Required

Return value:

out : ndarray - Array interpretation of a. No copy is performed if the input is already an ndarray. If a is a subclass of ndarray, a base class ndarray is returned.

Raises: ValueError - Raises ValueError if a contains NaN (Not a Number) or Inf (Infinity).

Example: Checking array flags in NumPy

>>> import numpy as np
>>> a = np.arange(9).reshape(3,3)
>>> a.flags
  C_CONTIGUOUS : True
  F_CONTIGUOUS : False
  OWNDATA : False
  WRITEABLE : True
  ALIGNED : True
  UPDATEIFCOPY : False

The above code creates a 3x3 NumPy array a using the arange function and the reshape method. Then, it checks the array flags using the flags attribute of the array object. The flags attribute is a dictionary containing information about the memory layout and other properties of the array.

Here, the following flags are present with the given values:

C_CONTIGUOUS: This flag is True, indicating that the array is in row-major (C-style) memory layout, meaning that elements in each row are contiguous in memory.
F_CONTIGUOUS: This flag is False, indicating that the array is not in column-major (Fortran-style) memory layout, meaning that elements in each column are not contiguous in memory.
OWNDATA: This flag is False, indicating that the array does not own its data. This means that the data is shared with another object, such as a Python list.
WRITEABLE: This flag is True, indicating that the array is writeable, meaning that its elements can be modified.
ALIGNED: This flag is True, indicating that the array data is aligned to a suitable boundary in memory for optimal performance.
UPDATEIFCOPY: This flag is False, indicating that if this array is a copy of another array, then the original array will not be updated if this array is modified.

Example: Changing the memory layout and dtype of a NumPy array using numpy.require()

>>> import numpy as np
>>> b = np.require(a, dtype=np.float32, requirements=['A', 'O', 'W', 'F'])
>>> b.flags
  C_CONTIGUOUS : False
  F_CONTIGUOUS : True
  OWNDATA : True
  WRITEABLE : True
  ALIGNED : True
  UPDATEIFCOPY : False

In the above code, a 3x3 array 'a' is created using np.arange() and np.reshape(). The flags attribute of the array shows that it is C_CONTIGUOUS (row-major), not F_CONTIGUOUS (column-major), and the memory is not owned by the array.
Next, numpy.require() is used to create a new array b, which is a copy of a with the data type converted to np.float32. The requirements argument specifies that the new array should have 'A' (aligned), 'O' (not over-aligned), 'W' (writable), and 'F' (column-major) memory layout requirements. The resulting array b is F_CONTIGUOUS (column-major), owns its memory, and is writable. The memory layout and dtype of the original array a are not modified.

Python - NumPy Code Editor:

Previous: asscalar()
Next: Joining arrays concatenate()