Tpetra parallel linear algebra  Version of the Day
Namespaces | Macros | Functions
Tpetra_Util.hpp File Reference

Stand-alone utility functions and macros. More...

#include "Tpetra_ConfigDefs.hpp"
#include "Kokkos_DualView.hpp"
#include "Teuchos_Utils.hpp"
#include "Teuchos_Assert.hpp"
#include <algorithm>
#include <iterator>
#include <sstream>

Go to the source code of this file.

Namespaces

 Tpetra
 Namespace Tpetra contains the class and methods constituting the Tpetra library.
 
 SortDetails
 Implementation details of sort routines used by Tpetra.
 
 Tpetra::Details
 Namespace for Tpetra implementation details.
 

Macros

#define TPETRA_EFFICIENCY_WARNING(throw_exception_test, Exception, msg)
 Print or throw an efficency warning. More...
 
#define TPETRA_ABUSE_WARNING(throw_exception_test, Exception, msg)
 Handle an abuse warning, according to HAVE_TPETRA_THROW_ABUSE_WARNINGS and HAVE_TPETRA_PRINT_ABUSE_WARNINGS. More...
 
#define SHARED_TEST_FOR_EXCEPTION(throw_exception_test, Exception, msg, comm)
 Test for exception, with reduction over the given communicator. More...
 
#define SWITCHED_TEST_FOR_EXCEPTION(throw_exception_test, Exception, msg, comm)
 If TEUCHOS_DEBUG is defined, then it calls SHARED_TEST_FOR_EXCEPTION. Otherwise, it calls TEUCHOS_TEST_FOR_EXCEPTION. More...
 

Functions

template<typename MapType , typename KeyArgType , typename ValueArgType >
MapType::iterator Tpetra::efficientAddOrUpdate (MapType &m, const KeyArgType &k, const ValueArgType &v)
 Efficiently insert or replace an entry in an std::map. More...
 
template<class IT1 >
bool Tpetra::SortDetails::isAlreadySorted (const IT1 &first, const IT1 &last)
 Determines whether or not a random access sequence is already sorted. More...
 
template<class IT >
IT Tpetra::SortDetails::getPivot (const IT &first, const IT &last)
 Determines the pivot point as part of the quicksort routine. More...
 
template<class IT1 , class IT2 >
IT1 Tpetra::SortDetails::partition2 (const IT1 &first1, const IT1 &last1, const IT2 &first2, const IT2 &last2, const IT1 &pivot)
 Partition operation for quicksort2(). More...
 
template<class IT1 , class IT2 , class IT3 >
IT1 Tpetra::SortDetails::partition3 (const IT1 &first1, const IT1 &last1, const IT2 &first2, const IT2 &last2, const IT3 &first3, const IT3 &last3, const IT1 &pivot)
 Partition operation for quicksort3(). More...
 
template<class IT1 , class IT2 >
void Tpetra::SortDetails::quicksort2 (const IT1 &first1, const IT1 &last1, const IT2 &first2, const IT2 &last2)
 Sort the first array using Quicksort, and apply the resulting permutation to the second array. More...
 
template<class IT1 , class IT2 , class IT3 >
void Tpetra::SortDetails::quicksort3 (const IT1 &first1, const IT1 &last1, const IT2 &first2, const IT2 &last2, const IT3 &first3, const IT3 &last3)
 Sort the first array using Quicksort, and apply the resulting permutation to the second and third arrays. More...
 
template<class IT1 , class IT2 , class IT3 >
void Tpetra::SortDetails::sh_sort3 (const IT1 &first1, const IT1 &last1, const IT2 &first2, const IT2 &last2, const IT3 &first3, const IT3 &last3)
 Sort the first array using shell sort, and apply the resulting permutation to the second and third arrays. More...
 
template<class IT1 , class IT2 >
void Tpetra::SortDetails::sh_sort2 (const IT1 &first1, const IT1 &last1, const IT2 &first2, const IT2 &last2)
 Sort the first array using shell sort, and apply the resulting permutation to the second array. More...
 
