DOC: describe ufunc copy behavior when input and output overlap (#16826)

Describing ufunc copy behaviour when input and output overlaps.

Closes #16749

Co-authored-by: Ross Barnowski <rossbar@berkeley.edu>

1 files changed, 13 insertions, 0 deletions

diff --git a/doc/source/reference/ufuncs.rst b/doc/source/reference/ufuncs.rst
index 8f506dd8b..a0a5a4a06 100644
--- a/doc/source/reference/ufuncs.rst
+++ b/doc/source/reference/ufuncs.rst
@@ -335,6 +335,19 @@ advanced usage and will not typically be used.
     Note that outputs not explicitly filled are left with their
     uninitialized values.
 
+    .. versionadded:: 1.13
+
+    Operations where ufunc input and output operands have memory overlap are
+    defined to be the same as for equivalent operations where there
+    is no memory overlap.  Operations affected make temporary copies
+    as needed to eliminate data dependency.  As detecting these cases
+    is computationally expensive, a heuristic is used, which may in rare
+    cases result in needless temporary copies.  For operations where the
+    data dependency is simple enough for the heuristic to analyze,
+    temporary copies will not be made even if the arrays overlap, if it
+    can be deduced copies are not necessary.  As an example,
+    ``np.add(a, b, out=a)`` will not involve copies.
+
 *where*
 
     .. versionadded:: 1.7