The CreatePermutation(V) function constructs a permutation Vector or Matrix from a NAG pivot vector.  By default, the resulting object is a Vector of rectangular storage and integer datatype or a Matrix of sparse storage and integer datatype.

A pivot vector V in NAG form, returned for example by an LU decomposition of a Matrix A, has all integer entries.  Its ith element is the ordinal of the row of the partially row-reduced Matrix which is selected as the ith choice of pivoting row.  Prior to performing the ith pivot, row i and row V[i] of the partially row-reduced Matrix are swapped.

A returned permutation Vector U has as its ith entry the ordinal of the row of A such that, if all U[i]th rows of A were permuted to the ith row, i = 1 .. n, then no swapping would be required to do the factorization with the exact same choices of pivot rows.  The default datatype of a returned permutation Vector is integer.

A returned permutation Matrix M has all entries with value 1 or 0.  Premultiplying A by M permutes A to a Matrix whose factorization would require no row swapping in order to use the same choices of pivot values.  The ith pivoting row of M . A would be the ith row of M . A  (i.e., no pivoting is required to compute the decomposition of M . A).  The default datatype of a returned permutation Matrix is integer. The default storage is sparse.

If the optional nonnegative integer parameter d is provided then the dimension(s) of the output object have the value d.  This value must be greater than or equal to the dimension of the input Vector V.  This allows the shortened form of a pivot vector used by NAG when the number of rows of an LU factorizable Matrix A is larger than the number of its columns.  For example, the pivot vector Vector[column](3, [6, 6, 6]) is equivalent to the pivot vector Vector[column](6, [6, 6, 6, 4, 5, 6]).

The constructor options provide additional information (readonly, shape, storage, order, datatype, and attributes) to the Matrix or Vector constructor that builds the result. These options may also be provided in the form outputoptions=[...], where [...] represents a Maple list.  If a constructor option is provided in both the calling sequence directly and in an outputoptions option, the latter takes precedence (regardless of the order).

This function is part of the LinearAlgebra package, and so it can be used in the form CreatePermutation(..) only after executing the command with(LinearAlgebra). However, it can always be accessed through the long form of the command by using LinearAlgebra[CreatePermutation](..).

$\mathrm{with}\left(\mathrm{LinearAlgebra}\right)\:$

$A≔\mathrm{Matrix}\left(\left[\left[0\,1\,1\,-3\right]\,\left[-2\,3\,1\,4\right]\,\left[0\,0\,0\,1\right]\,\left[3\,1\,0\,0\right]\right]\right)\:$

$\mathrm{nv},U≔\mathrm{LUDecomposition}\left(A\,\mathrm{output}='\mathrm{NAG}'\right)$

$\mathrm{nv},U≔\left[\begin{array}{c}2\\ 2\\ 4\\ 4\end{array}\right],\left[\begin{array}{cccc}\mathrm{-2}& 3& 1& 4\\ 0& 1& 1& \mathrm{-3}\\ -\frac{3}{2}& \frac{11}{2}& \mathrm{-4}& \frac{45}{2}\\ 0& 0& 0& 1\end{array}\right]$

$\mathrm{pm}≔\mathrm{CreatePermutation}\left(\mathrm{nv}\,\mathrm{output}='\mathrm{Matrix}'\right)$

$\mathrm{pm}≔\left[\begin{array}{cccc}0& 1& 0& 0\\ 1& 0& 0& 0\\ 0& 0& 0& 1\\ 0& 0& 1& 0\end{array}\right]$

$\mathrm{LUDecomposition}\left(\mathrm{pm}·A\,\mathrm{output}='\mathrm{NAG}'\right)$

$\left[\begin{array}{c}1\\ 2\\ 3\\ 4\end{array}\right],\left[\begin{array}{cccc}\mathrm{-2}& 3& 1& 4\\ 0& 1& 1& \mathrm{-3}\\ -\frac{3}{2}& \frac{11}{2}& \mathrm{-4}& \frac{45}{2}\\ 0& 0& 0& 1\end{array}\right]$

$\mathrm{pv}≔\mathrm{CreatePermutation}\left(\mathrm{nv}\,\mathrm{output}='\mathrm{Vector}'\right)$

$\mathrm{pv}≔\left[\begin{array}{c}2\\ 1\\ 4\\ 3\end{array}\right]$

$A≔A\left[\mathrm{convert}\left(\mathrm{pv}\,\mathrm{list}\right),1..-1\right]$

$A≔\left[\begin{array}{cccc}\mathrm{-2}& 3& 1& 4\\ 0& 1& 1& \mathrm{-3}\\ 3& 1& 0& 0\\ 0& 0& 0& 1\end{array}\right]$

$\mathrm{LUDecomposition}\left(A\,\mathrm{output}='\mathrm{NAG}'\right)$

$\left[\begin{array}{c}1\\ 2\\ 3\\ 4\end{array}\right],\left[\begin{array}{cccc}\mathrm{-2}& 3& 1& 4\\ 0& 1& 1& \mathrm{-3}\\ -\frac{3}{2}& \frac{11}{2}& \mathrm{-4}& \frac{45}{2}\\ 0& 0& 0& 1\end{array}\right]$