Tpetra Matrix/Vector Services Version of the Day
Tpetra_MultiVector_decl.hpp
00001 // @HEADER
00002 // ***********************************************************************
00003 // 
00004 //          Tpetra: Templated Linear Algebra Services Package
00005 //                 Copyright (2008) Sandia Corporation
00006 // 
00007 // Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
00008 // the U.S. Government retains certain rights in this software.
00009 // 
00010 // Redistribution and use in source and binary forms, with or without
00011 // modification, are permitted provided that the following conditions are
00012 // met:
00013 //
00014 // 1. Redistributions of source code must retain the above copyright
00015 // notice, this list of conditions and the following disclaimer.
00016 //
00017 // 2. Redistributions in binary form must reproduce the above copyright
00018 // notice, this list of conditions and the following disclaimer in the
00019 // documentation and/or other materials provided with the distribution.
00020 //
00021 // 3. Neither the name of the Corporation nor the names of the
00022 // contributors may be used to endorse or promote products derived from
00023 // this software without specific prior written permission.
00024 //
00025 // THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
00026 // EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00027 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
00028 // PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
00029 // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
00030 // EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
00031 // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
00032 // PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
00033 // LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
00034 // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00035 // SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00036 //
00037 // Questions? Contact Michael A. Heroux (maherou@sandia.gov) 
00038 // 
00039 // ************************************************************************
00040 // @HEADER
00041 
00042 #ifndef TPETRA_MULTIVECTOR_DECL_HPP
00043 #define TPETRA_MULTIVECTOR_DECL_HPP
00044 
00045 #include <Teuchos_LabeledObject.hpp>
00046 #include <Teuchos_DataAccess.hpp>
00047 #include <Teuchos_BLAS_types.hpp>
00048 #include <Teuchos_Range1D.hpp>
00049 
00050 #include <Kokkos_MultiVector.hpp>
00051 #include <Kokkos_DefaultArithmetic.hpp>
00052 
00053 #include "Tpetra_ConfigDefs.hpp"
00054 #include "Tpetra_DistObject.hpp"
00055 #include "Tpetra_Map.hpp"
00056 
00057 // TODO: add principal use case instructions for memory management interfaces (view/copy extraction)
00058 // TODO: expand user-visible documentation 
00059 
00060 namespace Tpetra {
00061 
00062 #ifndef DOXYGEN_SHOULD_SKIP_THIS
00063   // forward declaration of Vector, needed to prevent circular inclusions
00064   template<class S, class LO, class GO, class N> class Vector;
00065 #endif
00066 
00068 
00073   template <class Scalar, class LocalOrdinal=int, class GlobalOrdinal=LocalOrdinal, class Node=Kokkos::DefaultNode::DefaultNodeType>
00074   class MultiVector : public DistObject<Scalar,LocalOrdinal,GlobalOrdinal,Node> {
00075 
00076     public:
00077       typedef Scalar        scalar_type;
00078       typedef LocalOrdinal  local_ordinal_type;
00079       typedef GlobalOrdinal global_ordinal_type;
00080       typedef Node          node_type;
00081 
00083 
00084 
00086     MultiVector(const Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > &map, size_t NumVectors, bool zeroOut=true);
00087 
00089     MultiVector(const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> &source);
00090 
00092 
00093     MultiVector(const Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > &map, const Teuchos::ArrayView<const Scalar> &A, size_t LDA, size_t NumVectors);
00094 
00096 
00097     MultiVector(const Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > &map, const Teuchos::ArrayView<const Teuchos::ArrayView<const Scalar> > &ArrayOfPtrs, size_t NumVectors);
00098 
00100     virtual ~MultiVector();
00101 
00103 
00105 
00106 
00108 
00110     void replaceGlobalValue(GlobalOrdinal globalRow, size_t vectorIndex, const Scalar &value);
00111 
00113 
00115     void sumIntoGlobalValue(GlobalOrdinal globalRow, size_t vectorIndex, const Scalar &value);
00116 
00118 
00120     void replaceLocalValue(LocalOrdinal myRow, size_t vectorIndex, const Scalar &value);
00121 
00123 
00125     void sumIntoLocalValue(LocalOrdinal myRow, size_t vectorIndex, const Scalar &value);
00126 
00128     void putScalar(const Scalar &value);
00129 
00131     void randomize();
00132 
00134     void replaceMap(const Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > &map);
00135 
00137     void reduce();
00138 
00140 
00142     MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node>& operator=(const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> &source);
00143 
00145 
00147 
00155 
00157     Teuchos::RCP<MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> > subCopy(const Teuchos::Range1D &colRng) const;
00158 
00160     Teuchos::RCP<MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> > subCopy(const Teuchos::ArrayView<const size_t> &cols) const;
00161 
00163     Teuchos::RCP<const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> > subView(const Teuchos::Range1D &colRng) const;
00164 
00166     Teuchos::RCP<const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> > subView(const Teuchos::ArrayView<const size_t> &cols) const;
00167 
00169     Teuchos::RCP<MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> > subViewNonConst(const Teuchos::Range1D &colRng);
00170 
00172     Teuchos::RCP<MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> > subViewNonConst(const Teuchos::ArrayView<const size_t> &cols);
00173 
00175 
00183     Teuchos::RCP<const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> > offsetView(const Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > &subMap, size_t offset) const;
00184 
00186 
00194     Teuchos::RCP<MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> > offsetViewNonConst(const Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > &subMap, size_t offset);
00195 
00197     Teuchos::RCP<const Vector<Scalar,LocalOrdinal,GlobalOrdinal,Node> > getVector(size_t j) const;
00198 
00200     Teuchos::RCP<Vector<Scalar,LocalOrdinal,GlobalOrdinal,Node> > getVectorNonConst(size_t j);
00201 
00204     Teuchos::ArrayRCP<const Scalar> getData(size_t j) const;
00205 
00208     Teuchos::ArrayRCP<Scalar> getDataNonConst(size_t j);
00209 
00211     void get1dCopy(Teuchos::ArrayView<Scalar> A, size_t LDA) const;
00212 
00214     void get2dCopy(Teuchos::ArrayView<const Teuchos::ArrayView<Scalar> > ArrayOfPtrs) const;
00215 
00217     Teuchos::ArrayRCP<const Scalar> get1dView() const;
00218 
00220     Teuchos::ArrayRCP<Teuchos::ArrayRCP<const Scalar> > get2dView() const;
00221 
00223     Teuchos::ArrayRCP<Scalar> get1dViewNonConst();
00224 
00226     Teuchos::ArrayRCP<Teuchos::ArrayRCP<Scalar> > get2dViewNonConst();
00227 
00229     const Kokkos::MultiVector<Scalar,Node> & getLocalMV() const;
00230 
00232     Kokkos::MultiVector<Scalar,Node> & getLocalMVNonConst();
00233 
00235 
00237 
00238 
00240     void dot(const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> &A, const Teuchos::ArrayView<Scalar> &dots) const;
00241 
00243     void abs(const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> &A);
00244 
00246     void reciprocal(const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> &A);
00247 
00249     void scale(const Scalar &alpha);
00250 
00252     void scale(Teuchos::ArrayView<const Scalar> alpha);
00253 
00255     void scale(const Scalar &alpha, const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> &A);
00256 
00258     void update(const Scalar &alpha, const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> &A, const Scalar &beta);
00259 
00261     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);
00262 
00264     void norm1(const Teuchos::ArrayView<typename Teuchos::ScalarTraits<Scalar>::magnitudeType> &norms) const;
00265 
00267     void norm2(const Teuchos::ArrayView<typename Teuchos::ScalarTraits<Scalar>::magnitudeType> &norms) const;
00268 
00270     void normInf(const Teuchos::ArrayView<typename Teuchos::ScalarTraits<Scalar>::magnitudeType> &norms) const;
00271 
00273     void normWeighted(const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> &weights, const Teuchos::ArrayView<typename Teuchos::ScalarTraits<Scalar>::magnitudeType> &norms) const;
00274 
00276     void meanValue(const Teuchos::ArrayView<Scalar> &means) const;
00277 
00279     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);
00280 
00282 
00287     void elementWiseMultiply(Scalar scalarAB, const Vector<Scalar,LocalOrdinal,GlobalOrdinal,Node> &A, const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> &B, Scalar scalarThis);
00289 
00291 
00292 
00294     size_t getNumVectors() const;
00295 
00297     size_t getLocalLength() const;
00298 
00300     global_size_t getGlobalLength() const;
00301 
00303     size_t getStride() const;
00304 
00306     bool isConstantStride() const;
00307 
00309 
00311 
00312 
00314     std::string description() const;
00315 
00317     void describe(Teuchos::FancyOStream &out, const Teuchos::EVerbosityLevel verbLevel=Teuchos::Describable::verbLevel_default) const;
00318 
00320 
00321     protected:
00322 
00323     typedef Kokkos::MultiVector<Scalar,Node> KMV;
00324     typedef Kokkos::DefaultArithmetic<KMV>   MVT;
00325   
00326     inline bool vectorIndexOutOfRange(size_t VectorIndex) const {
00327       return (VectorIndex < 1 && VectorIndex != 0) || VectorIndex >= getNumVectors();
00328     }
00329 
00330     KMV lclMV_;
00331     Teuchos::Array<size_t> whichVectors_;
00332 
00333     template <class T>
00335     Teuchos::ArrayRCP<T> getSubArrayRCP(Teuchos::ArrayRCP<T> arr, size_t j) const;
00336 
00338     MultiVector(const Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > &map,
00339                 Teuchos::ArrayRCP<Scalar> data, size_t LDA, Teuchos::ArrayView<const size_t> whichVectors);
00340 
00342     MultiVector(const Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > &map,
00343                 Teuchos::ArrayRCP<Scalar> data, size_t LDA, size_t NumVectors);
00344 
00345     // four functions needed for DistObject derivation
00346     bool checkSizes(const DistObject<Scalar,LocalOrdinal,GlobalOrdinal,Node> &sourceObj);
00347 
00348     void copyAndPermute(const DistObject<Scalar,LocalOrdinal,GlobalOrdinal,Node> &sourceObj,
00349                         size_t numSameIDs,
00350                         const Teuchos::ArrayView<const LocalOrdinal> &permuteToLIDs,
00351                         const Teuchos::ArrayView<const LocalOrdinal> &permuteFromLIDs);
00352 
00353     void packAndPrepare(const DistObject<Scalar,LocalOrdinal,GlobalOrdinal,Node> &sourceObj,
00354                         const Teuchos::ArrayView<const LocalOrdinal> &exportLIDs,
00355                         Teuchos::Array<Scalar> &exports,
00356                         const Teuchos::ArrayView<size_t> &numExportPacketsPerLID,
00357                         size_t& constantNumPackets,
00358                         Distributor &distor);
00359 
00360     void unpackAndCombine(const Teuchos::ArrayView<const LocalOrdinal> &importLIDs,
00361                           const Teuchos::ArrayView<const Scalar> &imports,
00362                           const Teuchos::ArrayView<size_t> &numPacketsPerLID,
00363                           size_t constantNumPackets,
00364                           Distributor &distor,
00365                           CombineMode CM);
00366 
00367   mutable Teuchos::ArrayRCP<Scalar> ncview_;
00368   mutable Teuchos::ArrayRCP<const Scalar> cview_;
00369 
00370   void createViews() const;
00371   void createViewsNonConst(Kokkos::ReadWriteOption rwo);
00372   void releaseViews() const;
00373 
00374   }; // class MultiVector
00375 
00379   template <class Scalar, class LocalOrdinal, class GlobalOrdinal, class Node>
00380   RCP< MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> >
00381   createMultiVector(const RCP< const Map<LocalOrdinal,GlobalOrdinal,Node> > &map, size_t numVectors) 
00382   {
00383     const bool DO_INIT_TO_ZERO = true;
00384     return rcp( new MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node>(map,numVectors,DO_INIT_TO_ZERO) );
00385   }
00386 
00387 
00388 } // namespace Tpetra
00389 
00390 
00391 #endif // TPETRA_MULTIVECTOR_DECL_HPP
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines