Skip to content

Complex operators improved3 #790

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

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

Complex operators improved3 #790

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
fa67fd6
WIP: Updating complex
nliber Jan 21, 2026
8786731
Updated documentation for the following operators:
nliber Jan 23, 2026
defe25d
Updated the following binary operators (as they are constexpr):
nliber Jan 23, 2026
6fc976d
Made unary + and unary - constexpr
nliber Jan 23, 2026
b32d3fa
Changed the deprecation from 5.0.0 to 5.0.2
nliber Jan 23, 2026
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
130 changes: 122 additions & 8 deletions docs/source/API/core/numerics/complex.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,9 @@ Description

* This is intended as a replacement for ``std::complex<T>``.
* Note: If ``z`` has type ``Kokkos::complex<T>``, casting such as ``reinterpret_cast<T(&)[2]>(z)`` leads to undefined behavior (this differs from ``std::complex``).
* Note: operations involving ``std::complex``, ``std::istream`` or ``std::ostream`` are not available on the device.
* Note: while operators may be listed as public member functions or non-member functions, they may be implemented as member functions, free functions or hidden friends.


Interface
---------
Expand Down Expand Up @@ -111,25 +114,33 @@ Interface
Assigns ``i`` to the imaginary component.

.. cpp:function:: constexpr complex& operator+=(complex v) noexcept
.. cpp:function:: constexpr complex& operator+=(std::complex<T> v)
.. cpp:function:: constexpr complex& operator+=(T v) noexcept

Adds the complex value ``complex(v)`` to the complex value ``*this`` and stores the sum in ``*this``.

.. cpp:function:: constexpr complex& operator-=(complex v) noexcept
.. cpp:function:: constexpr complex& operator-=(std::complex<T> v)
.. cpp:function:: constexpr complex& operator-=(T v) noexcept

Subtracts the complex value ``complex(v)`` from the complex value ``*this`` and stores the difference in ``*this``.

.. cpp:function:: constexpr complex& operator*=(complex v) noexcept
.. cpp:function:: constexpr complex& operator*=(std::complex<T> v)
.. cpp:function:: constexpr complex& operator*=(T v) noexcept

Multiplies the complex value ``complex(v)`` by the complex value ``*this`` and stores the product in ``*this``.

.. cpp:function:: constexpr complex& operator/=(complex v) noexcept
.. cpp:function:: constexpr complex& operator/=(std::complex<T> v) noexcept
.. cpp:function:: constexpr complex& operator/=(T v) noexcept

Divides the complex value ``complex(v)`` into the complex value ``*this`` and stores the quotient in ``*this``.

.. note::

The Kokkos implementation of division uses a scaled method, and the result does not necessarily match a similar operation using ``std::complex``, nor are they ``constexpr`` until C++23.

.. cpp:function:: volatile T& real() volatile noexcept

.. deprecated:: 4.0.0
Expand Down Expand Up @@ -181,54 +192,157 @@ Interface

.. rubric:: Non-Member Functions:

.. cpp:function:: constexpr bool operator==(complex x, complex y)
.. cpp:function:: constexpr bool operator==(complex x, T y)
.. cpp:function:: constexpr bool operator==(T x, complex y)
.. cpp:function:: constexpr bool operator==(complex x, std::complex<T> y)
.. cpp:function:: constexpr bool operator==(std::complex<T> x, complex y)

:return: ``true`` if and only if the real component of ``complex(x)`` equals the real component of ``complex(y)`` and the imaginary component of ``complex(x)`` equals the imaginary component of ``complex(y)``.

.. cpp:function:: template<typename T1, typename T2> bool operator==(complex<T1> x, complex<T2> y) noexcept

.. deprecated:: 5.0.2

.. cpp:function:: template<typename T1, typename T2> bool operator==(complex<T1> x, T2 y) noexcept

.. deprecated:: 5.0.2

.. cpp:function:: template<typename T1, typename T2> bool operator==(T1 x, complex<T2> y) noexcept

.. deprecated:: 5.0.2

.. cpp:function:: template<typename T1, typename T2> bool operator==(complex<T1> x, std::complex<T2> y) noexcept

.. deprecated:: 5.0.2

.. cpp:function:: template<typename T1, typename T2> bool operator==(std::complex<T1> x, complex<T2> y) noexcept

:return: ``true`` if and only if the real component of ``complex(x)`` equals the real component of ``complex(y)`` and the imaginary component of ``complex(x)`` equals the imaginary component of ``complex(y)``.
.. deprecated:: 5.0.2

.. cpp:function:: constexpr bool operator!=(complex x, complex y)
.. cpp:function:: constexpr bool operator!=(complex x, T y)
.. cpp:function:: constexpr bool operator!=(T x, complex y)
.. cpp:function:: constexpr bool operator!=(complex x, std::complex<T> y)
.. cpp:function:: constexpr bool operator!=(std::complex<T> x, complex y)

:return: ``!(x == y)``

.. cpp:function:: template<typename T1, typename T2> bool operator!=(complex<T1> x, complex<T2> y) noexcept

.. deprecated:: 5.0.2

.. cpp:function:: template<typename T1, typename T2> bool operator!=(complex<T1> x, T2 y) noexcept

.. deprecated:: 5.0.2

.. cpp:function:: template<typename T1, typename T2> bool operator!=(T1 x, complex<T2> y) noexcept

.. deprecated:: 5.0.2

.. cpp:function:: template<typename T1, typename T2> bool operator!=(complex<T1> x, std::complex<T2> y) noexcept

.. deprecated:: 5.0.2

