Tpetra Matrix/Vector Services: Tpetra_MultiVector

00001 // @HEADER
00002 // ***********************************************************************
00003 // 
00004 //          Tpetra: Templated Linear Algebra Services Package
00005 //                 Copyright (2008) Sandia Corporation
00006 // 
00007 // Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
00008 // license for use of this work by or on behalf of the U.S. Government.
00009 // 
00010 // This library is free software; you can redistribute it and/or modify
00011 // it under the terms of the GNU Lesser General Public License as
00012 // published by the Free Software Foundation; either version 2.1 of the
00013 // License, or (at your option) any later version.
00014 //  
00015 // This library is distributed in the hope that it will be useful, but
00016 // WITHOUT ANY WARRANTY; without even the implied warranty of
00017 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00018 // Lesser General Public License for more details.
00019 //  
00020 // You should have received a copy of the GNU Lesser General Public
00021 // License along with this library; if not, write to the Free Software
00022 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
00023 // USA
00024 // Questions? Contact Michael A. Heroux (maherou@sandia.gov) 
00025 // 
00026 // ***********************************************************************
00027 // @HEADER
00028 
00029 #ifndef TPETRA_MULTIVECTOR_DECL_HPP
00030 #define TPETRA_MULTIVECTOR_DECL_HPP
00031 
00032 #include <Teuchos_LabeledObject.hpp>
00033 #include <Teuchos_DataAccess.hpp>
00034 #include <Teuchos_BLAS_types.hpp>
00035 #include <Teuchos_Range1D.hpp>
00036 
00037 #include <Kokkos_MultiVector.hpp>
00038 #include <Kokkos_DefaultArithmetic.hpp>
00039 
00040 #include "Tpetra_ConfigDefs.hpp"
00041 #include "Tpetra_DistObject.hpp"
00042 #include "Tpetra_Map.hpp"
00043 
00044 // TODO: add principal use case instructions for memory management interfaces (view/copy extraction)
00045 // TODO: expand user-visible documentation 
00046 
00047 namespace Tpetra {
00048 
00049 #ifndef DOXYGEN_SHOULD_SKIP_THIS
00050   // forward declaration of Vector, needed to prevent circular inclusions
00051   template<class S, class LO, class GO, class N> class Vector;
00052 #endif
00053 
00055 
00060   template <class Scalar, class LocalOrdinal=int, class GlobalOrdinal=LocalOrdinal, class Node=Kokkos::DefaultNode::DefaultNodeType>
00061   class MultiVector : public DistObject<Scalar,LocalOrdinal,GlobalOrdinal,Node> {
00062 
00063     public:
00064       typedef Scalar        scalar_type;
00065       typedef LocalOrdinal  local_ordinal_type;
00066       typedef GlobalOrdinal global_ordinal_type;
00067       typedef Node          node_type;
00068 
00070 
00071 
00073     MultiVector(const Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > &map, size_t NumVectors, bool zeroOut=true);
00074 
00076     MultiVector(const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> &source);
00077 
00079 
00080     MultiVector(const Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > &map, const Teuchos::ArrayView<const Scalar> &A, size_t LDA, size_t NumVectors);
00081 
00083 
00084     MultiVector(const Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > &map, const Teuchos::ArrayView<const Teuchos::ArrayView<const Scalar> > &ArrayOfPtrs, size_t NumVectors);
00085 
00087     virtual ~MultiVector();
00088 
00090 
00092 
00093 
00095 
00097     void replaceGlobalValue(GlobalOrdinal globalRow, size_t vectorIndex, const Scalar &value);
00098 
00100 
00102     void sumIntoGlobalValue(GlobalOrdinal globalRow, size_t vectorIndex, const Scalar &value);
00103 
00105 
00107     void replaceLocalValue(LocalOrdinal myRow, size_t vectorIndex, const Scalar &value);
00108 
00110 
00112     void sumIntoLocalValue(LocalOrdinal myRow, size_t vectorIndex, const Scalar &value);
00113 
00115     void putScalar(const Scalar &value);
00116 
00118     void randomize();
00119 
00121     void replaceMap(const Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > &map);
00122 
00124     void reduce();
00125 
00127 
00129     MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node>& operator=(const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> &source);
00130 
00132 
00134 
00142 
00144     Teuchos::RCP<MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> > subCopy(const Teuchos::Range1D &colRng) const;
00145 
00147     Teuchos::RCP<MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> > subCopy(const Teuchos::ArrayView<const size_t> &cols) const;
00148 
00150     Teuchos::RCP<const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> > subView(const Teuchos::Range1D &colRng) const;
00151 
00153     Teuchos::RCP<const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> > subView(const Teuchos::ArrayView<const size_t> &cols) const;
00154 
00156     Teuchos::RCP<MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> > subViewNonConst(const Teuchos::Range1D &colRng);
00157 
00159     Teuchos::RCP<MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> > subViewNonConst(const Teuchos::ArrayView<const size_t> &cols);
00160 
00162 
00170     Teuchos::RCP<const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> > offsetView(const Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > &subMap, size_t offset) const;
00171 
00173 
00181     Teuchos::RCP<MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> > offsetViewNonConst(const Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > &subMap, size_t offset);
00182 
00184     Teuchos::RCP<const Vector<Scalar,LocalOrdinal,GlobalOrdinal,Node> > getVector(size_t j) const;
00185 
00187     Teuchos::RCP<Vector<Scalar,LocalOrdinal,GlobalOrdinal,Node> > getVectorNonConst(size_t j);
00188 
00191     Teuchos::ArrayRCP<const Scalar> getData(size_t j) const;
00192 
00195     Teuchos::ArrayRCP<Scalar> getDataNonConst(size_t j);
00196 
00198     void get1dCopy(Teuchos::ArrayView<Scalar> A, size_t LDA) const;
00199 
00201     void get2dCopy(Teuchos::ArrayView<const Teuchos::ArrayView<Scalar> > ArrayOfPtrs) const;
00202 
00204     Teuchos::ArrayRCP<const Scalar> get1dView() const;
00205 
00207     Teuchos::ArrayRCP<Teuchos::ArrayRCP<const Scalar> > get2dView() const;
00208 
00210     Teuchos::ArrayRCP<Scalar> get1dViewNonConst();
00211 
00213     Teuchos::ArrayRCP<Teuchos::ArrayRCP<Scalar> > get2dViewNonConst();
00214 
00216     const Kokkos::MultiVector<Scalar,Node> & getLocalMV() const;
00217 
00219     Kokkos::MultiVector<Scalar,Node> & getLocalMVNonConst();
00220 
00222 
00224 
00225 
00227     void dot(const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> &A, const Teuchos::ArrayView<Scalar> &dots) const;
00228 
00230     void abs(const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> &A);
00231 
00233     void reciprocal(const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> &A);
00234 
00236     void scale(const Scalar &alpha);
00237 
00239     void scale(Teuchos::ArrayView<const Scalar> alpha);
00240 
00242     void scale(const Scalar &alpha, const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> &A);
00243 
00245     void update(const Scalar &alpha, const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> &A, const Scalar &beta);
00246 
00248     void update(const Scalar &alpha, const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> &A, const Scalar &beta, const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> &B, const Scalar &gamma);
00249 
00251     void norm1(const Teuchos::ArrayView<typename Teuchos::ScalarTraits<Scalar>::magnitudeType> &norms) const;
00252 
00254     void norm2(const Teuchos::ArrayView<typename Teuchos::ScalarTraits<Scalar>::magnitudeType> &norms) const;
00255 
00257     void normInf(const Teuchos::ArrayView<typename Teuchos::ScalarTraits<Scalar>::magnitudeType> &norms) const;
00258 
00260     void normWeighted(const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> &weights, const Teuchos::ArrayView<typename Teuchos::ScalarTraits<Scalar>::magnitudeType> &norms) const;
00261 
00263     void meanValue(const Teuchos::ArrayView<Scalar> &means) const;
00264 
00266     void multiply(Teuchos::ETransp transA, Teuchos::ETransp transB, const Scalar &alpha, const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> &A, const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> &B, const Scalar &beta);
00267 
00269 
00274     void elementWiseMultiply(Scalar scalarAB, const Vector<Scalar,LocalOrdinal,GlobalOrdinal,Node> &A, const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> &B, Scalar scalarThis);
00276 
00278 
00279 
00281     size_t getNumVectors() const;
00282 
00284     size_t getLocalLength() const;
00285 
00287     global_size_t getGlobalLength() const;
00288 
00290     size_t getStride() const;
00291 
00293     bool isConstantStride() const;
00294 
00296 
00298 
00299 
00301     std::string description() const;
00302 
00304     void describe(Teuchos::FancyOStream &out, const Teuchos::EVerbosityLevel verbLevel=Teuchos::Describable::verbLevel_default) const;
00305 
00307 
00308     protected:
00309 
00310     typedef Kokkos::MultiVector<Scalar,Node> KMV;
00311     typedef Kokkos::DefaultArithmetic<KMV>   MVT;
00312 
00313     KMV lclMV_;
00314     Teuchos::Array<size_t> whichVectors_;
00315 
00316     template <class T>
00318     Teuchos::ArrayRCP<T> getSubArrayRCP(Teuchos::ArrayRCP<T> arr, size_t j) const;
00319 
00321     MultiVector(const Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > &map,
00322                 Teuchos::ArrayRCP<Scalar> data, size_t LDA, Teuchos::ArrayView<const size_t> whichVectors);
00323 
00325     MultiVector(const Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > &map,
00326                 Teuchos::ArrayRCP<Scalar> data, size_t LDA, size_t NumVectors);
00327 
00328     // four functions needed for DistObject derivation
00329     bool checkSizes(const DistObject<Scalar,LocalOrdinal,GlobalOrdinal,Node> &sourceObj);
00330 
00331     void copyAndPermute(const DistObject<Scalar,LocalOrdinal,GlobalOrdinal,Node> &sourceObj,
00332                         size_t numSameIDs,
00333                         const Teuchos::ArrayView<const LocalOrdinal> &permuteToLIDs,
00334                         const Teuchos::ArrayView<const LocalOrdinal> &permuteFromLIDs);
00335 
00336     void packAndPrepare(const DistObject<Scalar,LocalOrdinal,GlobalOrdinal,Node> &sourceObj,
00337                         const Teuchos::ArrayView<const LocalOrdinal> &exportLIDs,
00338                         Teuchos::Array<Scalar> &exports,
00339                         const Teuchos::ArrayView<size_t> &numExportPacketsPerLID,
00340                         size_t& constantNumPackets,
00341                         Distributor &distor);
00342 
00343     void unpackAndCombine(const Teuchos::ArrayView<const LocalOrdinal> &importLIDs,
00344                           const Teuchos::ArrayView<const Scalar> &imports,
00345                           const Teuchos::ArrayView<size_t> &numPacketsPerLID,
00346                           size_t constantNumPackets,
00347                           Distributor &distor,
00348                           CombineMode CM);
00349 
00350   mutable Teuchos::ArrayRCP<Scalar> ncview_;
00351   mutable Teuchos::ArrayRCP<const Scalar> cview_;
00352 
00353   void createViews() const;
00354   void createViewsNonConst(Kokkos::ReadWriteOption rwo);
00355   void releaseViews() const;
00356 
00357   }; // class MultiVector
00358 
00362   template <class Scalar, class LocalOrdinal, class GlobalOrdinal, class Node>
00363   Teuchos::RCP< MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> >
00364   createMultiVector(const Teuchos::RCP< const Map<LocalOrdinal,GlobalOrdinal,Node> > &map, size_t numVectors);
00365 
00366 
00367 } // namespace Tpetra
00368 
00369 
00370 #endif // TPETRA_MULTIVECTOR_DECL_HPP