%==========================================================================
% File Name     : <U_triangulate.m>
% Usage         : [A, xid, rk] = U_triangulate(A, maxC, bUnit)
% Description   : This matrix returns a upper triangular matrix
% transformation.
%
% Using standard gaussian elimination procedures it turns the original
% matrix in upper triangular form (i.e. everything below the main diagonal
% are nil). It also returns the rearranged column indices, something that
% matlab doesn't. The main diagonal elements are scaled to 1 to enable easy
% solution/substitution.
%
% The 3rd optional argument bUnit if ~0 it will complete the
% triangularization of the upper part too, ending up with a unit matrix
% which is useful in many cases.
%
% maxC is the maximum column index that is considered for swappings
% e.g. if A includes the RHS of a system of equations the last column
% shouldn't be included as a candidate. Note that xid only monitors these
% maxC columns.
%
% If the source table A has rank deficiency, the triangulation still
% succeeds but the bottom rows will be left with zeros. The true rank is
% returned too.
%--------------------------------------------------------------------------
% Author        : Richard Oberdieck, Nikolaos A. Diangelakis
% Office        : Giesecke Engineering Research Building, Texas A&M, USA.
% Mail          : paroc@tamu.edu
%--------------------------------------------------------------------------
% Last Modified   | Author  | Description
%-----------------+---------+----------------------------------------------
% 17-Jun-2004     | N/A     | Initial Version
%==========================================================================