Tpetra parallel linear algebra  Version of the Day
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Tpetra_DistObject_decl.hpp
Go to the documentation of this file.
1 // @HEADER
2 // ***********************************************************************
3 //
4 // Tpetra: Templated Linear Algebra Services Package
5 // Copyright (2008) Sandia Corporation
6 //
7 // Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
8 // the U.S. Government retains certain rights in this software.
9 //
10 // Redistribution and use in source and binary forms, with or without
11 // modification, are permitted provided that the following conditions are
12 // met:
13 //
14 // 1. Redistributions of source code must retain the above copyright
15 // notice, this list of conditions and the following disclaimer.
16 //
17 // 2. Redistributions in binary form must reproduce the above copyright
18 // notice, this list of conditions and the following disclaimer in the
19 // documentation and/or other materials provided with the distribution.
20 //
21 // 3. Neither the name of the Corporation nor the names of the
22 // contributors may be used to endorse or promote products derived from
23 // this software without specific prior written permission.
24 //
25 // THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
26 // EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
27 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28 // PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
29 // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
30 // EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
31 // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
32 // PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
33 // LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
34 // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
35 // SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
36 //
37 // Questions? Contact Michael A. Heroux (maherou@sandia.gov)
38 //
39 // ************************************************************************
40 // @HEADER
41 
42 #ifndef TPETRA_DISTOBJECT_DECL_HPP
43 #define TPETRA_DISTOBJECT_DECL_HPP
44 
52 
53 #include "Tpetra_Map.hpp"
54 #include "Tpetra_Import.hpp"
55 #include "Tpetra_Export.hpp"
56 #include "Tpetra_SrcDistObject.hpp"
58 #include "Kokkos_ArithTraits.hpp"
59 #include <type_traits>
60 
61 // #ifndef HAVE_TPETRA_TRANSFER_TIMERS
62 // # define HAVE_TPETRA_TRANSFER_TIMERS 1
63 // #endif // HAVE_TPETRA_TRANSFER_TIMERS
64 
65 #ifdef HAVE_TPETRA_TRANSFER_TIMERS
66 # undef HAVE_TPETRA_TRANSFER_TIMERS
67 #endif // HAVE_TPETRA_TRANSFER_TIMERS
68 
69 namespace KokkosClassic {
74  enum ReadWriteOption {
75  ReadWrite = 0,
76  WriteOnly = 1
77  };
78 } // namespace KokkosClassic
79 
80 namespace Tpetra {
81 
164  template<class DistObjectType>
165  void
166  removeEmptyProcessesInPlace (Teuchos::RCP<DistObjectType>& input,
167  const Teuchos::RCP<const Map<typename DistObjectType::local_ordinal_type,
168  typename DistObjectType::global_ordinal_type,
169  typename DistObjectType::node_type> >& newMap);
170 
207  template<class DistObjectType>
208  void
209  removeEmptyProcessesInPlace (Teuchos::RCP<DistObjectType>& input);
210 
322  template <class Packet,
323  class LocalOrdinal,
324  class GlobalOrdinal,
325  class Node>
326  class DistObject :
327  virtual public SrcDistObject,
328  virtual public Teuchos::Describable
329  {
330  public:
332 
333 
338  using packet_type = typename ::Kokkos::Details::ArithTraits<Packet>::val_type;
340  using local_ordinal_type = LocalOrdinal;
342  using global_ordinal_type = GlobalOrdinal;
344  using node_type = Node;
345 
347  using device_type = typename Node::device_type;
349  using execution_space = typename device_type::execution_space;
350 
353 
355 
357 
361  explicit DistObject (const Teuchos::RCP<const map_type>& map);
362 
365 
368 
371 
374 
384  virtual ~DistObject () = default;
385 
387 
389 
417  void
418  doImport (const SrcDistObject& source,
420  const CombineMode CM,
421  const bool restrictedMode = false);
422 
450  void
451  doExport (const SrcDistObject& source,
453  const CombineMode CM,
454  const bool restrictedMode = false);
455 
484  void
485  doImport (const SrcDistObject& source,
487  const CombineMode CM,
488  const bool restrictedMode = false);
489 
518  void
519  doExport (const SrcDistObject& source,
521  const CombineMode CM,
522  const bool restrictedMode = false);
523 
525 
527 
533  bool isDistributed () const;
534 
541  virtual Teuchos::RCP<const map_type> getMap () const { return map_; }
542 
544 
546 
551  void print (std::ostream& os) const;
552 
554 
556 
561  virtual std::string description () const;
562 
567  virtual void
568  describe (Teuchos::FancyOStream &out,
569  const Teuchos::EVerbosityLevel verbLevel =
570  Teuchos::Describable::verbLevel_default) const;
571 
573 
575 
622  virtual void
623  removeEmptyProcessesInPlace (const Teuchos::RCP<const map_type>& newMap);
624 
626 
627  protected:
637  DoForward, //*!< Perform the transfer in forward mode.
638  DoReverse //*!< Perform the transfer in reverse mode.
639  };
640 
657  virtual size_t constantNumberOfPackets () const;
658 
678  virtual void
679  doTransfer (const SrcDistObject& src,
680  const ::Tpetra::Details::Transfer<local_ordinal_type, global_ordinal_type, node_type>& transfer,
681  const char modeString[],
682  const ReverseOption revOp,
683  const CombineMode CM,
684  const bool restrictedMode);
685 
700  virtual bool
701  reallocArraysForNumPacketsPerLid (const size_t numExportLIDs,
702  const size_t numImportLIDs);
703 
704 #ifdef TPETRA_ENABLE_DEPRECATED_CODE
705  virtual void TPETRA_DEPRECATED
711  doTransferOld (const SrcDistObject& src,
712  CombineMode CM,
713  size_t numSameIDs,
714  const Teuchos::ArrayView<const local_ordinal_type> &permuteToLIDs,
715  const Teuchos::ArrayView<const local_ordinal_type> &permuteFromLIDs,
716  const Teuchos::ArrayView<const local_ordinal_type> &remoteLIDs,
717  const Teuchos::ArrayView<const local_ordinal_type> &exportLIDs,
718  Distributor &distor,
719  ReverseOption revOp,
720  const bool restrictedMode);
721 #endif // TPETRA_ENABLE_DEPRECATED_CODE
722 
727 #ifdef KOKKOS_ENABLE_CUDA
728  using buffer_memory_space = typename std::conditional<
729  std::is_same<typename device_type::execution_space, Kokkos::Cuda>::value,
730  Kokkos::CudaSpace,
731  typename device_type::memory_space>::type;
732 #else
733  using buffer_memory_space = typename device_type::memory_space;
734 #endif // KOKKOS_ENABLE_CUDA
735 
736  public:
747  using buffer_device_type =
748  Kokkos::Device<typename device_type::execution_space,
750  protected:
756  virtual void
757  doTransferNew (const SrcDistObject& src,
758  const CombineMode CM,
759  const size_t numSameIDs,
760  const Kokkos::DualView<const local_ordinal_type*,
761  buffer_device_type>& permuteToLIDs,
762  const Kokkos::DualView<const local_ordinal_type*,
763  buffer_device_type>& permuteFromLIDs,
764  const Kokkos::DualView<const local_ordinal_type*,
765  buffer_device_type>& remoteLIDs,
766  const Kokkos::DualView<const local_ordinal_type*,
767  buffer_device_type>& exportLIDs,
768  Distributor& distor,
769  const ReverseOption revOp,
770  const bool commOnHost,
771  const bool restrictedMode);
772 
783 
784 
788  virtual bool
789  checkSizes (const SrcDistObject& source) = 0;
790 
791 #ifdef TPETRA_ENABLE_DEPRECATED_CODE
792  virtual void
819  copyAndPermuteNew (const SrcDistObject& source,
820  const size_t numSameIDs,
821  const Kokkos::DualView<const local_ordinal_type*,
822  buffer_device_type>& permuteToLIDs,
823  const Kokkos::DualView<const local_ordinal_type*,
824  buffer_device_type>& permuteFromLIDs);
825 #else // TPETRA_ENABLE_DEPRECATED_CODE
826  virtual void
853  copyAndPermute (const SrcDistObject& source,
854  const size_t numSameIDs,
855  const Kokkos::DualView<const local_ordinal_type*,
856  buffer_device_type>& permuteToLIDs,
857  const Kokkos::DualView<const local_ordinal_type*,
858  buffer_device_type>& permuteFromLIDs);
859 #endif // TPETRA_ENABLE_DEPRECATED_CODE
860 
861 #ifdef TPETRA_ENABLE_DEPRECATED_CODE
862  virtual void
903  packAndPrepareNew (const SrcDistObject& source,
904  const Kokkos::DualView<const local_ordinal_type*,
905  buffer_device_type>& exportLIDs,
906  Kokkos::DualView<packet_type*,
907  buffer_device_type>& exports,
908  Kokkos::DualView<size_t*,
909  buffer_device_type> numPacketsPerLID,
910  size_t& constantNumPackets,
911  Distributor& distor);
912 #else // TPETRA_ENABLE_DEPRECATED_CODE
913  virtual void
954  packAndPrepare (const SrcDistObject& source,
955  const Kokkos::DualView<const local_ordinal_type*,
956  buffer_device_type>& exportLIDs,
957  Kokkos::DualView<packet_type*,
958  buffer_device_type>& exports,
959  Kokkos::DualView<size_t*,
960  buffer_device_type> numPacketsPerLID,
961  size_t& constantNumPackets,
962  Distributor& distor);
963 #endif // TPETRA_ENABLE_DEPRECATED_CODE
964 
965 #ifdef TPETRA_ENABLE_DEPRECATED_CODE
966  virtual void
1009  unpackAndCombineNew (const Kokkos::DualView<const local_ordinal_type*,
1010  buffer_device_type>& importLIDs,
1011  Kokkos::DualView<packet_type*,
1012  buffer_device_type> imports,
1013  Kokkos::DualView<size_t*,
1014  buffer_device_type> numPacketsPerLID,
1015  const size_t constantNumPackets,
1016  Distributor& distor,
1017  const CombineMode combineMode);
1018 #else // TPETRA_ENABLE_DEPRECATED_CODE
1019  virtual void
1062  unpackAndCombine (const Kokkos::DualView<const local_ordinal_type*,
1063  buffer_device_type>& importLIDs,
1064  Kokkos::DualView<packet_type*,
1065  buffer_device_type> imports,
1066  Kokkos::DualView<size_t*,
1067  buffer_device_type> numPacketsPerLID,
1068  const size_t constantNumPackets,
1069  Distributor& distor,
1070  const CombineMode combineMode);
1071 #endif // TPETRA_ENABLE_DEPRECATED_CODE
1072 
1073 #ifdef TPETRA_ENABLE_DEPRECATED_CODE
1074  virtual bool TPETRA_DEPRECATED useNewInterface () { return true; }
1079 
1085  virtual void TPETRA_DEPRECATED
1086  copyAndPermute (const SrcDistObject& source,
1087  const size_t numSameIDs,
1088  const Teuchos::ArrayView<const local_ordinal_type>& permuteToLIDs,
1089  const Teuchos::ArrayView<const local_ordinal_type>& permuteFromLIDs);
1090 
1096  virtual void TPETRA_DEPRECATED
1097  packAndPrepare (const SrcDistObject& source,
1098  const Teuchos::ArrayView<const local_ordinal_type>& exportLIDs,
1099  Teuchos::Array<packet_type>& exports,
1100  const Teuchos::ArrayView<size_t>& numPacketsPerLID,
1101  size_t& constantNumPackets,
1102  Distributor& distor);
1103 
1109  virtual void TPETRA_DEPRECATED
1110  unpackAndCombine (const Teuchos::ArrayView<const local_ordinal_type>& importLIDs,
1111  const Teuchos::ArrayView<const packet_type>& imports,
1112  const Teuchos::ArrayView<size_t>& numPacketsPerLID,
1113  const size_t constantNumPackets,
1114  Distributor& distor,
1115  const CombineMode combineMode);
1117 
1122  virtual void TPETRA_DEPRECATED
1123  createViews () const;
1124 
1129  virtual void TPETRA_DEPRECATED
1130  createViewsNonConst (KokkosClassic::ReadWriteOption rwo);
1131 
1136  virtual void TPETRA_DEPRECATED releaseViews () const;
1137 #endif // TPETRA_ENABLE_DEPRECATED_CODE
1138 
1140  Teuchos::RCP<const map_type> map_;
1141 
1142  protected:
1149  Kokkos::DualView<packet_type*, buffer_device_type> imports_;
1150 
1169  bool
1170  reallocImportsIfNeeded (const size_t newSize,
1171  const bool verbose,
1172  const std::string* prefix);
1173 
1187  Kokkos::DualView<size_t*, buffer_device_type> numImportPacketsPerLID_;
1188 
1194  Kokkos::DualView<packet_type*, buffer_device_type> exports_;
1195 
1209  Kokkos::DualView<size_t*, buffer_device_type> numExportPacketsPerLID_;
1210 
1211  private:
1213 
1214 #ifdef HAVE_TPETRA_TRANSFER_TIMERS
1215  Teuchos::RCP<Teuchos::Time> doXferTimer_;
1216  Teuchos::RCP<Teuchos::Time> copyAndPermuteTimer_;
1217  Teuchos::RCP<Teuchos::Time> packAndPrepareTimer_;
1218  Teuchos::RCP<Teuchos::Time> doPostsAndWaitsTimer_;
1219  Teuchos::RCP<Teuchos::Time> unpackAndCombineTimer_;
1220 #endif // HAVE_TPETRA_TRANSFER_TIMERS
1221  }; // class DistObject
1222 } // namespace Tpetra
1223 
1224 #endif // TPETRA_DISTOBJECT_DECL_HPP
Communication plan for data redistribution from a uniquely-owned to a (possibly) multiply-owned distr...
Node node_type
The Node type. If you don&#39;t know what this is, don&#39;t use it.
Kokkos::DualView< size_t *, buffer_device_type > numExportPacketsPerLID_
Number of packets to send for each send operation.
void doImport(const SrcDistObject &source, const Import< LocalOrdinal, GlobalOrdinal, Node > &importer, const CombineMode CM, const bool restrictedMode=false)
Import data into this object using an Import object (&quot;forward mode&quot;).
virtual void packAndPrepare(const SrcDistObject &source, const Kokkos::DualView< const local_ordinal_type *, buffer_device_type > &exportLIDs, Kokkos::DualView< packet_type *, buffer_device_type > &exports, Kokkos::DualView< size_t *, buffer_device_type > numPacketsPerLID, size_t &constantNumPackets, Distributor &distor)
Pack data and metadata for communication (sends).
virtual void doTransferNew(const SrcDistObject &src, const CombineMode CM, const size_t numSameIDs, const Kokkos::DualView< const local_ordinal_type *, buffer_device_type > &permuteToLIDs, const Kokkos::DualView< const local_ordinal_type *, buffer_device_type > &permuteFromLIDs, const Kokkos::DualView< const local_ordinal_type *, buffer_device_type > &remoteLIDs, const Kokkos::DualView< const local_ordinal_type *, buffer_device_type > &exportLIDs, Distributor &distor, const ReverseOption revOp, const bool commOnHost, const bool restrictedMode)
Implementation detail of doTransfer.
void print(std::ostream &os) const
Print this object to the given output stream.
virtual bool reallocArraysForNumPacketsPerLid(const size_t numExportLIDs, const size_t numImportLIDs)
Reallocate numExportPacketsPerLID_ and/or numImportPacketsPerLID_, if necessary.
Abstract base class for sources of an Import or Export.
bool isDistributed() const
Whether this is a globally distributed object.
Forward declaration of Tpetra::DistObject.
void removeEmptyProcessesInPlace(Teuchos::RCP< DistObjectType > &input, const Teuchos::RCP< const Map< typename DistObjectType::local_ordinal_type, typename DistObjectType::global_ordinal_type, typename DistObjectType::node_type > > &newMap)
Remove processes which contain no elements in this object&#39;s Map.
virtual void doTransfer(const SrcDistObject &src, const ::Tpetra::Details::Transfer< local_ordinal_type, global_ordinal_type, node_type > &transfer, const char modeString[], const ReverseOption revOp, const CombineMode CM, const bool restrictedMode)
Redistribute data across (MPI) processes.
virtual ~DistObject()=default
Destructor (virtual for memory safety of derived classes).
typename::Kokkos::Details::ArithTraits< GlobalOrdinal >::val_type packet_type
The type of each datum being sent or received in an Import or Export.
Kokkos::DualView< size_t *, buffer_device_type > numImportPacketsPerLID_
Number of packets to receive for each receive operation.
typename device_type::execution_space execution_space
The Kokkos execution space.
Kokkos::DualView< packet_type *, buffer_device_type > imports_
Buffer into which packed data are imported (received from other processes).
Kokkos::DualView< packet_type *, buffer_device_type > exports_
Buffer from which packed data are exported (sent to other processes).
typename device_type::memory_space buffer_memory_space
Kokkos memory space for communication buffers.
Communication plan for data redistribution from a (possibly) multiply-owned to a uniquely-owned distr...
Sets up and executes a communication plan for a Tpetra DistObject.
CombineMode
Rule for combining data in an Import or Export.
Teuchos::RCP< const map_type > map_
The Map over which this object is distributed.
Abstract base class for objects that can be the source of an Import or Export operation.
bool reallocImportsIfNeeded(const size_t newSize, const bool verbose, const std::string *prefix)
Reallocate imports_ if needed.
DistObject & operator=(const DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node > &)=default
Assignment operator (default).
DistObject(const Teuchos::RCP< const map_type > &map)
Constructor.
virtual std::string description() const
One-line descriptiion of this object.
virtual size_t constantNumberOfPackets() const
Whether the implementation&#39;s instance promises always to have a constant number of packets per LID (l...
A parallel distribution of indices over processes.
void doExport(const SrcDistObject &source, const Export< LocalOrdinal, GlobalOrdinal, Node > &exporter, const CombineMode CM, const bool restrictedMode=false)
Export data into this object using an Export object (&quot;forward mode&quot;).
virtual Teuchos::RCP< const map_type > getMap() const
The Map describing the parallel distribution of this object.
virtual void describe(Teuchos::FancyOStream &out, const Teuchos::EVerbosityLevel verbLevel=Teuchos::Describable::verbLevel_default) const
Print a descriptiion of this object to the given output stream.
Kokkos::Device< typename device_type::execution_space, buffer_memory_space > buffer_device_type
virtual void copyAndPermute(const SrcDistObject &source, const size_t numSameIDs, const Kokkos::DualView< const local_ordinal_type *, buffer_device_type > &permuteToLIDs, const Kokkos::DualView< const local_ordinal_type *, buffer_device_type > &permuteFromLIDs)
Perform copies and permutations that are local to the calling (MPI) process.
Base class for distributed Tpetra objects that support data redistribution.
virtual void unpackAndCombine(const Kokkos::DualView< const local_ordinal_type *, buffer_device_type > &importLIDs, Kokkos::DualView< packet_type *, buffer_device_type > imports, Kokkos::DualView< size_t *, buffer_device_type > numPacketsPerLID, const size_t constantNumPackets, Distributor &distor, const CombineMode combineMode)
Perform any unpacking and combining after communication.
virtual void removeEmptyProcessesInPlace(const Teuchos::RCP< const map_type > &newMap)
Remove processes which contain no entries in this object&#39;s Map.
virtual bool checkSizes(const SrcDistObject &source)=0
Compare the source and target (this) objects for compatibility.