`scipy.linalg._decomp_lu:lu`

source: /scipy/linalg/_decomp_lu.py:219

Signature

def lu(a, permute_l = False, overwrite_a = False, check_finite = True, p_indices = False)

Summary

Compute LU decomposition of a matrix with partial pivoting.

Extended Summary

The decomposition satisfies

A = P @ L @ U

where P is a permutation matrix, L lower triangular with unit diagonal elements, and U upper triangular. If permute_l is set to True then L is returned already permuted and hence satisfying A = L @ U.

Array argument(s) of this function may have additional "batch" dimensions prepended to the core shape. In this case, the array is treated as a batch of lower-dimensional slices; see linalg_batch for details.

Parameters

a : (..., M, N) array_like: 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). Default is False. See tutorial_linalg_overwrite for details.
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: Permutation arrays or vectors depending on p_indices.
l: Lower triangular or trapezoidal array with unit diagonal, where the last dimension is K = min(M, N).
pl: Permuted L matrix with last dimension being K = min(M, N).
u: 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

✗

array([[0., 1., 0., 0.],
       [0., 0., 0., 1.],
       [1., 0., 0., 0.],
       [0., 0., 1., 0.]])

p, _, _ = lu(A, p_indices=True)

✓

✗

array([1, 3, 0, 2], dtype=int32)

np.allclose(A, l[p, :] @ u)

✓

True

We can also use nd-arrays, for example, a demonstration with 4D array:

rng = np.random.default_rng()
A = rng.uniform(low=-4, high=4, size=[3, 2, 4, 8])
p, l, u = lu(A)
p.shape, l.shape, u.shape
np.allclose(A, p @ l @ u)
PL, U = lu(A, permute_l=True)
np.allclose(A, PL @ U)

✓

True

Aliases

scipy.linalg.lu