.. cpp:function:: template<typename T1, typename T2> bool operator!=(std::complex<T1> x, complex<T2> y) noexcept

:return: ``!(x == y)``
.. deprecated:: 5.0.2

.. cpp:function:: template<typename T> complex<T> operator+(complex<T> x) noexcept
.. cpp:function:: constexpr complex operator+(complex x) noexcept

:return: ``x``

.. cpp:function:: constexpr complex operator+(complex x, complex y)
.. cpp:function:: constexpr complex operator+(complex x, T y)
.. cpp:function:: constexpr complex operator+(T x, complex y)
.. cpp:function:: constexpr complex operator+(complex x, std::complex<T> y)
.. cpp:function:: constexpr complex operator+(std::complex<T> x, complex y)

:return: The complex value ``complex(x)`` added to the complex value ``complex(y)``.

.. cpp:function:: template<typename T1, typename T2> complex<std::common_type_t<T1, T2>> operator+(complex<T1> x, complex<T2> y) noexcept

.. deprecated:: 5.0.2

.. cpp:function:: template<typename T1, typename T2> complex<std::common_type_t<T1, T2>> operator+(complex<T1> x, T2 y) noexcept

.. deprecated:: 5.0.2

.. cpp:function:: template<typename T1, typename T2> complex<std::common_type_t<T1, T2>> operator+(T1 x, complex<T2> y) noexcept

:return: The complex value ``complex(x)`` added to the complex value ``complex(y)``.
.. deprecated:: 5.0.2

.. cpp:function:: template<typename T> complex<T> operator-(complex<T> x) noexcept
.. cpp:function:: constexpr complex operator-(complex x) noexcept

:return: ``complex(-x.real(), -x.imag())``

.. cpp:function:: constexpr complex operator-(complex x, complex y)
.. cpp:function:: constexpr complex operator-(complex x, T y)
.. cpp:function:: constexpr complex operator-(T x, complex y)
.. cpp:function:: constexpr complex operator-(complex x, std::complex<T> y)
.. cpp:function:: constexpr complex operator-(std::complex<T> x, complex y)

:return: The complex value ``complex(y)`` subtracted from the complex value ``complex(x)``.

.. cpp:function:: template<typename T1, typename T2> complex<std::common_type_t<T1, T2>> operator-(complex<T1> x, complex<T2> y) noexcept

.. deprecated:: 5.0.2

.. cpp:function:: template<typename T1, typename T2> complex<std::common_type_t<T1, T2>> operator-(complex<T1> x, T2 y) noexcept

.. deprecated:: 5.0.2

.. cpp:function:: template<typename T1, typename T2> complex<std::common_type_t<T1, T2>> operator-(T1 x, complex<T2> y) noexcept

:return: The complex value ``complex(y)`` subtracted from the complex value ``complex(x)``.
.. deprecated:: 5.0.2

.. cpp:function:: constexpr complex operator*(complex x, complex y)
.. cpp:function:: constexpr complex operator*(complex x, T y)
.. cpp:function:: constexpr complex operator*(T x, complex y)
.. cpp:function:: constexpr complex operator*(complex x, std::complex<T> y)
.. cpp:function:: constexpr complex operator*(std::complex<T> x, complex y)

:return: The complex value ``complex(x)`` multiplied by the complex value ``complex(y)``.

.. cpp:function:: template<typename T1, typename T2> complex<std::common_type_t<T1, T2>> operator*(complex<T1> x, complex<T2> y) noexcept

.. deprecated:: 5.0.2

.. cpp:function:: template<typename T1, typename T2> complex<std::common_type_t<T1, T2>> operator*(complex<T1> x, T2 y) noexcept

.. deprecated:: 5.0.2

.. cpp:function:: template<typename T1, typename T2> complex<std::common_type_t<T1, T2>> operator*(T1 x, complex<T2> y) noexcept

.. deprecated:: 5.0.2

.. cpp:function:: template<typename T1, typename T2> complex<std::common_type_t<T1, T2>> operator*(std::complex<T1> x, complex<T2> y) noexcept

:return: The complex value ``complex(x)`` multiplied by the complex value ``complex(y)``.
.. deprecated:: 5.0.2

.. cpp:function:: constexpr complex operator/(complex x, complex y)
.. cpp:function:: constexpr complex operator/(complex x, T y)
.. cpp:function:: constexpr complex operator/(T x, complex y)
.. cpp:function:: constexpr complex operator/(complex x, std::complex<T> y)
.. cpp:function:: constexpr complex operator/(std::complex<T> x, complex y)

:return: The complex value ``complex(y)`` divided into the complex value ``complex(x)``.

.. note::

The Kokkos implementation of division uses a scaled method, and the result does not necessarily match a similar operation using ``std::complex``, nor are they ``constexpr`` until C++23.

.. cpp:function:: template<typename T1, typename T2> complex<std::common_type_t<T1, T2>> operator/(complex<T1> x, complex<T2> y) noexcept

.. deprecated:: 5.0.2

.. cpp:function:: template<typename T1, typename T2> complex<std::common_type_t<T1, T2>> operator/(complex<T1> x, T2 y) noexcept

.. deprecated:: 5.0.2

.. cpp:function:: template<typename T1, typename T2> complex<std::common_type_t<T1, T2>> operator/(T1 x, complex<T2> y) noexcept

:return: The complex value ``complex(y)`` divided into the complex value ``complex(x)``.
.. deprecated:: 5.0.2

.. cpp:function:: template<typename T> std::istream& operator>>(std::ostream& i, complex<T>& x)

Expand Down