Source code for naginterfaces.library.orthog

# -*- coding: utf-8 -*-
r"""
Module Summary
--------------
Interfaces for the NAG Mark 30.3 `orthog` Chapter.

``orthog`` - Orthogonalization

This module is concerned with the orthogonalization of vectors in a finite dimensional space.

Functionality Index
-------------------

Schmidt orthogonalization of :math:`n` vectors of order :math:`m`: :meth:`real_gram_schmidt`

For full information please refer to the NAG Library document

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f05/f05intro.html
"""

# NAG Copyright 2017-2024.

def real_gram_schmidt(a, n1):
    r"""
    ``real_gram_schmidt`` applies the Schmidt orthogonalization process to :math:`n` vectors in :math:`m`-dimensional space, :math:`n\leq m`.

    .. _f05aa-py2-py-doc:

    For full information please refer to the NAG Library document for f05aa

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f05/f05aaf.html

    .. _f05aa-py2-py-parameters:

    **Parameters**
        **a** : float, array-like, shape :math:`\left(m, \textit{n2}\right)`
            Columns :math:`\mathrm{n1}` to :math:`\textit{n2}` contain the vectors to be orthogonalized. The vectors are stored by columns in elements :math:`1` to :math:`m`.

        **n1** : int
            The indices of the first and last columns of :math:`A` to be orthogonalized.

    **Returns**
        **a** : float, ndarray, shape :math:`\left(m, \textit{n2}\right)`
            These vectors are overwritten by the orthonormal vectors.

        **cc** : float
            Is used to indicate linear dependence of the original vectors. The nearer :math:`\mathrm{cc}` is to :math:`1.0`, the more likely vector :math:`\mathrm{icol}` is dependent on vectors :math:`\mathrm{n1}` to :math:`\mathrm{icol}-1`. See `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f05/f05aaf.html#fcomments>`__.

        **icol** : int
            The column number corresponding to :math:`\mathrm{cc}`. See `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f05/f05aaf.html#fcomments>`__.

    .. _f05aa-py2-py-errors:

    **Raises**
        **NagValueError**
            (`errno` :math:`1`)
                On entry, :math:`\mathrm{n1} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{n2} = \langle\mathit{\boldsymbol{value}}\rangle`.

                Constraint: :math:`\mathrm{n1}\leq \textit{n2}`.

    .. _f05aa-py2-py-notes:

    **Notes**
        `No equivalent traditional C interface for this routine exists in the NAG Library.`

        ``real_gram_schmidt`` applies the Schmidt orthogonalization process to :math:`n` linearly independent vectors in :math:`m`-dimensional space, :math:`n\leq m`.
        The effect of this process is to replace the original :math:`n` vectors by :math:`n` orthonormal vectors which have the property that the :math:`\textit{r}`\ th vector is linearly dependent on the first :math:`\textit{r}` of the original vectors, and that the sum of squares of the elements of the :math:`\textit{r}`\ th vector is equal to :math:`1`, for :math:`\textit{r} = 1,2,\ldots,n`.
        Inner-products are accumulated using additional precision.
    """
    raise NotImplementedError