Added the make_symmetric() function and modified the eigenvalue decomposition

code so that it uses the more optimized paths when this matrix operator is
present.

--HG--
extra : convert_revision : svn%3Afdd8eb12-d10e-0410-9acb-85c331704f74/trunk%403816

dlib/matrix/matrix_eigenvalue.h

@@ -47,6 +47,11 @@ namespace dlib
             const matrix_exp<EXP>& A
         ); 
 
+        template <typename EXP>
+        eigenvalue_decomposition(
+            const matrix_op<op_make_symmetric<EXP> >& A
+        ); 
+
         long dim (
         ) const;
 
@@ -186,6 +191,45 @@ namespace dlib
         }
     }
 
+// ----------------------------------------------------------------------------------------
+
+    template <typename matrix_exp_type>
+    template <typename EXP>
+    eigenvalue_decomposition<matrix_exp_type>::
+    eigenvalue_decomposition(
+        const matrix_op<op_make_symmetric<EXP> >& A
+    ) 
+    {
+        COMPILE_TIME_ASSERT((is_same_type<type, typename EXP::type>::value));
+
+
+        // make sure requires clause is not broken
+        DLIB_ASSERT(A.nr() == A.nc() && A.size() > 0,
+            "\teigenvalue_decomposition::eigenvalue_decomposition(A)"
+            << "\n\tYou can only use this on square matrices"
+            << "\n\tA.nr():   " << A.nr()
+            << "\n\tA.nc():   " << A.nc()
+            << "\n\tA.size(): " << A.size()
+            << "\n\tthis:     " << this
+            );
+
+
+        n = A.nc();
+        V.set_size(n,n);
+        d.set_size(n);
+        e.set_size(n);
+
+
+        V = A;
+
+        // Tridiagonalize.
+        tred2();
+
+        // Diagonalize.
+        tql2();
+
+    }
+
 // ----------------------------------------------------------------------------------------
 
     template <typename matrix_exp_type>

dlib/matrix/matrix_la.h

@@ -1596,7 +1596,9 @@ convergence:
         }
         else
         {
-            return eigenvalue_decomposition<EXP>(m).get_real_eigenvalues();
+            // Call .ref() so that the symmetric matrix overload can take effect if m 
+            // has the appropriate type.
+            return eigenvalue_decomposition<EXP>(m.ref()).get_real_eigenvalues();
         }
     }
 

dlib/matrix/matrix_la_abstract.h

@@ -675,6 +675,35 @@ namespace dlib
                 - #get_v() == all the eigenvectors of A
         !*/
 
+        template <typename EXP>
+        eigenvalue_decomposition(
+            const matrix_op<op_make_symmetric<EXP> >& A
+        ); 
+        /*!
+            requires
+                - A.nr() == A.nc() 
+                - A.size() > 0
+                - EXP::type == eigenvalue_decomposition::type 
+            ensures
+                - #dim() == A.nr()
+                - computes the eigenvalue decomposition of the symmetric matrix A.  Does so
+                  using a method optimized for symmetric matrices.
+                - #get_eigenvalues() == the eigenvalues of A
+                - #get_v() == all the eigenvectors of A
+                - moreover, since A is symmetric there won't be any imaginary eigenvalues. So 
+                  we will have:
+                    - #get_imag_eigenvalues() == 0
+                    - #get_real_eigenvalues() == the eigenvalues of A
+                    - #get_pseudo_v() == all the eigenvectors of A
+                    - diagm(#get_real_eigenvalues()) == #get_pseudo_d()
+
+                Note that the symmetric matrix operator is created by the
+                dlib::make_symmetric() function.  This function simply reflects
+                the lower triangular part of a square matrix into the upper triangular
+                part to create a symmetric matrix.  It can also be used to denote that a 
+                matrix is already symmetric using the C++ type system.
+        !*/
+
         long dim (
         ) const;
         /*!

dlib/matrix/matrix_utilities.h

@@ -2732,6 +2732,43 @@ namespace dlib
         return matrix_op<op>(op(a.ref(),b.ref()));
     }
 
+// ----------------------------------------------------------------------------------------
+
+    template <typename M>
+    struct op_make_symmetric : basic_op_m<M>
+    {
+        op_make_symmetric ( const M& m_) : basic_op_m<M>(m_){}
+
+        const static long cost = M::cost+1;
+        typedef typename M::type type;
+        typedef const typename M::const_ret_type const_ret_type;
+        const_ret_type apply ( long r, long c) const
+        { 
+            if (r >= c)
+                return this->m(r,c);
+            else
+                return this->m(c,r);
+        }
+    };
+
+    template <
+        typename EXP
+        >
+    const matrix_op<op_make_symmetric<EXP> > make_symmetric (
+        const matrix_exp<EXP>& m
+    )
+    {
+        DLIB_ASSERT(m.nr() == m.nc(), 
+            "\tconst matrix make_symmetric(m)"
+            << "\n\t m must be a square matrix"
+            << "\n\t m.nr(): " << m.nr()
+            << "\n\t m.nc(): " << m.nc()
+            );
+
+        typedef op_make_symmetric<EXP> op;
+        return matrix_op<op>(op(m.ref()));
+    }
+
 // ----------------------------------------------------------------------------------------
 
     template <typename M>

dlib/matrix/matrix_utilities_abstract.h

@@ -144,6 +144,26 @@ namespace dlib
                         - M(r,c) == 0
     !*/
 
+// ----------------------------------------------------------------------------------------
+
+    const matrix_exp make_symmetric (
+        const matrix_exp& m
+    );
+    /*!
+        requires
+            - m.nr() == m.nc()
+              (i.e. m must be a square matrix)
+        ensures
+            - returns a matrix M such that:
+                - M::type == the same type that was in m
+                - M has the same dimensions as m
+                - M is a symmetric matrix, that is, M == trans(M) and
+                  it is constructed from the lower triangular part of m.  Specifically,
+                  we have:
+                    - lowerm(M) == lowerm(m)
+                    - upperm(M) == trans(lowerm(m))
+    !*/
+
 // ----------------------------------------------------------------------------------------
 
     template <