Understanding NumPy Data Type Equivalence with PyArray_EquivTypes

NumPy C-API and dtypes

NumPy provides a C-API (Application Programming Interface) that allows developers to interact with NumPy arrays from C code. One important aspect of the C-API is dealing with data types (dtypes) of arrays. The PyArray_EquivTypes function is a core function in this regard.

What is PyArray_EquivTypes?

PyArray_EquivTypes is a function defined in the NumPy C-API. It takes two NumPy data types (dtype1 and dtype2) as arguments and returns a boolean value indicating whether these two data types are equivalent.

How does it work?

The function follows a two-step approach to determine equivalence:

1. Exact match
   It first checks if the two data types are exactly the same using the == operator. If they are identical, it returns True. This covers cases where you have the same fundamental data type (e.g., int, float, bool).

2. Kind check
   If the first step doesn't match, it compares the kind attribute of the data types. The kind attribute indicates the category of the data type (e.g., 'i' for integer, 'f' for float, 'b' for bool). If the kind attributes are the same, it suggests compatibility between the data types. In this case, the function returns True. This covers scenarios where you have compatible numerical data types like int and float.

3. More complex cases (not implemented here)
   The provided example focuses on the core functionality. In real-world use cases, there might be more complex data types like structured arrays. These require additional checks beyond basic and numeric types. The provided implementation serves as a foundation and can be extended to handle such cases.

Example usage

The provided Python code demonstrates how PyArray_EquivTypes can be used to compare data types of NumPy arrays. The function is_dtype_equivalent wraps the C-API function for convenience. It shows that int and float arrays are considered equivalent, while int and bool arrays are not.

In summary,

---

#include <stdio.h>
#include <numpy/arrayobject.h>

int is_dtype_equivalent(PyArray_Descr *dtype1, PyArray_Descr *dtype2) {
  // Check for exact match
  if (dtype1 == dtype2) {
    return 1;
  }

  // Check for compatible kinds (e.g., int and float)
  return (dtype1->kind == dtype2->kind);
}

int main() {
  // Create NumPy arrays with different data types
  int arr1[] = {1, 2, 3};
  float arr2[] = {1.0, 2.0, 3.0};
  bool arr3[] = {true, false, true};

  PyArrayObject *array1 = PyArray_FromInts(sizeof(arr1) / sizeof(arr1[0]), NPY_CORDER, NPY_INT, arr1);
  PyArrayObject *array2 = PyArray_FromFloats(sizeof(arr2) / sizeof(arr2[0]), NPY_CORDER, NPY_FLOAT, arr2);
  PyArrayObject *array3 = PyArray_FromBoolean(sizeof(arr3) / sizeof(arr3[0]), NPY_CORDER, NPY_BOOL, arr3);

  // Get data types of the arrays
  PyArray_Descr *dtype1 = PyArray_DescrFromObject(PyArray_TYPE(array1));
  PyArray_Descr *dtype2 = PyArray_DescrFromObject(PyArray_TYPE(array2));
  PyArray_Descr *dtype3 = PyArray_DescrFromObject(PyArray_TYPE(array3));

  // Check equivalence using the function
  int int_float_equiv = is_dtype_equivalent(dtype1, dtype2);
  int int_bool_equiv = is_dtype_equivalent(dtype1, dtype3);

  // Print the results
  printf("int and float equivalent: %d\n", int_float_equiv);
  printf("int and bool equivalent: %d\n", int_bool_equiv);

  // Release memory
  Py_DECREF(array1);
  Py_DECREF(array2);
  Py_DECREF(array3);
  Py_DECREF(dtype1);
  Py_DECREF(dtype2);
  Py_DECREF(dtype3);

  return 0;
}

This code first defines a function is_dtype_equivalent that mirrors the behavior explained earlier. Then, it creates NumPy arrays of integer, float, and boolean data types. It extracts their data types and uses the is_dtype_equivalent function to check if int is equivalent to float and bool. Finally, it prints the results. This demonstrates how to use the PyArray_EquivTypes concept in practice.

---

1. • Access the kind attribute of the data types using dtype.kind.
   • Compare the kind attributes for equality. This works well for basic data types like integers, floats, and booleans.

   int is_dtype_equivalent(PyArray_Descr *dtype1, PyArray_Descr *dtype2) {
       return (dtype1->kind == dtype2->kind);
   }
   

2. Using PyArray_CanCastSafely
   

   • This function checks if elements of one data type can be safely cast to another. It's more comprehensive than just comparing kind and can handle cases like compatible byte orders or casting between scaled integers.

   int is_dtype_equivalent(PyArray_Descr *dtype1, PyArray_Descr *dtype2) {
       return PyArray_CanCastSafely(dtype1, dtype2, NPY_SAFE_CAST);
   }
   

3. Custom logic based on dtype properties
   

   • For more complex scenarios, you can extend the logic by examining other properties of the dtype objects, such as itemsize (element size in bytes) or specific type parameters.

Remember that PyArray_EquivTypes might internally use a combination of these approaches for its determination. The best alternative depends on the specific requirements of your use case.

int is_dtype_equivalent(PyArray_Descr *dtype1, PyArray_Descr *dtype2) {
  // Check for exact match
  if (dtype1 == dtype2) {
    return 1;
  }

  // Check for compatible kinds and allow safe casting
  return (dtype1->kind == dtype2->kind) && PyArray_CanCastSafely(dtype1, dtype2, NPY_SAFE_CAST);
}