template<class IT1 , class IT2 >
void Tpetra::sort2 (const IT1 &first1, const IT1 &last1, const IT2 &first2)
 Sort the first array, and apply the resulting permutation to the second array. More...
 
template<class IT1 , class IT2 , class IT3 >
void Tpetra::sort3 (const IT1 &first1, const IT1 &last1, const IT2 &first2, const IT3 &first3)
 Sort the first array, and apply the same permutation to the second and third arrays. More...
 
template<class IT1 , class IT2 >
void Tpetra::merge2 (IT1 &indResultOut, IT2 &valResultOut, IT1 indBeg, IT1 indEnd, IT2 valBeg, IT2 valEnd)
 Merge values in place, additively, with the same index. More...
 
template<class IT1 , class IT2 , class BinaryFunction >
void Tpetra::merge2 (IT1 &indResultOut, IT2 &valResultOut, IT1 indBeg, IT1 indEnd, IT2 valBeg, IT2 valEnd, BinaryFunction f)
 Merge values in place with the same index, using any associative binary function. More...
 
template<class KeyInputIterType , class ValueInputIterType , class KeyOutputIterType , class ValueOutputIterType , class BinaryFunction >
void Tpetra::keyValueMerge (KeyInputIterType keyBeg1, KeyInputIterType keyEnd1, ValueInputIterType valBeg1, ValueInputIterType valEnd1, KeyInputIterType keyBeg2, KeyInputIterType keyEnd2, ValueInputIterType valBeg2, ValueInputIterType valEnd2, KeyOutputIterType keyOut, ValueOutputIterType valOut, BinaryFunction f)
 Merge two sorted (by keys) sequences of unique (key,value) pairs by combining pairs with equal keys. More...
 
bool Tpetra::Details::congruent (const Teuchos::Comm< int > &comm1, const Teuchos::Comm< int > &comm2)
 Whether the two communicators are congruent. More...
 
template<class DualViewType >
Teuchos::ArrayView< typename DualViewType::t_dev::value_type > Tpetra::Details::getArrayViewFromDualView (const DualViewType &x)
 Get a Teuchos::ArrayView which views the host Kokkos::View of the input 1-D Kokkos::DualView. More...
 
template<class T , class DT >
Kokkos::DualView< T *, DT > Tpetra::Details::getDualViewCopyFromArrayView (const Teuchos::ArrayView< const T > &x_av, const char label[], const bool leaveOnHost)
 Get a 1-D Kokkos::DualView which is a deep copy of the input Teuchos::ArrayView (which views host memory). More...
 

Detailed Description

Stand-alone utility functions and macros.

Tpetra_Util contains utility functions macros that are used throughout Tpetra, by many classes and functions. They are placed here so that they can be updated and maintained in a single spot.

Definition in file Tpetra_Util.hpp.

Macro Definition Documentation

◆ TPETRA_EFFICIENCY_WARNING

#define TPETRA_EFFICIENCY_WARNING (   throw_exception_test,
  Exception,
  msg 
)

Print or throw an efficency warning.

This macro is only for use by Tpetra developers. It is only to be used in the implementation of a Tpetra class' instance method.

If HAVE_TPETRA_THROW_EFFICIENCY_WARNINGS is defined, throw an exception of type Exception, whose exception message will include msg (along with other useful information).

If HAVE_TPETRA_PRINT_EFFICIENCY_WARNINGS is defined, print the given message to std::cerr, along with other useful information.

This macro must be called in an instance method of a class. (Alas, C++ gives us no way to search the scope for a list of defined names. Otherwise, the macro could search for "this" to determine whether it is in a class' instance method.)

Macro arguments:

throw_exception_test: Boolean expression to evaluate. If true, this macro will trigger the efficiency warning. The test will be evaluated at most once. Nevertheless, the test should not have side effects, since it will not be evaluated at all if neither HAVE_TPETRA_THROW_EFFICIENCY_WARNINGS nor HAVE_TPETRA_PRINT_EFFICIENCY_WARNINGS are defined.

Exception: The type of exception to throw, if throw_exception_test evaluates to true and TPETRA_THROWS_EFFICIENCY_WARNINGS is defined. The Exception should be a subclass of std::exception.

msg: The message to include in the warning. The warning also includes the name of the class, and other useful information.

Definition at line 145 of file Tpetra_Util.hpp.

◆ TPETRA_ABUSE_WARNING

#define TPETRA_ABUSE_WARNING (   throw_exception_test,
  Exception,
  msg 
)

