1 // This file is part of Eigen, a lightweight C++ template library
2 // for linear algebra.
3 //
4 // Copyright (C) 2008-2014 Gael Guennebaud <gael.guennebaud@inria.fr>
5 //
6 // This Source Code Form is subject to the terms of the Mozilla
7 // Public License v. 2.0. If a copy of the MPL was not distributed
8 // with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
9 
10 #ifndef EIGEN_SPARSEMATRIXBASE_H
11 #define EIGEN_SPARSEMATRIXBASE_H
12 
13 namespace Eigen {
14 
15 /** \ingroup SparseCore_Module
16   *
17   * \class SparseMatrixBase
18   *
19   * \brief Base class of any sparse matrices or sparse expressions
20   *
21   * \tparam Derived is the derived type, e.g. a sparse matrix type, or an expression, etc.
22   *
23   * This class can be extended with the help of the plugin mechanism described on the page
24   * \ref TopicCustomizing_Plugins by defining the preprocessor symbol \c EIGEN_SPARSEMATRIXBASE_PLUGIN.
25   */
26 template<typename Derived> class SparseMatrixBase
27   : public EigenBase<Derived>
28 {
29   public:
30 
31     typedef typename internal::traits<Derived>::Scalar Scalar;
32 
33     /** The numeric type of the expression' coefficients, e.g. float, double, int or std::complex<float>, etc.
34       *
35       * It is an alias for the Scalar type */
36     typedef Scalar value_type;
37 
38     typedef typename internal::packet_traits<Scalar>::type PacketScalar;
39     typedef typename internal::traits<Derived>::StorageKind StorageKind;
40 
41     /** The integer type used to \b store indices within a SparseMatrix.
42       * For a \c SparseMatrix<Scalar,Options,IndexType> it an alias of the third template parameter \c IndexType. */
43     typedef typename internal::traits<Derived>::StorageIndex StorageIndex;
44 
45     typedef typename internal::add_const_on_value_type_if_arithmetic<
46                          typename internal::packet_traits<Scalar>::type
47                      >::type PacketReturnType;
48 
49     typedef SparseMatrixBase StorageBaseType;
50 
51     typedef Matrix<StorageIndex,Dynamic,1> IndexVector;
52     typedef Matrix<Scalar,Dynamic,1> ScalarVector;
53 
54     template<typename OtherDerived>
55     Derived& operator=(const EigenBase<OtherDerived> &other);
56 
57     enum {
58 
59       RowsAtCompileTime = internal::traits<Derived>::RowsAtCompileTime,
60         /**< The number of rows at compile-time. This is just a copy of the value provided
61           * by the \a Derived type. If a value is not known at compile-time,
62           * it is set to the \a Dynamic constant.
63           * \sa MatrixBase::rows(), MatrixBase::cols(), ColsAtCompileTime, SizeAtCompileTime */
64 
65       ColsAtCompileTime = internal::traits<Derived>::ColsAtCompileTime,
66         /**< The number of columns at compile-time. This is just a copy of the value provided
67           * by the \a Derived type. If a value is not known at compile-time,
68           * it is set to the \a Dynamic constant.
69           * \sa MatrixBase::rows(), MatrixBase::cols(), RowsAtCompileTime, SizeAtCompileTime */
70 
71 
72       SizeAtCompileTime = (internal::size_at_compile_time<internal::traits<Derived>::RowsAtCompileTime,
73                                                    internal::traits<Derived>::ColsAtCompileTime>::ret),
74         /**< This is equal to the number of coefficients, i.e. the number of
75           * rows times the number of columns, or to \a Dynamic if this is not
76           * known at compile-time. \sa RowsAtCompileTime, ColsAtCompileTime */
77 
78       MaxRowsAtCompileTime = RowsAtCompileTime,
79       MaxColsAtCompileTime = ColsAtCompileTime,
80 
81       MaxSizeAtCompileTime = (internal::size_at_compile_time<MaxRowsAtCompileTime,
82                                                       MaxColsAtCompileTime>::ret),
83 
84       IsVectorAtCompileTime = RowsAtCompileTime == 1 || ColsAtCompileTime == 1,
85         /**< This is set to true if either the number of rows or the number of
86           * columns is known at compile-time to be equal to 1. Indeed, in that case,
87           * we are dealing with a column-vector (if there is only one column) or with
88           * a row-vector (if there is only one row). */
89 
90       Flags = internal::traits<Derived>::Flags,
91         /**< This stores expression \ref flags flags which may or may not be inherited by new expressions
92           * constructed from this one. See the \ref flags "list of flags".
93           */
94 
95       IsRowMajor = Flags&RowMajorBit ? 1 : 0,
96 
97       InnerSizeAtCompileTime = int(IsVectorAtCompileTime) ? int(SizeAtCompileTime)
98                              : int(IsRowMajor) ? int(ColsAtCompileTime) : int(RowsAtCompileTime),
99 
100       #ifndef EIGEN_PARSED_BY_DOXYGEN
101       _HasDirectAccess = (int(Flags)&DirectAccessBit) ? 1 : 0 // workaround sunCC
102       #endif
103     };
104 
105     /** \internal the return type of MatrixBase::adjoint() */
106     typedef typename internal::conditional<NumTraits<Scalar>::IsComplex,
107                         CwiseUnaryOp<internal::scalar_conjugate_op<Scalar>, Eigen::Transpose<const Derived> >,
108                         Transpose<const Derived>
109                      >::type AdjointReturnType;
110     typedef Transpose<Derived> TransposeReturnType;
111     typedef typename internal::add_const<Transpose<const Derived> >::type ConstTransposeReturnType;
112 
113     // FIXME storage order do not match evaluator storage order
114     typedef SparseMatrix<Scalar, Flags&RowMajorBit ? RowMajor : ColMajor, StorageIndex> PlainObject;
115 
116 #ifndef EIGEN_PARSED_BY_DOXYGEN
117     /** This is the "real scalar" type; if the \a Scalar type is already real numbers
118       * (e.g. int, float or double) then \a RealScalar is just the same as \a Scalar. If
119       * \a Scalar is \a std::complex<T> then RealScalar is \a T.
120       *
121       * \sa class NumTraits
122       */
123     typedef typename NumTraits<Scalar>::Real RealScalar;
124 
125     /** \internal the return type of coeff()
126       */
127     typedef typename internal::conditional<_HasDirectAccess, const Scalar&, Scalar>::type CoeffReturnType;
128 
129     /** \internal Represents a matrix with all coefficients equal to one another*/
130     typedef CwiseNullaryOp<internal::scalar_constant_op<Scalar>,Matrix<Scalar,Dynamic,Dynamic> > ConstantReturnType;
131 
132     /** type of the equivalent dense matrix */
133     typedef Matrix<Scalar,RowsAtCompileTime,ColsAtCompileTime> DenseMatrixType;
134     /** type of the equivalent square matrix */
135     typedef Matrix<Scalar,EIGEN_SIZE_MAX(RowsAtCompileTime,ColsAtCompileTime),
136                           EIGEN_SIZE_MAX(RowsAtCompileTime,ColsAtCompileTime)> SquareMatrixType;
137 
derived()138     inline const Derived& derived() const { return *static_cast<const Derived*>(this); }
derived()139     inline Derived& derived() { return *static_cast<Derived*>(this); }
const_cast_derived()140     inline Derived& const_cast_derived() const
141     { return *static_cast<Derived*>(const_cast<SparseMatrixBase*>(this)); }
142 
143     typedef EigenBase<Derived> Base;
144 
145 #endif // not EIGEN_PARSED_BY_DOXYGEN
146 
147 #define EIGEN_CURRENT_STORAGE_BASE_CLASS Eigen::SparseMatrixBase
148 #ifdef EIGEN_PARSED_BY_DOXYGEN
149 #define EIGEN_DOC_UNARY_ADDONS(METHOD,OP)           /** <p>This method does not change the sparsity of \c *this: the OP is applied to explicitly stored coefficients only. \sa SparseCompressedBase::coeffs() </p> */
150 #define EIGEN_DOC_BLOCK_ADDONS_NOT_INNER_PANEL      /** <p> \warning This method returns a read-only expression for any sparse matrices. \sa \ref TutorialSparse_SubMatrices "Sparse block operations" </p> */
151 #define EIGEN_DOC_BLOCK_ADDONS_INNER_PANEL_IF(COND) /** <p> \warning This method returns a read-write expression for COND sparse matrices only. Otherwise, the returned expression is read-only. \sa \ref TutorialSparse_SubMatrices "Sparse block operations" </p> */
152 #else
153 #define EIGEN_DOC_UNARY_ADDONS(X,Y)
154 #define EIGEN_DOC_BLOCK_ADDONS_NOT_INNER_PANEL
155 #define EIGEN_DOC_BLOCK_ADDONS_INNER_PANEL_IF(COND)
156 #endif
157 #   include "../plugins/CommonCwiseUnaryOps.h"
158 #   include "../plugins/CommonCwiseBinaryOps.h"
159 #   include "../plugins/MatrixCwiseUnaryOps.h"
160 #   include "../plugins/MatrixCwiseBinaryOps.h"
161 #   include "../plugins/BlockMethods.h"
162 #   ifdef EIGEN_SPARSEMATRIXBASE_PLUGIN
163 #     include EIGEN_SPARSEMATRIXBASE_PLUGIN
164 #   endif
165 #undef EIGEN_CURRENT_STORAGE_BASE_CLASS
166 #undef EIGEN_DOC_UNARY_ADDONS
167 #undef EIGEN_DOC_BLOCK_ADDONS_NOT_INNER_PANEL
168 #undef EIGEN_DOC_BLOCK_ADDONS_INNER_PANEL_IF
169 
170     /** \returns the number of rows. \sa cols() */
rows()171     inline Index rows() const { return derived().rows(); }
172     /** \returns the number of columns. \sa rows() */
cols()173     inline Index cols() const { return derived().cols(); }
174     /** \returns the number of coefficients, which is \a rows()*cols().
175       * \sa rows(), cols(). */
size()176     inline Index size() const { return rows() * cols(); }
177     /** \returns true if either the number of rows or the number of columns is equal to 1.
178       * In other words, this function returns
179       * \code rows()==1 || cols()==1 \endcode
180       * \sa rows(), cols(), IsVectorAtCompileTime. */
isVector()181     inline bool isVector() const { return rows()==1 || cols()==1; }
182     /** \returns the size of the storage major dimension,
183       * i.e., the number of columns for a columns major matrix, and the number of rows otherwise */
outerSize()184     Index outerSize() const { return (int(Flags)&RowMajorBit) ? this->rows() : this->cols(); }
185     /** \returns the size of the inner dimension according to the storage order,
186       * i.e., the number of rows for a columns major matrix, and the number of cols otherwise */
innerSize()187     Index innerSize() const { return (int(Flags)&RowMajorBit) ? this->cols() : this->rows(); }
188 
isRValue()189     bool isRValue() const { return m_isRValue; }
markAsRValue()190     Derived& markAsRValue() { m_isRValue = true; return derived(); }
191 
SparseMatrixBase()192     SparseMatrixBase() : m_isRValue(false) { /* TODO check flags */ }
193 
194 
195     template<typename OtherDerived>
196     Derived& operator=(const ReturnByValue<OtherDerived>& other);
197 
198     template<typename OtherDerived>
199     inline Derived& operator=(const SparseMatrixBase<OtherDerived>& other);
200 
201     inline Derived& operator=(const Derived& other);
202 
203   protected:
204 
205     template<typename OtherDerived>
206     inline Derived& assign(const OtherDerived& other);
207 
208     template<typename OtherDerived>
209     inline void assignGeneric(const OtherDerived& other);
210 
211   public:
212 
213     friend std::ostream & operator << (std::ostream & s, const SparseMatrixBase& m)
214     {
215       typedef typename Derived::Nested Nested;
216       typedef typename internal::remove_all<Nested>::type NestedCleaned;
217 
218       if (Flags&RowMajorBit)
219       {
220         Nested nm(m.derived());
221         internal::evaluator<NestedCleaned> thisEval(nm);
222         for (Index row=0; row<nm.outerSize(); ++row)
223         {
224           Index col = 0;
225           for (typename internal::evaluator<NestedCleaned>::InnerIterator it(thisEval, row); it; ++it)
226           {
227             for ( ; col<it.index(); ++col)
228               s << "0 ";
229             s << it.value() << " ";
230             ++col;
231           }
232           for ( ; col<m.cols(); ++col)
233             s << "0 ";
234           s << std::endl;
235         }
236       }
237       else
238       {
239         Nested nm(m.derived());
240         internal::evaluator<NestedCleaned> thisEval(nm);
241         if (m.cols() == 1) {
242           Index row = 0;
243           for (typename internal::evaluator<NestedCleaned>::InnerIterator it(thisEval, 0); it; ++it)
244           {
245             for ( ; row<it.index(); ++row)
246               s << "0" << std::endl;
247             s << it.value() << std::endl;
248             ++row;
249           }
250           for ( ; row<m.rows(); ++row)
251             s << "0" << std::endl;
252         }
253         else
254         {
255           SparseMatrix<Scalar, RowMajorBit, StorageIndex> trans = m;
256           s << static_cast<const SparseMatrixBase<SparseMatrix<Scalar, RowMajorBit, StorageIndex> >&>(trans);
257         }
258       }
259       return s;
260     }
261 
262     template<typename OtherDerived>
263     Derived& operator+=(const SparseMatrixBase<OtherDerived>& other);
264     template<typename OtherDerived>
265     Derived& operator-=(const SparseMatrixBase<OtherDerived>& other);
266 
267     template<typename OtherDerived>
268     Derived& operator+=(const DiagonalBase<OtherDerived>& other);
269     template<typename OtherDerived>
270     Derived& operator-=(const DiagonalBase<OtherDerived>& other);
271 
272     template<typename OtherDerived>
273     Derived& operator+=(const EigenBase<OtherDerived> &other);
274     template<typename OtherDerived>
275     Derived& operator-=(const EigenBase<OtherDerived> &other);
276 
277     Derived& operator*=(const Scalar& other);
278     Derived& operator/=(const Scalar& other);
279 
280     template<typename OtherDerived> struct CwiseProductDenseReturnType {
281       typedef CwiseBinaryOp<internal::scalar_product_op<typename ScalarBinaryOpTraits<
282                                                           typename internal::traits<Derived>::Scalar,
283                                                           typename internal::traits<OtherDerived>::Scalar
284                                                         >::ReturnType>,
285                             const Derived,
286                             const OtherDerived
287                           > Type;
288     };
289 
290     template<typename OtherDerived>
291     EIGEN_STRONG_INLINE const typename CwiseProductDenseReturnType<OtherDerived>::Type
292     cwiseProduct(const MatrixBase<OtherDerived> &other) const;
293 
294     // sparse * diagonal
295     template<typename OtherDerived>
296     const Product<Derived,OtherDerived>
297     operator*(const DiagonalBase<OtherDerived> &other) const
298     { return Product<Derived,OtherDerived>(derived(), other.derived()); }
299 
300     // diagonal * sparse
301     template<typename OtherDerived> friend
302     const Product<OtherDerived,Derived>
303     operator*(const DiagonalBase<OtherDerived> &lhs, const SparseMatrixBase& rhs)
304     { return Product<OtherDerived,Derived>(lhs.derived(), rhs.derived()); }
305 
306     // sparse * sparse
307     template<typename OtherDerived>
308     const Product<Derived,OtherDerived,AliasFreeProduct>
309     operator*(const SparseMatrixBase<OtherDerived> &other) const;
310 
311     // sparse * dense
312     template<typename OtherDerived>
313     const Product<Derived,OtherDerived>
314     operator*(const MatrixBase<OtherDerived> &other) const
315     { return Product<Derived,OtherDerived>(derived(), other.derived()); }
316 
317     // dense * sparse
318     template<typename OtherDerived> friend
319     const Product<OtherDerived,Derived>
320     operator*(const MatrixBase<OtherDerived> &lhs, const SparseMatrixBase& rhs)
321     { return Product<OtherDerived,Derived>(lhs.derived(), rhs.derived()); }
322 
323      /** \returns an expression of P H P^-1 where H is the matrix represented by \c *this */
twistedBy(const PermutationMatrix<Dynamic,Dynamic,StorageIndex> & perm)324     SparseSymmetricPermutationProduct<Derived,Upper|Lower> twistedBy(const PermutationMatrix<Dynamic,Dynamic,StorageIndex>& perm) const
325     {
326       return SparseSymmetricPermutationProduct<Derived,Upper|Lower>(derived(), perm);
327     }
328 
329     template<typename OtherDerived>
330     Derived& operator*=(const SparseMatrixBase<OtherDerived>& other);
331 
332     template<int Mode>
333     inline const TriangularView<const Derived, Mode> triangularView() const;
334 
335     template<unsigned int UpLo> struct SelfAdjointViewReturnType { typedef SparseSelfAdjointView<Derived, UpLo> Type; };
336     template<unsigned int UpLo> struct ConstSelfAdjointViewReturnType { typedef const SparseSelfAdjointView<const Derived, UpLo> Type; };
337 
338     template<unsigned int UpLo> inline
339     typename ConstSelfAdjointViewReturnType<UpLo>::Type selfadjointView() const;
340     template<unsigned int UpLo> inline
341     typename SelfAdjointViewReturnType<UpLo>::Type selfadjointView();
342 
343     template<typename OtherDerived> Scalar dot(const MatrixBase<OtherDerived>& other) const;
344     template<typename OtherDerived> Scalar dot(const SparseMatrixBase<OtherDerived>& other) const;
345     RealScalar squaredNorm() const;
346     RealScalar norm()  const;
347     RealScalar blueNorm() const;
348 
transpose()349     TransposeReturnType transpose() { return TransposeReturnType(derived()); }
transpose()350     const ConstTransposeReturnType transpose() const { return ConstTransposeReturnType(derived()); }
adjoint()351     const AdjointReturnType adjoint() const { return AdjointReturnType(transpose()); }
352 
353     // inner-vector
354     typedef Block<Derived,IsRowMajor?1:Dynamic,IsRowMajor?Dynamic:1,true>       InnerVectorReturnType;
355     typedef Block<const Derived,IsRowMajor?1:Dynamic,IsRowMajor?Dynamic:1,true> ConstInnerVectorReturnType;
356     InnerVectorReturnType innerVector(Index outer);
357     const ConstInnerVectorReturnType innerVector(Index outer) const;
358 
359     // set of inner-vectors
360     typedef Block<Derived,Dynamic,Dynamic,true> InnerVectorsReturnType;
361     typedef Block<const Derived,Dynamic,Dynamic,true> ConstInnerVectorsReturnType;
362     InnerVectorsReturnType innerVectors(Index outerStart, Index outerSize);
363     const ConstInnerVectorsReturnType innerVectors(Index outerStart, Index outerSize) const;
364 
toDense()365     DenseMatrixType toDense() const
366     {
367       return DenseMatrixType(derived());
368     }
369 
370     template<typename OtherDerived>
371     bool isApprox(const SparseMatrixBase<OtherDerived>& other,
372                   const RealScalar& prec = NumTraits<Scalar>::dummy_precision()) const;
373 
374     template<typename OtherDerived>
375     bool isApprox(const MatrixBase<OtherDerived>& other,
376                   const RealScalar& prec = NumTraits<Scalar>::dummy_precision()) const
377     { return toDense().isApprox(other,prec); }
378 
379     /** \returns the matrix or vector obtained by evaluating this expression.
380       *
381       * Notice that in the case of a plain matrix or vector (not an expression) this function just returns
382       * a const reference, in order to avoid a useless copy.
383       */
eval()384     inline const typename internal::eval<Derived>::type eval() const
385     { return typename internal::eval<Derived>::type(derived()); }
386 
387     Scalar sum() const;
388 
389     inline const SparseView<Derived>
390     pruned(const Scalar& reference = Scalar(0), const RealScalar& epsilon = NumTraits<Scalar>::dummy_precision()) const;
391 
392   protected:
393 
394     bool m_isRValue;
395 
convert_index(const Index idx)396     static inline StorageIndex convert_index(const Index idx) {
397       return internal::convert_index<StorageIndex>(idx);
398     }
399   private:
400     template<typename Dest> void evalTo(Dest &) const;
401 };
402 
403 } // end namespace Eigen
404 
405 #endif // EIGEN_SPARSEMATRIXBASE_H
406