core/vnl/vnl_rank.h
Go to the documentation of this file.
00001 // This is core/vnl/vnl_rank.h
00002 #ifndef vnl_rank_h_
00003 #define vnl_rank_h_
00004 //:
00005 //  \file
00006 //  \author Peter Vanroose, Leuven
00007 //  \date   27 March 2003
00008 //  \brief Direct computation of the rank of a matrix, without using svd
00009 //
00010 //  The (row) rank of a matrix is its number of linearly independent rows.
00011 //  This turns out to be equal to the number of linearly independent columns,
00012 //  i.e., the column rank, so it is just called the rank of the matrix.
00013 //  This can be computed by row-reducing (or column-reducing) the matrix
00014 //  and then counting the number of non-zero rows (or columns).
00015 
00016 #include <vnl/vnl_matrix.h>
00017 
00018 typedef enum { vnl_rank_row, vnl_rank_column, vnl_rank_both } vnl_rank_type;
00019 typedef enum { vnl_rank_pivot_one, vnl_rank_pivot_all } vnl_rank_pivot_type;
00020 
00021 //: Returns the rank of a matrix
00022 //  By default, the row rank of the matrix is determined.
00023 //  Specify vnl_rank_column to obtain the column rank.
00024 //
00025 // \relatesalso vnl_matrix
00026 template <class T>
00027 unsigned int vnl_rank(vnl_matrix<T> const& mat, vnl_rank_type = vnl_rank_both);
00028 
00029 //: Row reduce a matrix.
00030 //  First try to use 1 or -1 as pivot element in each row, to avoid divisions;
00031 //  then use any nonzero element as candidate pivot.
00032 //  Repeat this process until the matrix does not change any more.
00033 //  At that point, the matrix spans the same row space as before and contains
00034 //  as many zeros as possible.
00035 //
00036 //  When specifying vnl_rank_pivot_one is given as second argument,
00037 //  only elements with value 1 or -1 are used as candidate pivot elements.
00038 //
00039 //  Note that for integer matrices, the resulting matrix is still integer,
00040 //  and is guaranteed to be row equivalent with the original matrix.
00041 //
00042 // \relatesalso vnl_matrix
00043 //
00044 template <class T>
00045 vnl_matrix<T> vnl_rank_row_reduce(vnl_matrix<T> const& mat,
00046                                   vnl_rank_pivot_type = vnl_rank_pivot_all);
00047 
00048 //: Column reduce a matrix.
00049 //
00050 // \relatesalso vnl_matrix
00051 //
00052 template <class T>
00053 vnl_matrix<T> vnl_rank_column_reduce(vnl_matrix<T> const& mat,
00054                                      vnl_rank_pivot_type = vnl_rank_pivot_all);
00055 
00056 //: Row and column reduce a matrix.
00057 //  Perform both row reduction and column reduction on a matrix.
00058 //  The resulting matrix will in general no longer span the same row space
00059 //  (or column space) as the original matrix, but the rank will not have
00060 //  changed, and the number of nonzero elements will be minimal (viz at most
00061 //  one per row and one per column).
00062 //
00063 // \relatesalso vnl_matrix
00064 //
00065 template <class T>
00066 vnl_matrix<T> vnl_rank_row_column_reduce(vnl_matrix<T> const& mat,
00067                                          vnl_rank_pivot_type = vnl_rank_pivot_all);
00068 
00069 #define VNL_RANK_INSTANTIATE(T) extern "please #include vnl/vnl_rank.txx instead"
00070 
00071 #endif // vnl_rank_h_