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 #include "Tpetra_ViewAccepter.hpp"
00057 
00058 // TODO: add principal use case instructions for memory management interfaces (view/copy extraction)
00059 // TODO: expand user-visible documentation
00060 
00061 namespace Tpetra {
00062 
00063 #ifndef DOXYGEN_SHOULD_SKIP_THIS
00064   // forward declaration of Vector, needed to prevent circular inclusions
00065   template<class S, class LO, class GO, class N> class Vector;
00066 
00067   //template<class S, class LO, class GO, class N> class MultiVector;
00068 
00069   //template <class Scalar, class LocalOrdinal, class GlobalOrdinal, class Node>
00070   //RCP< MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> >
00071   //createMultiVectorFromView(const RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > &map,
00072   //                          const ArrayRCP<Scalar> &view, size_t LDA, size_t numVectors);
00073 #endif
00074 
00076 
00081   template<class Scalar,
00082            class LocalOrdinal=int,
00083            class GlobalOrdinal=LocalOrdinal,
00084            class Node=Kokkos::DefaultNode::DefaultNodeType>
00085   class MultiVector :
00086     public DistObject<Scalar, LocalOrdinal, GlobalOrdinal, Node>
00087   {
00088   public:
00090     typedef Scalar        scalar_type;
00091     typedef LocalOrdinal  local_ordinal_type;
00092     typedef GlobalOrdinal global_ordinal_type;
00093     typedef Node          node_type;
00094 
00096 
00097 
00098 
00105     MultiVector (const Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> >& map,
00106                  size_t NumVectors,
00107                  bool zeroOut=true);
00108 
00110     MultiVector (const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> &source);
00111 
00113 
00114     MultiVector (const Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> >& map,
00115                  const Teuchos::ArrayView<const Scalar>& A,
00116                  size_t LDA,
00117                  size_t NumVectors);
00118 
00120 
00121     MultiVector (const Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> >& map,
00122                  const Teuchos::ArrayView<const Teuchos::ArrayView<const Scalar> >&ArrayOfPtrs,
00123                  size_t NumVectors);
00124 
00126     virtual ~MultiVector();
00127 
00129 
00130 
00131 
00140     void
00141     replaceGlobalValue (GlobalOrdinal globalRow,
00142                         size_t vectorIndex,
00143                         const Scalar &value);
00144 
00153     void
00154     sumIntoGlobalValue (GlobalOrdinal globalRow,
00155                         size_t vectorIndex,
00156                         const Scalar &value);
00157 
00166     void
00167     replaceLocalValue (LocalOrdinal myRow,
00168                        size_t vectorIndex,
00169                        const Scalar &value);
00170 
00179     void
00180     sumIntoLocalValue (LocalOrdinal myRow,
00181                        size_t vectorIndex,
00182                        const Scalar &value);
00183 
00185     void putScalar (const Scalar &value);
00186 
00202     void randomize();
00203 
00229     void replaceMap(const RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > &map);
00230 
00232     void reduce();
00233 
00248     MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node>&
00249     operator= (const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node>& source);
00250 
00252 
00254 
00262 
00264     Teuchos::RCP<MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> >
00265     subCopy (const Teuchos::Range1D &colRng) const;
00266 
00268     Teuchos::RCP<MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> >
00269     subCopy (const Teuchos::ArrayView<const size_t> &cols) const;
00270 
00272     Teuchos::RCP<const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> >
00273     subView (const Teuchos::Range1D &colRng) const;
00274 
00276     Teuchos::RCP<const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> >
00277     subView (const Teuchos::ArrayView<const size_t> &cols) const;
00278 
00280     Teuchos::RCP<MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> >
00281     subViewNonConst (const Teuchos::Range1D &colRng);
00282 
00284     Teuchos::RCP<MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> >
00285     subViewNonConst (const Teuchos::ArrayView<const size_t> &cols);
00286 
00288 
00299     Teuchos::RCP<const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> >
00300     offsetView (const Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> >& subMap,
00301                 size_t offset) const;
00302 
00304 
00315     Teuchos::RCP<MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> >
00316     offsetViewNonConst (const Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > &subMap,
00317                         size_t offset);
00318 
00320     Teuchos::RCP<const Vector<Scalar,LocalOrdinal,GlobalOrdinal,Node> >
00321     getVector (size_t j) const;
00322 
00324     Teuchos::RCP<Vector<Scalar,LocalOrdinal,GlobalOrdinal,Node> >
00325     getVectorNonConst (size_t j);
00326 
00328     Teuchos::ArrayRCP<const Scalar> getData(size_t j) const;
00329 
00331     Teuchos::ArrayRCP<Scalar> getDataNonConst(size_t j);
00332 
00339     void get1dCopy (Teuchos::ArrayView<Scalar> A, size_t LDA) const;
00340 
00346     void get2dCopy (Teuchos::ArrayView<const Teuchos::ArrayView<Scalar> > ArrayOfPtrs) const;
00347 
00353     Teuchos::ArrayRCP<const Scalar> get1dView() const;
00354 
00356     Teuchos::ArrayRCP<Teuchos::ArrayRCP<const Scalar> > get2dView() const;
00357 
00363     Teuchos::ArrayRCP<Scalar> get1dViewNonConst();
00364 
00366     Teuchos::ArrayRCP<Teuchos::ArrayRCP<Scalar> > get2dViewNonConst();
00367 
00369     const Kokkos::MultiVector<Scalar,Node> & getLocalMV() const;
00370 
00372     Kokkos::MultiVector<Scalar,Node> & getLocalMVNonConst();
00373 
00375 
00377 
00378 
00380     void dot(const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> &A, const Teuchos::ArrayView<Scalar> &dots) const;
00381 
00383     void abs(const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> &A);
00384 
00386     void reciprocal(const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> &A);
00387 
00389     void scale(const Scalar &alpha);
00390 
00392     void scale(Teuchos::ArrayView<const Scalar> alpha);
00393 
00395     void scale(const Scalar &alpha, const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> &A);
00396 
00398     void update(const Scalar &alpha, const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> &A, const Scalar &beta);
00399 
00401     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);
00402 
00404     void norm1(const Teuchos::ArrayView<typename Teuchos::ScalarTraits<Scalar>::magnitudeType> &norms) const;
00405 
00407     void norm2(const Teuchos::ArrayView<typename Teuchos::ScalarTraits<Scalar>::magnitudeType> &norms) const;
00408 
00410     void normInf(const Teuchos::ArrayView<typename Teuchos::ScalarTraits<Scalar>::magnitudeType> &norms) const;
00411 
00413     void normWeighted(const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> &weights, const Teuchos::ArrayView<typename Teuchos::ScalarTraits<Scalar>::magnitudeType> &norms) const;
00414 
00416     void meanValue(const Teuchos::ArrayView<Scalar> &means) const;
00417 
00419     void
00420     multiply (Teuchos::ETransp transA,
00421               Teuchos::ETransp transB,
00422               const Scalar& alpha,
00423               const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node>& A,
00424               const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node>& B,
00425               const Scalar& beta);
00426 
00428 
00433     void
00434     elementWiseMultiply (Scalar scalarAB,
00435                          const Vector<Scalar,LocalOrdinal,GlobalOrdinal,Node>& A,
00436                          const MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node>& B,
00437                          Scalar scalarThis);
00439 
00441 
00442 
00444     size_t getNumVectors() const;
00445 
00447     size_t getLocalLength() const;
00448 
00450     global_size_t getGlobalLength() const;
00451 
00457     size_t getStride() const;
00458 
00462     bool isConstantStride() const;
00463 
00465 
00467 
00468 
00470     std::string description() const;
00471 
00500     void
00501     describe (Teuchos::FancyOStream& out,
00502               const Teuchos::EVerbosityLevel verbLevel=Teuchos::Describable::verbLevel_default) const;
00503 
00505 
00506   protected:
00507 
00508     typedef Kokkos::MultiVector<Scalar,Node> KMV;
00509     typedef Kokkos::DefaultArithmetic<KMV>   MVT;
00510 
00512     KMV lclMV_;
00513 
00519     Array<size_t> whichVectors_;
00520 
00522 
00523 
00524     template <class S,class LO,class GO,class N>
00525     friend RCP<MultiVector<S,LO,GO,N> >
00526     createMultiVectorFromView (const Teuchos::RCP<const Map<LO,GO,N> >&, const Teuchos::ArrayRCP<S>&, size_t, size_t);
00527 
00537     MultiVector (const Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> >& map,
00538                  const Teuchos::ArrayRCP<Scalar>& view,
00539                  size_t LDA,
00540                  size_t NumVectors,
00541                  EPrivateHostViewConstructor /* dummy */);
00542 
00543     inline bool vectorIndexOutOfRange(size_t VectorIndex) const {
00544       return (VectorIndex < 1 && VectorIndex != 0) || VectorIndex >= getNumVectors();
00545     }
00546 
00552     template <class T>
00553     ArrayRCP<T> getSubArrayRCP(ArrayRCP<T> arr, size_t j) const;
00554 
00556     MultiVector (const Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> >& map,
00557                  Teuchos::ArrayRCP<Scalar> data,
00558                  size_t LDA,
00559                  Teuchos::ArrayView<const size_t> whichVectors,
00560                  EPrivateComputeViewConstructor /* dummy */);
00561 
00563     MultiVector (const Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> >& map,
00564                  Teuchos::ArrayRCP<Scalar> data,
00565                  size_t LDA,
00566                  size_t NumVectors,
00567                  EPrivateComputeViewConstructor /* dummy */);
00568 
00570 
00571 
00572 
00577     bool
00578     checkSizes (const DistObject<Scalar,LocalOrdinal,GlobalOrdinal,Node>& sourceObj);
00579 
00580     void
00581     copyAndPermute (const DistObject<Scalar,LocalOrdinal,GlobalOrdinal,Node>& sourceObj,
00582                     size_t numSameIDs,
00583                     const ArrayView<const LocalOrdinal>& permuteToLIDs,
00584                     const ArrayView<const LocalOrdinal>& permuteFromLIDs);
00585 
00586     void
00587     packAndPrepare (const DistObject<Scalar,LocalOrdinal,GlobalOrdinal,Node>& sourceObj,
00588                     const ArrayView<const LocalOrdinal>& exportLIDs,
00589                     Array<Scalar>& exports,
00590                     const ArrayView<size_t>& numExportPacketsPerLID,
00591                     size_t& constantNumPackets,
00592                     Distributor& distor);
00593 
00594     void
00595     unpackAndCombine (const ArrayView<const LocalOrdinal>& importLIDs,
00596                       const ArrayView<const Scalar>& imports,
00597                       const ArrayView<size_t>& numPacketsPerLID,
00598                       size_t constantNumPackets,
00599                       Distributor& distor,
00600                       CombineMode CM);
00601 
00602     void createViews () const;
00603     void createViewsNonConst (Kokkos::ReadWriteOption rwo);
00604     void releaseViews () const;
00605 
00607     mutable ArrayRCP<Scalar> ncview_;
00608 
00610     mutable ArrayRCP<const Scalar> cview_;
00612   }; // class MultiVector
00613 
00621   template <class Scalar, class LocalOrdinal, class GlobalOrdinal, class Node>
00622   Teuchos::RCP<MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> >
00623   createMultiVector (const Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> >& map,
00624                      size_t numVectors)
00625   {
00626     using Teuchos::rcp;
00627     typedef MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> MV;
00628 
00629     const bool initToZero = true;
00630     return rcp (new MV (map, numVectors, initToZero));
00631   }
00632 
00646   template <class Scalar, class LocalOrdinal, class GlobalOrdinal, class Node>
00647   Teuchos::RCP<MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> >
00648   createMultiVectorFromView (const Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> >& map,
00649                              const Teuchos::ArrayRCP<Scalar>& view,
00650                              size_t LDA,
00651                              size_t numVectors)
00652   {
00653     using Teuchos::rcp;
00654     typedef Tpetra::details::ViewAccepter<Node> VAN;
00655     typedef MultiVector<Scalar,LocalOrdinal,GlobalOrdinal,Node> MV;
00656 
00657     // This uses a protected MultiVector constructor, but this
00658     // nonmember function was declared a friend of MultiVector.
00659     //
00660     // The ViewAccepter expression will fail to compile for
00661     // unsupported Kokkos Node types.
00662     return rcp (new MV (map, VAN::template acceptView<Scalar> (view),
00663                         LDA, numVectors, HOST_VIEW_CONSTRUCTOR));
00664   }
00665 
00666 } // namespace Tpetra
00667 
00668 
00669 #endif // TPETRA_MULTIVECTOR_DECL_HPP
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines