lu

Perform LU decomposition. More...

Functions
AFAPI void	lu (array &out, array &pivot, const array &in, const bool is_lapack_piv=true)
	C++ Interface to perform LU decomposition in packed format. More...
AFAPI void	lu (array &lower, array &upper, array &pivot, const array &in)
	C++ Interface to perform LU decomposition. More...
AFAPI void	luInPlace (array &pivot, array &in, const bool is_lapack_piv=true)
	C++ Interface to perform in-place LU decomposition. More...
AFAPI af_err	af_lu (af_array *lower, af_array *upper, af_array *pivot, const af_array in)
	C Interface to perform LU decomposition. More...
AFAPI af_err	af_lu_inplace (af_array *pivot, af_array in, const bool is_lapack_piv)
	C Interface to perform in-place LU decomposition. More...

Detailed Description

Perform LU decomposition.

This function decomposes input matrix \(A\) into a lower triangle \(L\), an upper triangle \(U\) such that \(A = L * U\).

For stability, a permutation array \(P\) is also used to modify the formula in the following manner, \(A(P, span) = L * U\).

This operation can be performed in ArrayFire, using the following code snippet.

    array l, u, pivot;
    lu(l, u, pivot, a_orig);

The permuted version of the original matrix can be reconstructed, using the following snippet.

    array a_recon = matmul(l, u);
    array a_perm  = a_orig(pivot, span);

The sample output for these operations can be seen below.

a_orig [3 3 1 1]
    0.0000     3.0000     6.0000
    1.0000     4.0000     7.0000
    2.0000     5.0000     8.0000
 
l [3 3 1 1]
    1.0000     0.0000     0.0000
    0.0000     1.0000     0.0000
    0.5000     0.5000     1.0000
 
u [3 3 1 1]
    2.0000     5.0000     8.0000
    0.0000     3.0000     6.0000
    0.0000     0.0000     0.0000
 
pivot [3 1 1 1]
         2
         0
         1
 
a_recon [3 3 1 1]
    2.0000     5.0000     8.0000
    0.0000     3.0000     6.0000
    1.0000     4.0000     7.0000
 
a_perm [3 3 1 1]
    2.0000     5.0000     8.0000
    0.0000     3.0000     6.0000
    1.0000     4.0000     7.0000

When memory is a concern, users can perform the LU decomposition in place as shown below.

    array out = a_orig.copy();
    array pivot2;
    luInPlace(pivot2, out, false);

The lower and upper triangle matrices can be obtained if necessary in the following manner.

    array l2 = lower(out, true);
    array u2 = upper(out, false);

LU decompositions have many applications including solving a system of linear equations. Check af::solveLU for more information.

---

Function Documentation

af_lu()

AFAPI af_err af_lu	(	af_array *	lower,
		af_array *	upper,
		af_array *	pivot,
		const af_array	in
	)

C Interface to perform LU decomposition.

Parameters

[out]	lower	lower triangular matrix of the LU decomposition
[out]	upper	upper triangular matrix of the LU decomposition
[out]	pivot	permutation indices mapping the input to the decomposition
[in]	in	input array

Returns

AF_SUCCESS, if function returns successfully, else an af_err code is given

af_lu_inplace()

AFAPI af_err af_lu_inplace	(	af_array *	pivot,
		af_array	in,
		const bool	is_lapack_piv
	)

C Interface to perform in-place LU decomposition.

This function is not supported in GFOR.

Parameters

[out]	pivot	permutation indices mapping the input to the decomposition
[in,out]	in	input array on entry; packed LU decomposition on exit
[in]	is_lapack_piv	specifies if the pivot is returned in original LAPACK-compliant format

Returns

AF_SUCCESS, if function returns successfully, else an af_err code is given

lu() [1/2]

AFAPI void lu	(	array &	lower,
		array &	upper,
		array &	pivot,
		const array &	in
	)

C++ Interface to perform LU decomposition.

This function is not supported in GFOR.

Parameters

[out]	lower	lower triangular matrix of the LU decomposition
[out]	upper	upper triangular matrix of the LU decomposition
[out]	pivot	permutation indices mapping the input to the decomposition
[in]	in	input array

lu() [2/2]

AFAPI void lu	(	array &	out,
		array &	pivot,
		const array &	in,
		const bool	is_lapack_piv = true
	)

C++ Interface to perform LU decomposition in packed format.

This function is not supported in GFOR.

Parameters

[out]	out	packed LU decomposition
[out]	pivot	permutation indices mapping the input to the decomposition
[in]	in	input array
[in]	is_lapack_piv	specifies if the pivot is returned in original LAPACK compliant format

luInPlace()

AFAPI void luInPlace	(	array &	pivot,
		array &	in,
		const bool	is_lapack_piv = true
	)

C++ Interface to perform in-place LU decomposition.

This function is not supported in GFOR.

Parameters

[out]	pivot	permutation indices mapping the input to the decomposition
[in,out]	in	input array on entry; packed LU decomposition on exit
[in]	is_lapack_piv	specifies if the pivot is returned in original LAPACK-compliant format