numpy · mattip · Feb 17, 2025 · Feb 17, 2025 · May 15, 2025 · May 29, 2025
diff --git a/doc/release/upcoming_changes/29129.enhancement.rst b/doc/release/upcoming_changes/29129.enhancement.rst
@@ -0,0 +1,7 @@
+``'same_value'`` for casting by value
+-------------------------------------
+The ``casting`` kwarg now has a ``'same_value'`` option that checks the actual
+values can be round-trip cast without changing value. Currently it is only
+implemented in `ndarray.astype`. This will raise a ``ValueError`` if any of the
+values in the array would change as a result of the cast, including rounding of
+floats or overflowing of ints.
diff --git a/doc/source/reference/c-api/array.rst b/doc/source/reference/c-api/array.rst
@@ -4452,5 +4452,10 @@ Enumerated Types
 
        Allow any cast, no matter what kind of data loss may occur.
 
+    .. c:enumerator:: NPY_SAME_VALUE_CASTING
+
+       Allow any cast, but error if any values change during the cast. Currently
+       supported only in ``ndarray.astype(... casting='same_value')``
+
 .. index::
    pair: ndarray; C-API
diff --git a/numpy/__init__.cython-30.pxd b/numpy/__init__.cython-30.pxd
@@ -156,6 +156,7 @@ cdef extern from "numpy/arrayobject.h":
         NPY_SAFE_CASTING
         NPY_SAME_KIND_CASTING
         NPY_UNSAFE_CASTING
+        NPY_SAME_VALUE_CASTING
 
     ctypedef enum NPY_CLIPMODE:
         NPY_CLIP

diff --git a/numpy/__init__.pxd b/numpy/__init__.pxd
@@ -165,6 +165,7 @@ cdef extern from "numpy/arrayobject.h":
         NPY_SAFE_CASTING
         NPY_SAME_KIND_CASTING
         NPY_UNSAFE_CASTING
+        NPY_SAME_VALUE_CASTING
 
     ctypedef enum NPY_CLIPMODE:
         NPY_CLIP

diff --git a/numpy/__init__.pyi b/numpy/__init__.pyi
@@ -965,7 +965,7 @@ _DTypeBuiltinKind: TypeAlias = L[0, 1, 2]
 
 _ArrayAPIVersion: TypeAlias = L["2021.12", "2022.12", "2023.12", "2024.12"]
 
-_CastingKind: TypeAlias = L["no", "equiv", "safe", "same_kind", "unsafe"]
+_CastingKind: TypeAlias = L["no", "equiv", "safe", "same_kind", "same_value", "unsafe"]
 
 _OrderKACF: TypeAlias = L["K", "A", "C", "F"] | None
 _OrderACF: TypeAlias = L["A", "C", "F"] | None

diff --git a/numpy/_core/_add_newdocs.py b/numpy/_core/_add_newdocs.py
@@ -3185,7 +3185,7 @@
         'C' order otherwise, and 'K' means as close to the
         order the array elements appear in memory as possible.
         Default is 'K'.
-    casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional
+    casting : {'no', 'equiv', 'safe', 'same_kind', 'same_value', 'unsafe'}, optional
         Controls what kind of data casting may occur. Defaults to 'unsafe'
         for backwards compatibility.
 
@@ -3195,6 +3195,12 @@
         * 'same_kind' means only safe casts or casts within a kind,
           like float64 to float32, are allowed.
         * 'unsafe' means any data conversions may be done.
+        * 'same_value' means any data conversions may be done, but the values
+          must not change, including rounding of floats or overflow of ints
+
+        .. versionadded:: 2.4
+            Support for ``'same_value'`` was added.
+
     subok : bool, optional
         If True, then sub-classes will be passed-through (default), otherwise
         the returned array will be forced to be a base-class array.
@@ -3217,6 +3223,9 @@
     ComplexWarning
         When casting from complex to float or int. To avoid this,
         one should use ``a.real.astype(t)``.
+    ValueError
+        When casting using ``'same_value'`` and the values change or would
+        overflow
 
     Examples
     --------

diff --git a/numpy/_core/code_generators/cversions.txt b/numpy/_core/code_generators/cversions.txt
@@ -79,5 +79,6 @@
 # Version 19 (NumPy 2.2.0) No change
 0x00000013 = 2b8f1f4da822491ff030b2b37dff07e3
 # Version 20 (NumPy 2.3.0)
-# Version 20 (NumPy 2.4.0) No change
 0x00000014 = e56b74d32a934d085e7c3414cb9999b8,
+# Version 21 (NumPy 2.4.0) Add 'same_value' casting, header additions
+0x00000015 = e56b74d32a934d085e7c3414cb9999b8,
diff --git a/numpy/_core/include/numpy/dtype_api.h b/numpy/_core/include/numpy/dtype_api.h
@@ -107,7 +107,15 @@ typedef struct PyArrayMethod_Context_tag {
 
     /* Operand descriptors, filled in by resolve_descriptors */
     PyArray_Descr *const *descriptors;
+ #if NPY_FEATURE_VERSION > NPY_2_3_API_VERSION
+    void * _reserved;
+    /* 
+     * Optional flag to pass information into the inner loop
+     * If set, it will be NPY_CASTING
+     */
+    uint64_t flags;
     /* Structure may grow (this is harmless for DType authors) */
+ #endif
 } PyArrayMethod_Context;
 
 
