Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Complex #626

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

Complex #626

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1c74a26
Introductory text and constructors for complex are rewritten.
nliber Jan 31, 2025
d439944
Added assignment operators
nliber Feb 5, 2025
5a61faa
Added real() and imag() member functions
nliber Feb 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
185 changes: 53 additions & 132 deletions docs/source/API/core/utilities/complex.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,177 +1,98 @@
``Kokkos::complex``
``complex``
===================

.. role:: cppkokkos(code)
:language: cppkokkos

Header File: ``<Kokkos_Core.hpp>``

Usage
-----

.. code-block:: cpp

Kokkos::complex<double> a,b;
a.imag() = 5.0; a.real() = 1.0
b = a;
a += b;

Defined in header ``<Kokkos_Complex.hpp>`` which is included from ``<Kokkos_Core.hpp>``

Description
-----------

.. cppkokkos:class:: template<class Scalar> 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<class T> complex(const T& real);

Constructor from a real number. Sets ``re = real`` and ``im = value_type()``.

.. cppkokkos:kokkosinlinefunction:: template <class T1, class T2> complex(const T1& real, const T2& imag)

Constructor from real numbers. Sets ``re = real`` and ``im = imag``.

.. cppkokkos:function:: template<class T> complex(const std::complex<T>& src);

Copy constructor. Sets ``re = src.real()`` and ``im = src.imag()``.

.. rubric:: Assignment and conversion

.. cppkokkos:kokkosinlinefunction:: template<class T> complex<Scalar>& operator= (const complex<T>& src);

Sets ``re = src.real()`` and ``im = src.imag()``.

.. cppkokkos:kokkosinlinefunction:: template<class T> complex<Scalar>& operator= (const T& re);

Sets ``re = src.real()`` and ``im = value_type()``.

.. cppkokkos:kokkosinlinefunction:: template<class T> complex<Scalar>& operator= (const std::complex<T>& src);

Sets ``re = src.real()`` and ``im = src.imag()``.

.. cppkokkos:function:: operator std::complex<value_type>() const;

Returns ``std::complex<value_type>(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``.
``complex`` is a class template for representing and manipulating complex numbers.

.. cppkokkos:kokkosinlinefunction:: template<class T> complex& operator += (const complex<T>& src);
* This is intended as a replacement for ``std::complex<T>``.
* If ``z`` has type ``Kokkos::complex<T>``, casting such as ``reinterpret_cast<T(&)[2](z)`` lead to undefined behavior. Note: This differs from ``std::complex``.

Executes ``re += src.real(); im += src.imag(); return *this;``
Interface
---------

.. cppkokkos:function:: template<class T> complex& operator += (const std::complex<T>& src);
.. cppkokkos:class:: template<class T> complex

Executes ``re += src.real(); im += src.imag(); return *this;``
.. rubric:: Template Parameters

.. cppkokkos:kokkosinlinefunction:: template<class T> complex& operator += (const T& real);
:tparam T: The type of the real and imaginary components.

Executes ``re += real; return *this;``
* ``T`` must be a floating point type (``float``, ``double``, ``long double``) or an extended floating point type.

.. cppkokkos:kokkosinlinefunction:: template<class T> complex& operator -= (const complex<T>& src);
* ``T`` cannot be ``const`` and/or ``volatile`` qualified.

Executes ``re -= src.real(); im -= src.imag(); return *this;``
* Some types might not work with a specific backend (such as ``long double`` on CUDA or SYCL).

.. cppkokkos:function:: template<class T> complex& operator -= (const std::complex<T>& src);
.. rubric:: Public Types

Executes ``re -= src.real(); im -= src.imag(); return *this;``
.. cppkokkos:type:: value_type = T

.. cppkokkos:kokkosinlinefunction:: template<class T> complex& operator -= (const T& real);
.. rubric:: Constructors & Assignment Operators

Executes ``re -= real; return *this;``
.. cppkokkos:function:: complex()

.. cppkokkos:kokkosinlinefunction:: template<class T> complex& operator *= (const complex<T>& src);
Default constructor zero initializes the real and imaginary components.

Multiplies the current complex number with the complex number ``src``.
.. cppkokkos:function:: template<class U> complex(complex<U> z) noexcept

.. cppkokkos:function:: template<class T> complex& operator *= (const std::complex<T>& src);

Multiplies the current complex number with the complex number ``src``.
Conversion constructor initializes the real component to ``static_cast<T>(z.real())`` and the imaginary component to ``static_cast<T>(z.imag())``.

.. cppkokkos:kokkosinlinefunction:: template<class T> complex& operator *= (const T& real);
Constraints: ``U`` is convertible to ``T``.

Executes ``re *= real; im *= real; return *this;``
.. cppkokkos:function:: complex(std::complex<T> z) noexcept
.. cppkokkos:function:: complex& operator=(std::complex<T> z) noexcept

.. cppkokkos:kokkosinlinefunction:: template<class T> complex& operator /= (const complex<T>& src);
Implicit conversion from ``std::complex`` initializes the real component to ``z.real()`` and the imaginary component to ``z.imag()``.

Divides the current complex number with the complex number ``src``.
.. cppkokkos:function:: constexpr complex(T r) noexcept
.. cppkokkos:function:: constexpr complex& operator=(T r) noexcept

.. cppkokkos:function:: template<class T> complex& operator /= (const std::complex<T>& src);
Initializes the real component to ``r`` and zero initializes the imaginary component.

Divides the current complex number with the complex number ``src``.
.. cppkokkos:function:: constexpr complex(T r, T i) noexcept

.. cppkokkos:kokkosinlinefunction:: template<class T> complex& operator /= (const T& real);
Initializes the real component to ``r`` and the imaginary component to ``i``.

Executes ``re /= real; im /= real; return *this;``
.. 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

.. cppkokkos:kokkosinlinefunction:: template<class T> complex& operator == (const complex<T>& src);
Note: These have templated implementations so as not to be copy assignment operators.

Returns ``re == src.real() && im == src.imag()``.
.. rubric:: Public Member Functions

.. cppkokkos:function:: template<class T> complex& operator == (const std::complex<T>& src);
.. cppkokkos:function:: operator std::complex<T>() const noexcept

Returns ``re == src.real() && im == src.imag()``.
Conversion operator to ``std::complex``.

.. cppkokkos:kokkosinlinefunction:: template<class T> complex& operator == (const T& real);
.. 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

Returns ``re == src.real() && im == value_type()``.
:return: The value of the real component.

.. cppkokkos:kokkosinlinefunction:: template<class T> complex& operator != (const complex<T>& src);
.. cppkokkos:function:: constexpr void real(T r) noexcept

Returns ``re != src.real() || im != src.imag()``.
Assigns ``r`` to the real component.

.. cppkokkos:function:: template<class T> complex& operator != (const std::complex<T>& src);
.. 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

Returns ``re != src.real() || im != src.imag()``.
:return: The value of the imaginary component.

.. cppkokkos:kokkosinlinefunction:: template<class T> complex& operator != (const T& real);
.. cppkokkos:function:: constexpr void imag(T i) noexcept

Returns ``re != src.real() || im != value_type()``.
Assigns ``i`` to the imaginary component.