Merge pull request numpy#26398 from ajayjanapareddi/main

DOC: order of indices returned in tril_indices and triu_indices

numpy/lib/_twodim_base_impl.py

@@ -922,8 +922,9 @@ def tril_indices(n, k=0, m=None):
     Returns
     -------
     inds : tuple of arrays
-        The indices for the triangle. The returned tuple contains two arrays,
-        each with the indices along one dimension of the array.
+        The row and column indices, respectively. The row indices are sorted
+        in non-decreasing order, and the correspdonding column indices are
+        strictly increasing for each row.
 
     See also
     --------
@@ -944,8 +945,11 @@ def tril_indices(n, k=0, m=None):
     diagonals further right:
 
     >>> il1 = np.tril_indices(4)
-    >>> il2 = np.tril_indices(4, 2)
+    >>> il1
+    (array([0, 1, 1, 2, 2, 2, 3, 3, 3, 3]), array([0, 0, 1, 0, 1, 2, 0, 1, 2, 3]))
 
+    Note that row indices (first array) are non-decreasing, and the corresponding
+    column indices (second array) are strictly increasing for each row.
     Here is how they can be used with a sample array:
 
     >>> a = np.arange(16).reshape(4, 4)
@@ -971,6 +975,7 @@ def tril_indices(n, k=0, m=None):
 
     These cover almost the whole array (two diagonals right of the main one):
 
+    >>> il2 = np.tril_indices(4, 2)
     >>> a[il2] = -10
     >>> a
     array([[-10, -10, -10,   3],
@@ -1075,9 +1080,9 @@ def triu_indices(n, k=0, m=None):
     Returns
     -------
     inds : tuple, shape(2) of ndarrays, shape(`n`)
-        The indices for the triangle. The returned tuple contains two arrays,
-        each with the indices along one dimension of the array.  Can be used
-        to slice a ndarray of shape(`n`, `n`).
+        The row and column indices, respectively. The row indices are sorted
+        in non-decreasing order, and the correspdonding column indices are
+        strictly increasing for each row.
 
     See also
     --------
@@ -1098,7 +1103,11 @@ def triu_indices(n, k=0, m=None):
     diagonals further right:
 
     >>> iu1 = np.triu_indices(4)
-    >>> iu2 = np.triu_indices(4, 2)
+    >>> iu1
+    (array([0, 0, 0, 0, 1, 1, 1, 2, 2, 3]), array([0, 1, 2, 3, 1, 2, 3, 2, 3, 3]))
+
+    Note that row indices (first array) are non-decreasing, and the corresponding
+    column indices (second array) are strictly increasing for each row.
 
     Here is how they can be used with a sample array:
 
@@ -1126,6 +1135,7 @@ def triu_indices(n, k=0, m=None):
     These cover only a small part of the whole array (two diagonals right
     of the main one):
 
+    >>> iu2 = np.triu_indices(4, 2)
     >>> a[iu2] = -10
     >>> a
     array([[ -1,  -1, -10, -10],