Add taking the address of math constants to known issues

docs/source/API/core/numerics/mathematical-constants.rst

@@ -40,8 +40,13 @@ All constants are defined in the ``Kokkos::numbers::`` namespace since version 4
 Notes
 -----
 
+.. _KnownIssues: ../../../known-issues.html#mathematical-constants
+
+.. |KnownIssues| replace:: known issues
+
 * The mathematical constants are available in ``Kokkos::Experimental::`` since Kokkos 3.6
 * They were "promoted" to the ``Kokkos::numbers`` namespace in 4.0
+* Avoid taking the address of mathematical constants in device code.  It is not supported by some toolchains, hence not portable.  (See |KnownIssues|_)
 
 ------------
 

docs/source/known-issues.rst

@@ -41,3 +41,25 @@ The using-directive ``using namespace Kokkos;`` is highly discouraged (see
 calls to mathematical functions.  Instead, prefer explicit qualification
 ``Kokkos::sqrt`` or an using-declaration ``using Kokkos::sqrt;`` at local
 scope.
+
+Mathematical constants
+======================
+
+- Avoid taking the address of mathematical constants in device code.  It is not supported by some toolchains, hence not portable.
+
+.. code-block:: cpp
+
+    #include <Kokkos_Core.hpp>
+
+    KOKKOS_FUNCTION void do_math() {
+      // complex constructor takes scalar arguments by reference!
+      Kokkos::complex z1(Kokkos::numbers::pi);
+      // error: identifier "Kokkos::numbers::pi" is undefined in device code
+
+      // 1*pi is a temporary
+      Kokkos::complex z2(1 * Kokkos::numbers::pi);  // OK
+
+      // copy into a local variable
+      auto pi = Kokkos::numbers::pi;
+      Kokkos::complex z3(pi);  // OK
+    }