Repository: scipy/scipy
File: scipy/linalg/_decomp_lu.py (Python)

Code before:
        Array to decompose
    permute_l : bool, optional
        Perform the multiplication P*L (Default: do not permute)
    overwrite_a : bool, optional
        Whether to overwrite data in a (may improve performance)
    check_finite : bool, optional
        Whether to check that the input matrix contains only finite numbers.
        Disabling may give a performance gain, but may result in problems
        (crashes, non-termination) if the inputs do contain infinities or NaNs.
    p_indices : bool, optional
        If ``True`` the permutation information is returned as row indices.
        The default is ``False`` for backwards-compatibility reasons.

    Returns
    -------
    **(If** `permute_l` **is** ``False`` **)**

    p : (..., M, M) ndarray
        Permutation arrays or vectors depending on `p_indices`
    l : (..., M, K) ndarray
        Lower triangular or trapezoidal array with unit diagonal.
        ``K = min(M, N)``
    u : (..., K, N) ndarray
        Upper triangular or trapezoidal array

    **(If** `permute_l` **is** ``True`` **)**

    pl : (..., M, K) ndarray
        Permuted L matrix.
        ``K = min(M, N)``
    u : (..., K, N) ndarray
        Upper triangular or trapezoidal array

    Notes
    -----
    Permutation matrices are costly since they are nothing but row reorder of
    ``L`` and hence indices are strongly recommended to be used instead if the
    permutation is required. The relation in the 2D case then becomes simply
    ``A = L[P, :] @ U``. In higher dimensions, it is better to use `permute_l`
    to avoid complicated indexing tricks.

    In 2D case, if one has the indices however, for some reason, the
    permutation matrix is still needed then it can be constructed by
    ``np.eye(M)[P, :]``.

    Examples
    --------

    >>> import numpy as np
    >>> from scipy.linalg import lu
    >>> A = np.array([[2, 5, 8, 7], [5, 2, 2, 8], [7, 5, 6, 6], [5, 4, 4, 8]])

Review comment (suggestion):
In my opinion, this whole text block's [render] could be arranged better. What do you think about:

```text
    (p, l, u) | (pl, u):
        The tuple `(p, l, u)` is returned if `permute_l` is ``False`` (default) else
        the tuple `(pl, u)` is returned, where:

        p : (..., M, M) ndarray
            Permutation arrays or vectors depending on `p_indices`.
        l : (..., M, K) ndarray
            Lower triangular or trapezoidal array with unit diagonal, where the last
            dimension is ``K = min(M, N)``.
        pl : (..., M, K) ndarray
            Permuted L matrix with last dimension being ``K = min(M, N)``.
        u : (..., K, N) ndarray
            Upper triangular or trapezoidal array.
```

Of course, this is primarily a matter of personal taste.

[render]: https://output.circle-artifacts.com/output/job/34ef74ad-ca89-4fe0-9625-6fb8400a2442/artifacts/0/html/reference/generated/scipy.linalg.lu.html

Code after:
        Array to decompose
    permute_l : bool, optional
        Perform the multiplication P*L (Default: do not permute)
    overwrite_a : bool, optional
        Whether to overwrite data in a (may improve performance)
    check_finite : bool, optional
        Whether to check that the input matrix contains only finite numbers.
        Disabling may give a performance gain, but may result in problems
        (crashes, non-termination) if the inputs do contain infinities or NaNs.
    p_indices : bool, optional
        If ``True`` the permutation information is returned as row indices.
        The default is ``False`` for backwards-compatibility reasons.

    Returns
    -------
    (p, l, u) | (pl, u):
        The tuple `(p, l, u)` is returned if `permute_l` is ``False`` (default) else
        the tuple `(pl, u)` is returned, where:

        p : (..., M, M) ndarray
            Permutation arrays or vectors depending on `p_indices`.
        l : (..., M, K) ndarray
            Lower triangular or trapezoidal array with unit diagonal, where the last
            dimension is ``K = min(M, N)``.
        pl : (..., M, K) ndarray
            Permuted L matrix with last dimension being ``K = min(M, N)``.
        u : (..., K, N) ndarray
            Upper triangular or trapezoidal array.

    Notes
    -----
    Permutation matrices are costly since they are nothing but row reorder of
    ``L`` and hence indices are strongly recommended to be used instead if the
    permutation is required. The relation in the 2D case then becomes simply
    ``A = L[P, :] @ U``. In higher dimensions, it is better to use `permute_l`
    to avoid complicated indexing tricks.

    In 2D case, if one has the indices however, for some reason, the
    permutation matrix is still needed then it can be constructed by
    ``np.eye(M)[P, :]``.

    Examples
    --------

    >>> import numpy as np
    >>> from scipy.linalg import lu
    >>> A = np.array([[2, 5, 8, 7], [5, 2, 2, 8], [7, 5, 6, 6], [5, 4, 4, 8]])
    >>> p, l, u = lu(A)
    >>> np.allclose(A, p @ l @ u)
    True
    >>> p  # Permutation matrix