# Source code for naginterfaces.library.dot

# -*- coding: utf-8 -*-
r"""
Module Summary
--------------
Interfaces for the NAG Mark 29.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://www.nag.com/numeric/nl/nagdoc_29/flhtml/x03/x03intro.html
"""

[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://www.nag.com/numeric/nl/nagdoc_29/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}

: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://www.nag.com/numeric/nl/nagdoc_29/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}

: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