w3resource

NumPy: numpy.require() function

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()



Become a Patron!

Follow us on Facebook and Twitter for latest update.

It will be nice if you may share this link in any developer community or anywhere else, from where other developers may find this content. Thanks.

https://www.w3resource.com/numpy/manipulation/require.php