DOC: Add warning about differences between range and arange (#20972)

* DOC: Add warning about differences between range and arange

* Update to range instance instead of list

* Fix example

1 files changed, 20 insertions, 3 deletions

diff --git a/numpy/core/_add_newdocs.py b/numpy/core/_add_newdocs.py
index 1bbacad45..e432f6a11 100644
--- a/numpy/core/_add_newdocs.py
+++ b/numpy/core/_add_newdocs.py
@@ -1600,11 +1600,14 @@ add_newdoc('numpy.core.multiarray', 'arange',
 
     Values are generated within the half-open interval ``[start, stop)``
     (in other words, the interval including `start` but excluding `stop`).
-    For integer arguments the function is equivalent to the Python built-in
-    `range` function, but returns an ndarray rather than a list.
+    For integer arguments the function is roughly equivalent to the Python
+    built-in :py:class:`range`, but returns an ndarray rather than a ``range``
+    instance.
 
     When using a non-integer step, such as 0.1, it is often better to use
-    `numpy.linspace`. See the warnings section below for more information.
+    `numpy.linspace`.
+    
+    See the Warning sections below for more information.
 
     Parameters
     ----------
@@ -1656,6 +1659,20 @@ add_newdoc('numpy.core.multiarray', 'arange',
 
     In such cases, the use of `numpy.linspace` should be preferred.
 
+    The built-in :py:class:`range` generates :std:doc:`Python built-in integers
+    that have arbitrary size <c-api/long>`, while `numpy.arange` produces
+    `numpy.int32` or `numpy.int64` numbers. This may result in incorrect
+    results for large integer values::
+
+      >>> power = 40
+      >>> modulo = 10000
+      >>> x1 = [(n ** power) % modulo for n in range(8)]
+      >>> x2 = [(n ** power) % modulo for n in np.arange(8)]
+      >>> print(x1)
+      [0, 1, 7776, 8801, 6176, 625, 6576, 4001]  # correct
+      >>> print(x2)
+      [0, 1, 7776, 7185, 0, 5969, 4816, 3361]  # incorrect
+
     See Also
     --------
     numpy.linspace : Evenly spaced numbers with careful handling of endpoints.