# -*- coding: utf-8 -*-
r"""
Module Summary
--------------
Interfaces for the NAG Mark 30.2 `complex` Chapter.
``complex`` - Complex Arithmetic
This module provides facilities for arithmetic operations involving complex numbers.
Functionality Index
-------------------
**Complex numbers**
division: :meth:`divide`
modulus: :meth:`abs`
square root: :meth:`sqrt`
For full information please refer to the NAG Library document
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/a02/a02intro.html
"""
# NAG Copyright 2017-2024.
[docs]def sqrt(xr, xi):
r"""
``sqrt`` evaluates the square root of the complex number :math:`x = \left(x_r, x_i\right)`.
.. _a02aa-py2-py-doc:
For full information please refer to the NAG Library document for a02aa
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/a02/a02aaf.html
.. _a02aa-py2-py-parameters:
**Parameters**
**xr** : float
:math:`x_r`, the real part of :math:`x`.
**xi** : float
:math:`x_i`, the imaginary part of :math:`x`.
**Returns**
**yr** : float
:math:`y_r`, the real part of :math:`y`.
**yi** : float
:math:`y_i`, the imaginary part of :math:`y`.
.. _a02aa-py2-py-notes:
**Notes**
`In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.`
The method of evaluating :math:`y = \sqrt{x}` depends on the value of :math:`x_r`.
For :math:`x_r\geq 0`,
.. math::
y_r = \sqrt{\frac{{x_r+\sqrt{x_r^2+x_i^2}}}{2}}\text{, }\quad y_i = \frac{x_i}{{2y_r}}\text{.}
For :math:`x_r < 0`,
.. math::
y_i = \mathrm{sign}\left(x_i\right)\times \sqrt{\frac{{\left\lvert x_r\right\rvert +\sqrt{x_r^2+x_i^2}}}{2}}\text{, }\quad y_r = \frac{x_i}{{2y_i}}\text{.}
Overflow is avoided when squaring :math:`x_i` and :math:`x_r` by calling :meth:`abs` to evaluate :math:`\sqrt{x_r^2+x_i^2}`.
.. _a02aa-py2-py-references:
**References**
Wilkinson, J H and Reinsch, C, 1971, `Handbook for Automatic Computation II, Linear Algebra`, Springer--Verlag
"""
raise NotImplementedError
[docs]def abs(xr, xi): # pylint: disable=redefined-builtin
r"""
``abs`` returns the value of the modulus of the complex number :math:`x = \left(x_r, x_i\right)`.
.. _a02ab-py2-py-doc:
For full information please refer to the NAG Library document for a02ab
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/a02/a02abf.html
.. _a02ab-py2-py-parameters:
**Parameters**
**xr** : float
:math:`x_r`, the real part of :math:`x`.
**xi** : float
:math:`x_i`, the imaginary part of :math:`x`.
**Returns**
**xa** : float
The modulus of the complex number :math:`x = \left(x_r, x_i\right)`.
.. _a02ab-py2-py-notes:
**Notes**
`In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.`
The function evaluates :math:`\sqrt{x_r^2+x_i^2}` by using :math:`a\sqrt{1+\left(\frac{b}{a}\right)^2}` where :math:`a` is the larger of :math:`\left\lvert x_r\right\rvert` and :math:`\left\lvert x_i\right\rvert`, and :math:`b` is the smaller of :math:`\left\lvert x_r\right\rvert` and :math:`\left\lvert x_i\right\rvert`.
This ensures against unnecessary overflow and loss of accuracy when calculating :math:`\left(x_r^2+x_i^2\right)`.
.. _a02ab-py2-py-references:
**References**
Wilkinson, J H and Reinsch, C, 1971, `Handbook for Automatic Computation II, Linear Algebra`, Springer--Verlag
"""
raise NotImplementedError
[docs]def divide(xr, xi, yr, yi):
r"""
``divide`` divides one complex number, :math:`x = \left(x_r, x_i\right)`, by a second complex number, :math:`y = \left(y_r, y_i\right)`, returning the result in :math:`z = \left(z_r, z_i\right)`.
.. _a02ac-py2-py-doc:
For full information please refer to the NAG Library document for a02ac
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/a02/a02acf.html
.. _a02ac-py2-py-parameters:
**Parameters**
**xr** : float
:math:`x_r`, the real part of :math:`x`.
**xi** : float
:math:`x_i`, the imaginary part of :math:`x`.
**yr** : float
:math:`y_r`, the real part of :math:`y`.
**yi** : float
:math:`y_i`, the imaginary part of :math:`y`.
**Returns**
**zr** : float
:math:`z_r`, the real part of :math:`z`.
**zi** : float
:math:`z_i`, the imaginary part of :math:`z`.
.. _a02ac-py2-py-notes:
**Notes**
`In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.`
The result :math:`z` is calculated using Smith's algorithm with scaling, from Li `et al.` (2002), which ensures that no unnecessary overflow or underflow occurs at intermediate stages of the computation.
.. _a02ac-py2-py-references:
**References**
Li, X S, Demmel, J W, Bailey, D H, Henry, G, Hida, Y, Iskandar, J, Kahan, W, Kapur, A, Martin, M C, Tung, T and Yoo, D J, 2002, `Design, implementation and testing of extended and mixed precision BLAS`, ACM Trans. Math. Soft. (28(2)), 152--205
"""
raise NotImplementedError
