Kokkos: Document Kokkos::Complex math functions

[hcedwar]

Need well-defined strategy for Kokkos::Complex math functions. e.g., #546
Apply strategy to Kokkos::sqrt( Kokkos::Complex )

[hcedwar]

Favored strategy:

namespace std {
using Kokkos::sqrt ; // for Kokkos::sqrt( Kokkos::Complex<T> const & );
}

[etphipp]

I would suggest you don't do that. I inject Sacado's overloads into the std:: namespace and it continues to cause numerous headaches. I have found the following strategy works much better, but it is up to users to do it correctly:

using std::sqrt;

Scalar x = ...

Scalar y = sqrt(x);

The using std::sqrt will handle the case when Scalar is any builtin type. When Scalar is any derived type, such as Kokkos::complex, the right overload will be found through argument-dependent lookup, as long as the overload is placed in the same namespace that Scalar is in (which it is for Kokkos::complex).

This is what I recommend users of Sacado do. If it weren't for backwards compatibility, I would remove all of my injections into std:: for Sacado.

[hcedwar]

Need to give users documented guidance for best practice on how to deal with portable complex

[ibaned]

https://github.com/kokkos/kokkos/wiki/Kokkos%3A%3AComplex