@@ -144,7 +152,6 @@ typedef struct {
 #define NPY_METH_contiguous_indexed_loop 9
 #define _NPY_METH_static_data 10
 
-
 /*
  * The resolve descriptors function, must be able to handle NULL values for
  * all output (but not input) `given_descrs` and fill `loop_descrs`.

diff --git a/numpy/_core/include/numpy/ndarraytypes.h b/numpy/_core/include/numpy/ndarraytypes.h
@@ -227,6 +227,8 @@ typedef enum {
         NPY_SAME_KIND_CASTING=3,
         /* Allow any casts */
         NPY_UNSAFE_CASTING=4,
+        /* Allow any casts, check that no values overflow/change */
+        NPY_SAME_VALUE_CASTING=5,
 } NPY_CASTING;
 
 typedef enum {

diff --git a/numpy/_core/include/numpy/numpyconfig.h b/numpy/_core/include/numpy/numpyconfig.h
@@ -84,6 +84,7 @@
 #define NPY_2_1_API_VERSION 0x00000013
 #define NPY_2_2_API_VERSION 0x00000013
 #define NPY_2_3_API_VERSION 0x00000014
+#define NPY_2_4_API_VERSION 0x00000015
 
 
 /*
@@ -172,8 +173,10 @@
     #define NPY_FEATURE_VERSION_STRING "2.0"
 #elif NPY_FEATURE_VERSION == NPY_2_1_API_VERSION
     #define NPY_FEATURE_VERSION_STRING "2.1"
-#elif NPY_FEATURE_VERSION == NPY_2_3_API_VERSION  /* also 2.4 */
+#elif NPY_FEATURE_VERSION == NPY_2_3_API_VERSION
     #define NPY_FEATURE_VERSION_STRING "2.3"
+#elif NPY_FEATURE_VERSION == NPY_2_4_API_VERSION
+    #define NPY_FEATURE_VERSION_STRING "2.4"
 #else
     #error "Missing version string define for new NumPy version."
 #endif

diff --git a/numpy/_core/meson.build b/numpy/_core/meson.build
@@ -50,7 +50,8 @@ C_ABI_VERSION = '0x02000000'
 # 0x00000013 - 2.1.x
 # 0x00000013 - 2.2.x
 # 0x00000014 - 2.3.x
-C_API_VERSION = '0x00000014'
+# 0x00000015 - 2.4.x
+C_API_VERSION = '0x00000015'
 
 # Check whether we have a mismatch between the set C API VERSION and the
 # actual C API VERSION. Will raise a MismatchCAPIError if so.

diff --git a/numpy/_core/src/common/array_assign.h b/numpy/_core/src/common/array_assign.h
@@ -46,7 +46,7 @@ PyArray_AssignRawScalar(PyArrayObject *dst,
 NPY_NO_EXPORT int
 raw_array_assign_scalar(int ndim, npy_intp const *shape,
         PyArray_Descr *dst_dtype, char *dst_data, npy_intp const *dst_strides,
-        PyArray_Descr *src_dtype, char *src_data);
+        PyArray_Descr *src_dtype, char *src_data, NPY_CASTING casting);
 
 /*
  * Assigns the scalar value to every element of the destination raw array
@@ -59,7 +59,7 @@ raw_array_wheremasked_assign_scalar(int ndim, npy_intp const *shape,
         PyArray_Descr *dst_dtype, char *dst_data, npy_intp const *dst_strides,
         PyArray_Descr *src_dtype, char *src_data,
         PyArray_Descr *wheremask_dtype, char *wheremask_data,
-        npy_intp const *wheremask_strides);
+        npy_intp const *wheremask_strides, NPY_CASTING casting);
 
 /******** LOW-LEVEL ARRAY MANIPULATION HELPERS ********/
 

diff --git a/numpy/_core/src/multiarray/_multiarray_tests.c.src b/numpy/_core/src/multiarray/_multiarray_tests.c.src
@@ -2168,6 +2168,7 @@ run_casting_converter(PyObject* NPY_UNUSED(self), PyObject *args)
         case NPY_SAFE_CASTING: return PyUnicode_FromString("NPY_SAFE_CASTING");
         case NPY_SAME_KIND_CASTING: return PyUnicode_FromString("NPY_SAME_KIND_CASTING");
         case NPY_UNSAFE_CASTING: return PyUnicode_FromString("NPY_UNSAFE_CASTING");
+        case NPY_SAME_VALUE_CASTING: return PyUnicode_FromString("NPY_SAME_VALUE_CASTING");
         default: return PyLong_FromLong(casting);
     }
 }