Handle an abuse warning, according to HAVE_TPETRA_THROW_ABUSE_WARNINGS and HAVE_TPETRA_PRINT_ABUSE_WARNINGS.

Definition at line 163 of file Tpetra_Util.hpp.

◆ SHARED_TEST_FOR_EXCEPTION

#define SHARED_TEST_FOR_EXCEPTION (   throw_exception_test,
  Exception,
  msg,
  comm 
)
Value:
{ \
using Teuchos::outArg; \
const int lcl_throw_exception = (throw_exception_test) ? Teuchos::rank(comm)+1 : 0; \
int gbl_throw; \
Teuchos::reduceAll(comm,Teuchos::REDUCE_MAX,lcl_throw_exception,outArg(gbl_throw)); \
TEUCHOS_TEST_FOR_EXCEPTION(gbl_throw,Exception, \
msg << " Failure on at least one process, including process " << gbl_throw-1 << "." << std::endl); \
}

Test for exception, with reduction over the given communicator.

This is like Teuchos' TEUCHOS_TEST_FOR_EXCEPTION macro, except that it performs an all-reduce over the given communicator to ensure that all processes throw the exception if the test is true on at least one process.

Macro arguments:

throw_exception_test: Boolean expression to evaluate. If true on at least one calling process in the given communicator, this macro will throw an exception of the given type on all processes in the communicator. The exception message may differ on different processes. The expression will only be evaluated once on each process.

Exception: The type of exception to throw, if throw_exception_test evaluates to true on at least one process in the given communicator. The Exception should be a subclass of std::exception.

msg: The message to include in the warning. The warning also includes the name of the class, and the maximum process rank on which the test evaluated to true. The message may be different on different processes.

comm: The communicator (instance of a subclass of Teuchos::Comm<int>) over which to test. This must evaluate to a class instance or reference, not a Teuchos::RCP of an instance.

Definition at line 195 of file Tpetra_Util.hpp.

◆ SWITCHED_TEST_FOR_EXCEPTION

#define SWITCHED_TEST_FOR_EXCEPTION (   throw_exception_test,
  Exception,
  msg,
  comm 
)
Value:
{ \
TEUCHOS_TEST_FOR_EXCEPTION(throw_exception_test,Exception,msg); \
}

If TEUCHOS_DEBUG is defined, then it calls SHARED_TEST_FOR_EXCEPTION. Otherwise, it calls TEUCHOS_TEST_FOR_EXCEPTION.

Definition at line 213 of file Tpetra_Util.hpp.

Function Documentation

◆ isAlreadySorted()

template<class IT1 >
bool Tpetra::SortDetails::isAlreadySorted ( const IT1 &  first,
const IT1 &  last 
)

Determines whether or not a random access sequence is already sorted.

Parameters
firstAn iterator pointing to the beginning of the sequence.
lastAn iterator pointing to the end of the sequence.
Returns
True if the sequence is already sorted, else false.

Definition at line 266 of file Tpetra_Util.hpp.

◆ getPivot()

template<class IT >
IT Tpetra::SortDetails::getPivot ( const IT &  first,
const IT &  last 
)

Determines the pivot point as part of the quicksort routine.

Parameters
firstAn iterator pointing to the beginning of the array segment we are trying to find a pivot for.
lastAn iterator pointing to the ending of the array segment we are trying to find a pivot for.
Returns
The pivot point for the given array segment.

Definition at line 288 of file Tpetra_Util.hpp.

◆ partition2()

