DOC: add warning to allclose, revise "Notes" in isclose

numpy/_core/numeric.py

@@ -2190,6 +2190,9 @@ def allclose(a, b, rtol=1.e-5, atol=1.e-8, equal_nan=False):
     `atol` are added together to compare against the absolute difference
     between `a` and `b`.
 
+    .. warning:: The default `atol` is not appropriate for comparing numbers
+                 with magnitudes much smaller than one (see Notes).
+
     NaNs are treated as equal if they are in the same place and if
     ``equal_nan=True``.  Infs are treated as equal if they are in the same
     place and of the same sign in both arrays.
@@ -2229,6 +2232,14 @@ def allclose(a, b, rtol=1.e-5, atol=1.e-8, equal_nan=False):
     ``allclose(a, b)`` might be different from ``allclose(b, a)`` in
     some rare cases.
 
+    The default value of `atol` is not appropriate when the reference value
+    `b` has magnitude smaller than one. For example, it is unlikely that
+    ``a = 1e-9`` and ``b = 2e-9`` should be considered "close", yet
+    ``allclose(1e-9, 2e-9)`` is ``True`` with default settings. Be sure
+    to select `atol` for the use case at hand, especially for defining the
+    threshold below which a non-zero value in `a` will be considered "close"
+    to a very small or zero value in `b`.
+
     The comparison of `a` and `b` uses standard broadcasting, which
     means that `a` and `b` need not have the same shape in order for
     ``allclose(a, b)`` to evaluate to True.  The same is true for
@@ -2271,7 +2282,7 @@ def isclose(a, b, rtol=1.e-5, atol=1.e-8, equal_nan=False):
     between `a` and `b`.
 
     .. warning:: The default `atol` is not appropriate for comparing numbers
-                 that are much smaller than one (see Notes).
+                 with magnitudes much smaller than one (see Notes).
 
     Parameters
     ----------
@@ -2308,13 +2319,15 @@ def isclose(a, b, rtol=1.e-5, atol=1.e-8, equal_nan=False):
 
     Unlike the built-in `math.isclose`, the above equation is not symmetric
     in `a` and `b` -- it assumes `b` is the reference value -- so that
-    `isclose(a, b)` might be different from `isclose(b, a)`. Furthermore,
-    the default value of atol is not zero, and is used to determine what
-    small values should be considered close to zero. The default value is
-    appropriate for expected values of order unity: if the expected values
-    are significantly smaller than one, it can result in false positives.
-    `atol` should be carefully selected for the use case at hand. A zero value
-    for `atol` will result in `False` if either `a` or `b` is zero.
+    `isclose(a, b)` might be different from `isclose(b, a)`.
+
+    The default value of `atol` is not appropriate when the reference value
+    `b` has magnitude smaller than one. For example, it is unlikely that
+    ``a = 1e-9`` and ``b = 2e-9`` should be considered "close", yet
+    ``isclose(1e-9, 2e-9)`` is ``True`` with default settings. Be sure
+    to select `atol` for the use case at hand, especially for defining the
+    threshold below which a non-zero value in `a` will be considered "close"
+    to a very small or zero value in `b`.
 
     `isclose` is not defined for non-numeric data types.
     :class:`bool` is considered a numeric data-type for this purpose.