compute the Cholesky, PLU or PLU1R decomposition of a Matrix
LUDecomposition(A, m, out, c, ip, options, outopts)
Matrix or list of 3 Vectors
(optional) equation of the form method = name where name is one of 'GaussianElimination', 'RREF', 'FractionFree', 'Cholesky', 'SparseDirect', 'SparseDirectMKL', or 'none'; method used to factorize A
(optional) equation of the form output = obj where obj is one of 'P', 'L', 'U', 'U1', 'R', 'NAG', 'handle', 'determinant', or 'rank', or a list consisting of one or more of these names; selects result objects to compute
(optional) equation of the form conjugate=true or false; specifies whether to use the Hermitian transpose in the case of Cholesky decomposition
(optional) equation of the form inplace=true or false; specifies if output overwrites input when U or NAG is in the output list
(optional) equations giving options specific to the method, detailed below
(optional); constructor options for the result object(s)
(optional) equation(s) of the form outputoptions[o] = list where o is one of 'P', 'L', 'U', 'U1', 'R', 'NAG'; constructor options for the specified result object
The LUDecomposition command computes a PLU decomposition, a modified PLU1R decomposition, or a Cholesky decomposition of the Matrix A.
Depending on what is included in the output option (out), an expression sequence containing one or more of the factors P, L, U, U1, R, the compact NAG form, an abstract representation of the factored matrix as processed by the SparseDirectMKL method (called a handle), the determinant, and the rank can be returned. The objects are returned in the same order as specified in the output list.
Note: Either U or the pair U1 and R may be returned, but not both.
The LUDecomposition(A) calling sequence is equivalent, by default, to LUDecomposition(A, method='GaussianElimination'). If A has both symmetric or hermitian shape and positive_definite attributes, then the LUDecomposition(A) calling sequence is equivalent to LUDecomposition(A, method='Cholesky').
The LUDecomposition(A, method='GaussianElimination') calling sequence is equivalent to LUDecomposition(A, method='GaussianElimination', output=['P','L','U']). This PLU decomposition generates a square unit lower triangular L factor and an upper triangular factor U with the same dimensions as A so that A=P·L·U. The Matrix P is a permutation Matrix.
The selection of pivots in the GaussianElimination method differs according to the type of the Matrix entries. For Matrices with numeric entries and at least one floating-point entry, pivots are selected according to absolute magnitude. For Matrices with only exact rational or symbolic entries, pivots are selected as the first nonzero element in the current column, moving downwards from the current row.
The PLU1R decomposition is achieved by using LUDecomposition(A, method='RREF') or LUDecomposition(A, output=['P','L','U1','R']). This further factors U into U1·R where U1 is square upper triangular factor and R is the unique reduced row echelon form of the Matrix A. In this case, A=P·L·U1·R. The option method=Cholesky is incompatible with providing either U1 or R in the out list.
The PLU decomposition obtained by using method='FractionFree' generates a square non-unit lower triangular L factor and fraction-free upper triangular factor U with the same dimensions as A so that A=P·L·U. The Matrix P is a permutation Matrix.
The Cholesky decomposition of the positive definite Matrix A can be obtained by using LUDecomposition(A, method='Cholesky') which generates the square lower triangular factor L. If A is real symmetric, then A=L·Transpose⁡L; if A is complex hermitian, then A=L·HermitianTranspose⁡L. The factor U=HermitianTranspose⁡L can be generated using the calling sequence LUDecomposition(A, method='Cholesky', output=['U']).
For the Cholesky decomposition, if A is neither real symmetric nor complex hermitian, then a library-level warning is generated. In such a case, A is treated as if it were hermitian or symmetric, with only one of the upper or lower triangles of A being accessed. For floating-point data, the upper triangle of A is used if the factor U is requested; otherwise, the lower triangle of A is used. For exact data, the upper triangle of A is used.
If the SparseDirect or (equivalently) SparseDirectMKL method is selected, an abstract representation of the matrix factorization is returned. This representation can be used with the LinearSolve command. It is not possible to retrieve the individual factors from this abstract representation.
The SparseDirect and SparseDirectMKL methods use routines from the Intel oneAPI Math Kernel Library (software.intel.com/en-us/intel-mkl). This library is not available on Apple Silicon Macs when running native binaries. In order to use the SparseDirect or SparseDirectMKL methods on such computers, start the Intel x86-64 version of Maple. For more information, see Platform Specific Issues.
If m is not specified in the calling sequence, method='none' is used. Note: method='none' is equivalent to method='GaussianElimination'.
In the case of Cholesky decomposition, the Hermitian transpose is used by default. If conjugate=false is specified in the calling sequence, the ordinary transpose is used.
The output option (out) determines the content of the returned expression sequence.
If output='NAG' and method='Cholesky' are specified in the calling sequence, then the output consists of a Matrix whose lower triangle contains the data of the lower triangular factorization. The entries above the diagonal may not be set to zero.
If output='NAG' is specified and the Cholesky factorization method is not used, then the output is an expression sequence consisting of a Vector followed by a Matrix. The upper triangle of the Matrix is the U factor and the strictly lower triangle is the L factor (with implicit ones along the diagonal). The Vector is the NAG-style pivot Vector.
If NAG is included in the output list, all other output entries are excluded with the exception of determinant and rank.
If handle is included in the output list, nothing else can be included. This output is only available with the SparseDirect and SparseDirectMKL methods, and conversely, when using the SparseDirect or SparseDirectMKL methods, only the handle output can be requested.
The inplace option (ip) determines where the result is returned. If given as inplace=true and either U or NAG is included in the output list, the result overwrites the first argument. If given as inplace=false, or if this option is not included in the calling sequence, the result is returned in a new Matrix.
The condition inplace=true can be abbreviated to inplace.
The inplace option must be used with caution since, if the operation fails, the original Matrix argument may be corrupted.
The constructor options provide additional information (readonly, shape, storage, order, datatype, and attributes) to the Matrix or Vector constructor that builds the result(s). These options may also be provided in the form outputoptions[o]=[...], where [...] represents a Maple list. If a constructor option is provided in both the calling sequence directly and in an outputoptions[o] option, the latter takes precedence (regardless of the order).
The following list indicates permissible values for index [o] of outputoptions with their corresponding meaning.
lower triangular factor
upper triangular factor
square upper triangular factor
reduced row echelon form
compact (NAG-style) form
The inplace and constructor options are mutually exclusive.
The SparseDirect and SparseDirectMKL methods are only available for matrices that are in (or can be converted to) NAG-sparse form. That is, the datatype as returned by rtable_options needs to be one of these values:
The data type will internally be converted to float8 or complex8 if it isn't one of these types already. Note that this method is most useful for sparse matrices.
The SparseDirect and SparseDirectMKL methods are the only methods that accept A as being a list of 3 Vectors. These 3 Vectors should form the compressed sparse row form of the Matrix to be factored. If A is a Matrix and these methods are selected, the compressed sparse row form is computed with the CompressedSparseForm command, with the options form = row, includediagonal = true, and, if structural symmetry is selected, structuralsymmetry = true. If symmetry = symmetric or symmetry = hermitian is selected, the code ensures that A has upper triangular storage. If you want to construct or modify the compressed sparse row form of A manually, you need to ensure that similar precautions are taken.
The SparseDirect and SparseDirectMKL methods are the only methods that accept the mopts argument. These method-specific options can have this form:
domain = real or complex
This specifies whether a factorization over the real or complex domain is performed. By default, this is determined as follows: if the data type of A (or the third entry of A if A is a list of 3 Vectors) is float8 or complex8, then the domain is selected as real or complex, respectively. Otherwise, Maple attempts to convert the values in A to type float8. If this is successful, it selects the real domain. Otherwise, the values are converted to complex8 and the complex domain is selected.
symmetry = none or structural or symmetric or hermitian
This specifies what symmetry properties can be used for A:
With symmetry = none, no symmetry properties are assumed.
With symmetry = structural, the solver requires that there is an entry Ai,j in the compressed sparse row representation of A whenever there is an entry Aj,i, but no relationship between the two is assumed.
With symmetry = symmetric, the solver requires that Ai,j=Aj,i for all i,j. Only the upper diagonal entries of A are submitted to the solver.
With symmetry = hermitian, the solver requires that Ai,j=Aj,i&conjugate0; for all i,j. Only the upper diagonal entries of A are submitted to the solver.
If A is a list of 3 Vectors, then by default, no symmetry is assumed. If A is a Matrix, then Maple uses the appropriate type of symmetry if the indexing function is symmetric or hermitian, and no symmetry otherwise.
definite = indefinite or positive
With certain combinations of symmetry and domain, the solver can use positive definiteness of A if it applies. You can specify whether A is positive definite using the option definite = positive or force Maple not to use definiteness by specifying definite = indefinite. By default, if A is a list of 3 Vectors, Maple assumes A is not positive definite. If A is a Matrix, then Maple assumes that A is positive definite only if A has the attribute positive_definite.
The LU decomposition of a Matrix can be used as input for the LinearSolve, MatrixInverse, and ConditionNumber commands. For more details on how to do this, see these help pages.
For more information on the P.L.U1.R decomposition see: Corless, Robert M, and Jeffrey, David J, "The Turing Factorization of a Rectangular Matrix," Sigsam Bulletin 31, no. 3 (September 1997): 20-28. This paper names the U1 factor U.
This function is part of the LinearAlgebra package, and so it can be used in the form LUDecomposition(..) only after executing the command with(LinearAlgebra). However, it can always be accessed through the long form of the command by using LinearAlgebra[LUDecomposition](..).
A ≔ 0,−2,0,3|1,3,0,1|1,1,0,0|−3,4,1,0
p,l,u ≔ LUDecomposition⁡A
B ≔ 1,0,2|3,1,4|6,1,4|1,1,2:
C ≔ Matrix⁡4,4,64.+0.⁢I,−3.−41.⁢I,19.−8.⁢I,−14.+19.⁢I,33.+0.⁢I,13.−1.⁢I,−10.−5.⁢I,93.+0.⁢I,−61.−0.⁢I,66.+0.⁢I,scan=triangularupper,datatype=complex8,shape=hermitian
To reduce a Matrix using Gaussian elimination, specify the 'U' object:
To reduce a Matrix using Gauss-Jordan elimination, specify the 'R' object:
To factor a Matrix using the SparseDirectMKL method, specify this method explicitly after ensuring an appropriate data type for the Matrix.
m ≔ Matrix⁡1|0|1,2|0|0,2|0|3,datatype=float8
before P call
after P call
The LinearAlgebra[LUDecomposition] command was updated in Maple 2023.
The domain, symmetry and definite options were introduced in Maple 2023.
For more information on Maple 2023 changes, see Updates in Maple 2023.
Download Help Document