source: trunk/yat/utility/SVD.h @ 687

#ifndef _theplu_yat_utility_svd_
#define _theplu_yat_utility_svd_

// $Id: SVD.h 687 2006-10-16 23:51:10Z jari $

/*
  Copyright (C) The authors contributing to this file.

  This file is part of the yat library, http://lev.thep.lu.se/trac/yat

  The yat library is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License as
  published by the Free Software Foundation; either version 2 of the
  License, or (at your option) any later version.

  The yat library is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
  02111-1307, USA.
*/

#include "matrix.h"
#include "vector.h"

#include <gsl/gsl_linalg.h>

namespace theplu {
namespace yat {
namespace utility {

  // Jari check that interface is complete

  /**
     Class encapsulating GSL methods for singular value decomposition,
     SVD.

     A = U S V' = (MxN)(NxN)(NxN) = (MxN)\n   

     A = Matrix to be decomposed, size MxN\n
     U = Orthogonal matrix, size MxN\n
     S = Diagonal matrix of singular values, size NxN\n
     V = Orthogonal matrix, size NxN\n
  */

  class SVD
  {
  public:

    ///
    /// A number of SVD algorithms are implemented in GSL. They have
    /// their strengths and weaknesses, check the GSL documentation.
    ///
    /// There are restrictions on the matrix dimensions depending on
    /// which SVD algorithm is used. From the GSL's SVD source code
    /// one finds that the Golub-Reinsch algorithm implementation will
    /// not work on matrices with fewer rows than columns, the same is
    /// also true for the modified Golub-Reinsch algorithm.
    ///
    /// @see GSL's SVD documentation.
    ///
    enum SVDalgorithm {
      GolubReinsch,
      ModifiedGolubReinsch,
      Jacobi
    };

    ///
    /// Constructs an SVD object using the matrix A as only input. The
    /// input matrix is copied for further use in the object.
    ///
    inline SVD(const utility::matrix& Ain)
      : U_(Ain), V_(Ain.columns(),Ain.columns()), s_(Ain.columns()) {}

    inline ~SVD(void) {}

    ///
    /// This function will perform SVD with the method specified by \a
    /// algo.
    ///
    /// @return Whatever GSL returns.
    ///
    int decompose(SVDalgorithm algo=GolubReinsch);

    ///
    /// Access to the s vector.
    ///
    /// @return A copy of the s vector.
    ///
    /// @note If decompose() has not been run the outcome of the call
    /// is undefined.
    ///
    inline const utility::vector& s(void) const { return s_; }

    ///
    /// Solve the system \f$ Ax=b \f$ using the decomposition of A.
    ///
    /// @note If decompose() has not been run the outcome of the call
    /// is undefined.
    ///
    /// @return Whatever GSL returns.
    ///
    inline int solve(utility::vector b, utility::vector x)
      { return gsl_linalg_SV_solve(U_.gsl_matrix_p(), V_.gsl_matrix_p(), 
                                   s_.gsl_vector_p(), b.gsl_vector_p(),
                                   x.gsl_vector_p()); }

    ///
    /// Access to the U matrix.
    ///
    /// @return A copy of the U matrix.
    ///
    /// @note If decompose() has not been run the outcome of the call
    /// is undefined.
    ///
    inline const utility::matrix& U(void) const { return U_; }

    ///
    /// Access to the V matrix.
    ///
    /// @return A copy of the V matrix.
    ///
    /// @note If decompose() has not been run the outcome of the call
    /// is undefined.
    ///
    inline const utility::matrix& V(void) const { return V_; }

  private:
    inline int jacobi(void)
      { return gsl_linalg_SV_decomp_jacobi(U_.gsl_matrix_p(), V_.gsl_matrix_p(), 
                                           s_.gsl_vector_p()); }
    int golub_reinsch(void);
    int modified_golub_reinsch(void);

    utility::matrix U_, V_;
    utility::vector s_;
  };  

}}} // of namespace utility, yat, and theplu

#endif