From 1c74a26376bf9e7b4ab0fa247b43ddccea5cf8ba Mon Sep 17 00:00:00 2001 From: "Nevin \":-)\" Liber" Date: Thu, 30 Jan 2025 20:07:03 -0600 Subject: [PATCH 1/3] Introductory text and constructors for complex are rewritten. --- docs/source/API/core/utilities/complex.rst | 172 ++++----------------- 1 file changed, 27 insertions(+), 145 deletions(-) diff --git a/docs/source/API/core/utilities/complex.rst b/docs/source/API/core/utilities/complex.rst index 93c6a170d..4e577cdad 100644 --- a/docs/source/API/core/utilities/complex.rst +++ b/docs/source/API/core/utilities/complex.rst @@ -1,177 +1,59 @@ -``Kokkos::complex`` +``complex`` =================== .. role:: cppkokkos(code) :language: cppkokkos -Header File: ```` - -Usage ------ - -.. code-block:: cpp - - Kokkos::complex a,b; - a.imag() = 5.0; a.real() = 1.0 - b = a; - a += b; - +Defined in header ```` which is included from ```` Description ----------- -.. cppkokkos:class:: template complex - - | - - .. rubric:: Public Typedefs - - .. cppkokkos:type:: value_type - - The scalar type of the real and the imaginary component. - - .. rubric:: Private Members - - .. cppkokkos:member:: value_type im - - .. cppkokkos:member:: value_type re - - Private data members representing the real and the imaginary parts. - - .. rubric:: Constructors - - .. cppkokkos:kokkosinlinefunction:: complex(); - - Default constructor. Initializes the ``re`` and ``im`` with ``value_type()``. - - .. cppkokkos:kokkosinlinefunction:: complex(const complex& src); - - Copy constructor. Sets ``re = src.real()`` and ``im = src.imag()``. - - .. cppkokkos:kokkosinlinefunction:: template complex(const T& real); - - Constructor from a real number. Sets ``re = real`` and ``im = value_type()``. - - .. cppkokkos:kokkosinlinefunction:: template complex(const T1& real, const T2& imag) - - Constructor from real numbers. Sets ``re = real`` and ``im = imag``. - - .. cppkokkos:function:: template complex(const std::complex& src); - - Copy constructor. Sets ``re = src.real()`` and ``im = src.imag()``. - - .. rubric:: Assignment and conversion - - .. cppkokkos:kokkosinlinefunction:: template complex& operator= (const complex& src); - - Sets ``re = src.real()`` and ``im = src.imag()``. - - .. cppkokkos:kokkosinlinefunction:: template complex& operator= (const T& re); - - Sets ``re = src.real()`` and ``im = value_type()``. - - .. cppkokkos:kokkosinlinefunction:: template complex& operator= (const std::complex& src); - - Sets ``re = src.real()`` and ``im = src.imag()``. - - .. cppkokkos:function:: operator std::complex() const; - - Returns ``std::complex(re,im)``. - - .. rubric:: Functions - - .. cppkokkos:kokkosinlinefunction:: RealType& imag(); - - Return ``im``. - - .. cppkokkos:kokkosinlinefunction:: RealType& real(); - - Return ``re``. - - .. cppkokkos:kokkosinlinefunction:: const RealType imag() const; - - Return ``im``. - - .. cppkokkos:kokkosinlinefunction:: const RealType real() const; - - Return ``re``. - - .. cppkokkos:kokkosinlinefunction:: void imag(RealType v); - - Sets ``im = v``. - - .. cppkokkos:kokkosinlinefunction:: void real(RealType v); - - Sets ``re = v``. - - .. cppkokkos:kokkosinlinefunction:: template complex& operator += (const complex& src); - - Executes ``re += src.real(); im += src.imag(); return *this;`` - - .. cppkokkos:function:: template complex& operator += (const std::complex& src); - - Executes ``re += src.real(); im += src.imag(); return *this;`` - - .. cppkokkos:kokkosinlinefunction:: template complex& operator += (const T& real); - - Executes ``re += real; return *this;`` - - .. cppkokkos:kokkosinlinefunction:: template complex& operator -= (const complex& src); - - Executes ``re -= src.real(); im -= src.imag(); return *this;`` - - .. cppkokkos:function:: template complex& operator -= (const std::complex& src); - - Executes ``re -= src.real(); im -= src.imag(); return *this;`` - - .. cppkokkos:kokkosinlinefunction:: template complex& operator -= (const T& real); - - Executes ``re -= real; return *this;`` - - .. cppkokkos:kokkosinlinefunction:: template complex& operator *= (const complex& src); +``complex`` is a class template for representing and manipulating complex numbers. - Multiplies the current complex number with the complex number ``src``. +* This is intended as a replacement for ``std::complex``. +* If ``z`` has type ``Kokkos::complex``, casting such as ``reinterpret_cast complex& operator *= (const std::complex& src); +Interface +--------- - Multiplies the current complex number with the complex number ``src``. +.. cppkokkos:class:: template complex - .. cppkokkos:kokkosinlinefunction:: template complex& operator *= (const T& real); + .. rubric:: Template Parameters - Executes ``re *= real; im *= real; return *this;`` + :tparam T: The type of the real and imaginary components. - .. cppkokkos:kokkosinlinefunction:: template complex& operator /= (const complex& src); + * ``T`` must be a floating point type (``float``, ``double``, ``long double``) or an extended floating point type. - Divides the current complex number with the complex number ``src``. + * ``T`` cannot be ``const`` and/or ``volatile`` qualified. - .. cppkokkos:function:: template complex& operator /= (const std::complex& src); + * Some types might not work with a specific backend (such as ``long double`` on CUDA or SYCL). - Divides the current complex number with the complex number ``src``. + .. rubric:: Public Types - .. cppkokkos:kokkosinlinefunction:: template complex& operator /= (const T& real); + .. cppkokkos:type:: value_type = T - Executes ``re /= real; im /= real; return *this;`` + .. rubric:: Constructors - .. cppkokkos:kokkosinlinefunction:: template complex& operator == (const complex& src); + .. cppkokkos:function:: complex() - Returns ``re == src.real() && im == src.imag()``. + Default constructor zero initializes the real and imaginary components. - .. cppkokkos:function:: template complex& operator == (const std::complex& src); + .. cppkokkos:function:: template complex(complex z) noexcept - Returns ``re == src.real() && im == src.imag()``. - .. cppkokkos:kokkosinlinefunction:: template complex& operator == (const T& real); + Conversion constructor initializes the real component to ``static_cast(z.real())`` and the imaginary component to ``static_cast(z.imag())``. - Returns ``re == src.real() && im == value_type()``. + Constraints: ``U`` is convertible to ``T``. - .. cppkokkos:kokkosinlinefunction:: template complex& operator != (const complex& src); + .. cppkokkos:function:: complex(std::complex z) noexcept - Returns ``re != src.real() || im != src.imag()``. + Implicit conversion from ``std::complex`` initializes the real component to ``z.real()`` and the imaginary component to ``z.imag()``. - .. cppkokkos:function:: template complex& operator != (const std::complex& src); + .. cppkokkos:function:: constexpr complex(T r) noexcept - Returns ``re != src.real() || im != src.imag()``. + Initializes the real component to ``r`` and zero initializes the imaginary component. - .. cppkokkos:kokkosinlinefunction:: template complex& operator != (const T& real); + .. cppkokkos:function:: constexpr complex(T r, T i) noexcept - Returns ``re != src.real() || im != value_type()``. + Initializes the real component to ``r`` and the imaginary component to ``i``. From d4399447303132d62cbe1af59bb76252b9ef0099 Mon Sep 17 00:00:00 2001 From: "Nevin \":-)\" Liber" Date: Tue, 4 Feb 2025 18:34:49 -0600 Subject: [PATCH 2/3] Added assignment operators --- docs/source/API/core/utilities/complex.rst | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/source/API/core/utilities/complex.rst b/docs/source/API/core/utilities/complex.rst index 4e577cdad..984dadee9 100644 --- a/docs/source/API/core/utilities/complex.rst +++ b/docs/source/API/core/utilities/complex.rst @@ -33,7 +33,7 @@ Interface .. cppkokkos:type:: value_type = T - .. rubric:: Constructors + .. rubric:: Constructors & Assignment Operators .. cppkokkos:function:: complex() @@ -47,13 +47,24 @@ Interface Constraints: ``U`` is convertible to ``T``. .. cppkokkos:function:: complex(std::complex z) noexcept + .. cppkokkos:function:: complex& operator=(std::complex z) noexcept Implicit conversion from ``std::complex`` initializes the real component to ``z.real()`` and the imaginary component to ``z.imag()``. .. cppkokkos:function:: constexpr complex(T r) noexcept + .. cppkokkos:function:: constexpr complex& operator=(T r) noexcept Initializes the real component to ``r`` and zero initializes the imaginary component. .. cppkokkos:function:: constexpr complex(T r, T i) noexcept Initializes the real component to ``r`` and the imaginary component to ``i``. + + .. deprecated:: 4.x.x + .. cppkokkos:function:: void operator=(const complex&) volatile noexcept + .. cppkokkos:function:: volatile complex& operator=(const volatile complex&) volatile noexcept + .. cppkokkos:function:: complex& operator=(const volatile complex&) noexcept + .. cppkokkos:function:: void operator=(const volatile T&) noexcept + .. cppkokkos:function:: void operator=(const T&) volatile noexcept + + Note: These have templated implementations so as not to be copy assignment operators From 5a61faa7e5c2bcf5c0181f7009ceb090f370fb31 Mon Sep 17 00:00:00 2001 From: "Nevin \":-)\" Liber" Date: Tue, 4 Feb 2025 19:02:55 -0600 Subject: [PATCH 3/3] Added real() and imag() member functions --- docs/source/API/core/utilities/complex.rst | 32 ++++++++++++++++++++-- 1 file changed, 30 insertions(+), 2 deletions(-) diff --git a/docs/source/API/core/utilities/complex.rst b/docs/source/API/core/utilities/complex.rst index 984dadee9..be0ff0f96 100644 --- a/docs/source/API/core/utilities/complex.rst +++ b/docs/source/API/core/utilities/complex.rst @@ -60,11 +60,39 @@ Interface Initializes the real component to ``r`` and the imaginary component to ``i``. - .. deprecated:: 4.x.x + .. deprecated:: 4.0.0 .. cppkokkos:function:: void operator=(const complex&) volatile noexcept .. cppkokkos:function:: volatile complex& operator=(const volatile complex&) volatile noexcept .. cppkokkos:function:: complex& operator=(const volatile complex&) noexcept .. cppkokkos:function:: void operator=(const volatile T&) noexcept .. cppkokkos:function:: void operator=(const T&) volatile noexcept - Note: These have templated implementations so as not to be copy assignment operators + Note: These have templated implementations so as not to be copy assignment operators. + + .. rubric:: Public Member Functions + + .. cppkokkos:function:: operator std::complex() const noexcept + + Conversion operator to ``std::complex``. + + .. cppkokkos:function:: constexpr T& real() noexcept + .. cppkokkos:function:: constexpr T real() const noexcept + .. cppkokkos:function:: [[deprecated("in version 4.0.0")]] volatile T& real() volatile noexcept + .. cppkokkos:function:: [[deprecated("in version 4.0.0")]] T real() const volatile noexcept + + :return: The value of the real component. + + .. cppkokkos:function:: constexpr void real(T r) noexcept + + Assigns ``r`` to the real component. + + .. cppkokkos:function:: constexpr T& imag() noexcept + .. cppkokkos:function:: constexpr T imag() const noexcept + .. cppkokkos:function:: [[deprecated("in version 4.0.0")]] volatile T& imag() volatile noexcept + .. cppkokkos:function:: [[deprecated("in version 4.0.0")]] T imag() const volatile noexcept + + :return: The value of the imaginary component. + + .. cppkokkos:function:: constexpr void imag(T i) noexcept + + Assigns ``i`` to the imaginary component.