template<class IT1 , class IT2 >
IT1 Tpetra::SortDetails::partition2 ( const IT1 &  first1,
const IT1 &  last1,
const IT2 &  first2,
const IT2 &  last2,
const IT1 &  pivot 
)

Partition operation for quicksort2().

This is a helper routine for quicksort2(). It performs the partition step in Quicksort. All of the input argument iterators are random access iterators.

Parameters
first1An iterator pointing to the beginning of the first array.
last1An iterator pointing to the end of the first array.
first2An iterator pointing to the beginning of the second array.
last2An iterator pointing to the end of the second array.
pivotA pivot point calculated by the pivot function.
Returns
An iterator pointing to where the partition should be made.

Definition at line 310 of file Tpetra_Util.hpp.

◆ partition3()

template<class IT1 , class IT2 , class IT3 >
IT1 Tpetra::SortDetails::partition3 ( const IT1 &  first1,
const IT1 &  last1,
const IT2 &  first2,
const IT2 &  last2,
const IT3 &  first3,
const IT3 &  last3,
const IT1 &  pivot 
)

Partition operation for quicksort3().

This is a helper routine for quicksort3(). It performs the partition step in Quicksort. All of the input argument iterators are random access iterators.

Parameters
first1An iterator pointing to the beginning of the first array.
last1An iterator pointing to the end of the first array.
first2An iterator pointing to the beginning of the second array.
last2An iterator pointing to the end of the second array.
first3An iterator pointing to the beginning of the third array.
last3An iterator pointing to the end of the third array.
pivotA pivot point calculated by the pivot function.
Returns
An iterator pointing to where the partition should be made.

Definition at line 350 of file Tpetra_Util.hpp.

◆ quicksort2()

template<class IT1 , class IT2 >
void Tpetra::SortDetails::quicksort2 ( const IT1 &  first1,
const IT1 &  last1,
const IT2 &  first2,
const IT2 &  last2 
)

Sort the first array using Quicksort, and apply the resulting permutation to the second array.

All of the input argument iterators are random access iterators.

Parameters
first1An iterator pointing to the beginning of the first array.
last1An iterator pointing to the end (exclusive) of the first array.
first2An iterator pointing to the beginning of the second array.
last2An iterator pointing to the end of the second array.

Definition at line 389 of file Tpetra_Util.hpp.

◆ quicksort3()

template<class IT1 , class IT2 , class IT3 >
void Tpetra::SortDetails::quicksort3 ( const IT1 &  first1,
const IT1 &  last1,
const IT2 &  first2,
const IT2 &  last2,
const IT3 &  first3,
const IT3 &  last3 
)

Sort the first array using Quicksort, and apply the resulting permutation to the second and third arrays.

All of the input argument iterators are random access iterators.

Parameters
first1An iterator pointing to the beginning of the first array.
last1An iterator pointing to the end of the first array.
first2An iterator pointing to the beginning of the second array.
last2An iterator pointing to the end of the second array.
first3An iterator pointing to the beginning of the third array.
last3An iterator pointing to the end of the third array.

Definition at line 418 of file Tpetra_Util.hpp.

◆ sh_sort3()

template<class IT1 , class IT2 , class IT3 >
void Tpetra::SortDetails::sh_sort3 ( const IT1 &  first1,
const IT1 &  last1,
const IT2 &  first2,
const IT2 &  last2,
const IT3 &  first3,
const IT3 &  last3 
)

Sort the first array using shell sort, and apply the resulting permutation to the second and third arrays.

All of the input argument iterators are random access iterators.

Definition at line 443 of file Tpetra_Util.hpp.

◆ sh_sort2()

template<class IT1 , class IT2 >
void Tpetra::SortDetails::sh_sort2 ( const IT1 &  first1,
const IT1 &  last1,
const IT2 &  first2,
const IT2 &  last2 
)

Sort the first array using shell sort, and apply the resulting permutation to the second array.

All of the input argument iterators are random access iterators.

Definition at line 480 of file Tpetra_Util.hpp.