# -*- coding: utf-8 -*-
r"""
Module Summary
--------------
Interfaces for the NAG Mark 30.0 `dot` Chapter.
``dot`` - Inner Products
This module is concerned with the calculation of innerproducts required by other functions within the NAG Library.
Functionality Index
-------------------
Complex inner product added to initial value, basic/additional precision: :meth:`complex_prec`
Real inner product added to initial value, basic/additional precision: :meth:`real_prec`
For full information please refer to the NAG Library document
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/x03/x03intro.html
"""
# NAG Copyright 2017-2024.
[docs]def real_prec(a, b, c1, c2, sw):
r"""
``real_prec`` calculates the value of a scalar product using basic precision or additional precision and adds it to a basic precision or additional precision initial value.
.. _x03aa-py2-py-doc:
For full information please refer to the NAG Library document for x03aa
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/x03/x03aaf.html
.. _x03aa-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(n\right)`
The elements of the first vector.
**b** : float, array-like, shape :math:`\left(n\right)`
The elements of the second vector.
**c1** : float
:math:`\mathrm{c1}` and :math:`\mathrm{c2}` must specify the initial value :math:`c`: :math:`c = \mathrm{c1}+\mathrm{c2}`. Normally, if :math:`c` is in additional precision, :math:`\mathrm{c1}` specifies the most significant part and :math:`\mathrm{c2}` the least significant part; if :math:`c` is in basic precision, then :math:`\mathrm{c1}` specifies :math:`c` and :math:`\mathrm{c2}` must have the value :math:`0.0`. Both :math:`\mathrm{c1}` and :math:`\mathrm{c2}` must be defined on entry.
**c2** : float
:math:`\mathrm{c1}` and :math:`\mathrm{c2}` must specify the initial value :math:`c`: :math:`c = \mathrm{c1}+\mathrm{c2}`. Normally, if :math:`c` is in additional precision, :math:`\mathrm{c1}` specifies the most significant part and :math:`\mathrm{c2}` the least significant part; if :math:`c` is in basic precision, then :math:`\mathrm{c1}` specifies :math:`c` and :math:`\mathrm{c2}` must have the value :math:`0.0`. Both :math:`\mathrm{c1}` and :math:`\mathrm{c2}` must be defined on entry.
**sw** : bool
The precision to be used in the calculation.
:math:`\mathrm{sw} = \mathbf{True}`
additional precision.
:math:`\mathrm{sw} = \mathbf{False}`
basic precision.
**Returns**
**d1** : float
The result :math:`d`.
If the calculation is in additional precision (:math:`\mathrm{sw} = \mathbf{True}`),
:math:`\mathrm{d1} = d` rounded to basic precision;
:math:`\mathrm{d2} = d-\mathrm{d1}`,
thus :math:`\mathrm{d1}` holds the correctly rounded basic precision result and the sum :math:`\mathrm{d1}+\mathrm{d2}` gives the result in additional precision. :math:`\mathrm{d2}` may have the opposite sign to :math:`\mathrm{d1}`.
If the calculation is in basic precision (:math:`\mathrm{sw} = \mathbf{False}`),
:math:`\mathrm{d1} = d`;
:math:`\mathrm{d2} = 0.0`.
**d2** : float
The result :math:`d`.
If the calculation is in additional precision (:math:`\mathrm{sw} = \mathbf{True}`),
:math:`\mathrm{d1} = d` rounded to basic precision;
:math:`\mathrm{d2} = d-\mathrm{d1}`,
thus :math:`\mathrm{d1}` holds the correctly rounded basic precision result and the sum :math:`\mathrm{d1}+\mathrm{d2}` gives the result in additional precision. :math:`\mathrm{d2}` may have the opposite sign to :math:`\mathrm{d1}`.
If the calculation is in basic precision (:math:`\mathrm{sw} = \mathbf{False}`),
:math:`\mathrm{d1} = d`;
:math:`\mathrm{d2} = 0.0`.
.. _x03aa-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\textit{istepb} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{istepb} > 0`.
(`errno` :math:`1`)
On entry, :math:`\textit{istepa} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{istepa} > 0`.
(`errno` :math:`2`)
On entry, :math:`\textit{isizeb} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{istepb} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{isizeb}\geq \left(n-1\right)\times \textit{istepb}+1`.
(`errno` :math:`2`)
On entry, :math:`\textit{isizea} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{istepa} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{isizea}\geq \left(n-1\right)\times \textit{istepa}+1`.
.. _x03aa-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``real_prec`` calculates the scalar product of two `float` vectors and adds it to an initial value :math:`c` to give a correctly rounded result :math:`d`:
.. math::
d = c+\sum_{{i = 1}}^na_ib_i\text{.}
If :math:`n < 1`, :math:`d = c`.
The vector elements :math:`a_i` and :math:`b_i` are stored in selected elements of the one-dimensional array arguments :math:`\mathrm{a}` and :math:`\mathrm{b}`.
Both the initial value :math:`c` and the result :math:`d` are defined by a pair of `float` variables, so that they may take either basic precision or additional precision values.
(a) If :math:`\mathrm{sw} = \mathbf{True}`, the products are accumulated in additional precision, and on exit the result is available either in basic precision, correctly rounded, or in additional precision.
(#) If :math:`\mathrm{sw} = \mathbf{False}`, the products are accumulated in basic precision, and the result is returned in basic precision.
This function is designed primarily for use as an auxiliary function by other functions in the NAG Library, especially those in the modules on Linear Algebra.
"""
raise NotImplementedError
[docs]def complex_prec(a, b, cx, sw):
r"""
``complex_prec`` calculates the value of a `complex` scalar product using basic precision or additional precision and adds it to a `complex` initial value.
.. _x03ab-py2-py-doc:
For full information please refer to the NAG Library document for x03ab
https://support.nag.com/numeric/nl/nagdoc_30/flhtml/x03/x03abf.html
.. _x03ab-py2-py-parameters:
**Parameters**
**a** : complex, array-like, shape :math:`\left(n\right)`
The elements of the first vector.
**b** : complex, array-like, shape :math:`\left(n\right)`
The elements of the second vector.
**cx** : complex
The initial value :math:`c`.
**sw** : bool
The precision to be used in the calculation.
:math:`\mathrm{sw} = \mathbf{True}`
additional precision.
:math:`\mathrm{sw} = \mathbf{False}`
basic precision.
**Returns**
**dx** : complex
The result :math:`d`.
.. _x03ab-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\textit{istepb} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{istepb} > 0`.
(`errno` :math:`1`)
On entry, :math:`\textit{istepa} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{istepa} > 0`.
(`errno` :math:`2`)
On entry, :math:`\textit{isizeb} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{istepb} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{isizeb}\geq \left(n-1\right)\times \textit{istepb}+1`.
(`errno` :math:`2`)
On entry, :math:`\textit{isizea} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{istepa} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{isizea}\geq \left(n-1\right)\times \textit{istepa}+1`.
.. _x03ab-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``complex_prec`` calculates the scalar product of two `complex` vectors and adds it to an initial value :math:`c` to give a correctly rounded result :math:`d`:
.. math::
d = c+\sum_{{i = 1}}^na_ib_i\text{.}
If :math:`n < 1`, :math:`d = c`.
The vector elements :math:`a_i` and :math:`b_i` are stored in selected elements of the one-dimensional array arguments :math:`\mathrm{a}` and :math:`\mathrm{b}`.
The products are accumulated in basic precision or additional precision depending on the argument :math:`\mathrm{sw}`.
This function has been designed primarily for use as an auxiliary function by other functions in the NAG Library, especially those in the modules on Linear Algebra.
"""
raise NotImplementedError
