Source code for naginterfaces.library.lapacklin

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

``lapacklin`` - Linear Equations (LAPACK)

This module provides functions for the solution of systems of simultaneous linear equations, and associated computations.
It provides functions for

    matrix factorizations;

    solution of linear equations;

    estimating matrix condition numbers;

    computing error bounds for the solution of linear equations;

    matrix inversion;

    computing scaling factors to equilibrate a matrix.

Functions are provided for both `real` and `complex` data.

For a general introduction to the solution of systems of linear equations, you should turn first to `the F04 Introduction <https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f04/f04intro.html>`__.
The decision trees, in `the F04 Introduction <https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f04/f04intro.html#dtree>`__, direct you to the most appropriate functions in submodule :mod:`~naginterfaces.library.linsys` or submodule ``lapacklin`` for solving your particular problem.
In particular, submodule :mod:`~naginterfaces.library.linsys` and submodule ``lapacklin`` contain `Black Box` (or `driver`) functions which enable some standard types of problem to be solved by a call to a single function.
Where possible, functions in submodule :mod:`~naginterfaces.library.linsys` call submodule ``lapacklin`` functions to perform the necessary computational tasks.

There are two types of driver functions in this module: `simple drivers` which just return the solution to the linear equations; and `expert drivers` which also return condition and error estimates and, in many cases, also allow equilibration.
The simple drivers for real matrices have names of the form and for complex matrices have names of the form The expert drivers for real matrices have names of the form and for complex matrices have names of the form

The functions in this module (submodule ``lapacklin``) handle only `dense` and `band` matrices (not matrices with more specialised structures, or general sparse matrices).

The functions in this module have all been derived from the LAPACK project (see Anderson `et al.` (1999)).
They have been designed to be efficient on a wide range of high-performance computers, without compromising efficiency on conventional serial machines.

See Also
--------
``naginterfaces.library.examples.lapacklin`` :
    This subpackage contains examples for the ``lapacklin`` module.
    See also the :ref:`library_lapacklin_ex` subsection.

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

**Apply iterative refinement to the solution and compute error estimates**

  after factorizing the matrix of coefficients

    complex band matrix: :meth:`zgbrfs`

    complex Hermitian indefinite matrix: :meth:`zherfs`

    complex Hermitian indefinite matrix, packed storage: :meth:`zhprfs`

    complex Hermitian positive definite band matrix: :meth:`zpbrfs`

    complex Hermitian positive definite matrix: :meth:`zporfs`

    complex Hermitian positive definite matrix, packed storage: :meth:`zpprfs`

    complex Hermitian positive definite tridiagonal matrix: :meth:`zptrfs`

    complex matrix: :meth:`zgerfs`

    complex symmetric indefinite matrix: :meth:`zsyrfs`

    complex symmetric indefinite matrix, packed storage: :meth:`zsprfs`

    complex tridiagonal matrix: :meth:`zgtrfs`

    real band matrix: :meth:`dgbrfs`

    real matrix: :meth:`dgerfs`

    real symmetric indefinite matrix: :meth:`dsyrfs`

    real symmetric indefinite matrix, packed storage: :meth:`dsprfs`

    real symmetric positive definite band matrix: :meth:`dpbrfs`

    real symmetric positive definite matrix: :meth:`dporfs`

    real symmetric positive definite matrix, packed storage: :meth:`dpprfs`

    real symmetric positive definite tridiagonal matrix: :meth:`dptrfs`

    real tridiagonal matrix: :meth:`dgtrfs`

**Compute error estimates**

  complex triangular band matrix: :meth:`ztbrfs`

  complex triangular matrix: :meth:`ztrrfs`

  complex triangular matrix, packed storage: :meth:`ztprfs`

  real triangular band matrix: :meth:`dtbrfs`

  real triangular matrix: :meth:`dtrrfs`

  real triangular matrix, packed storage: :meth:`dtprfs`

**Compute row and column scalings**

  complex band matrix: :meth:`zgbequ`

  complex Hermitian positive definite band matrix: :meth:`zpbequ`

  complex Hermitian positive definite matrix: :meth:`zpoequ`

  complex Hermitian positive definite matrix, packed storage: :meth:`zppequ`

  complex matrix: :meth:`zgeequ`

  real band matrix: :meth:`dgbequ`

  real matrix: :meth:`dgeequ`

  real symmetric positive definite band matrix: :meth:`dpbequ`

  real symmetric positive definite matrix: :meth:`dpoequ`

  real symmetric positive definite matrix, packed storage: :meth:`dppequ`

**Condition number estimation**

  after factorizing the matrix of coefficients

    complex band matrix: :meth:`zgbcon`

    complex Hermitian indefinite matrix: :meth:`zhecon`

    complex Hermitian indefinite matrix, packed storage: :meth:`zhpcon`

    complex Hermitian positive definite band matrix: :meth:`zpbcon`

    complex Hermitian positive definite matrix: :meth:`zpocon`

    complex Hermitian positive definite matrix, packed storage: :meth:`zppcon`

    complex Hermitian positive definite tridiagonal matrix: :meth:`zptcon`

    complex matrix: :meth:`zgecon`

    complex symmetric indefinite matrix: :meth:`zsycon`

    complex symmetric indefinite matrix, packed storage: :meth:`zspcon`

    complex tridiagonal matrix: :meth:`zgtcon`

    real band matrix: :meth:`dgbcon`

    real matrix: :meth:`dgecon`

    real symmetric indefinite matrix: :meth:`dsycon`

    real symmetric indefinite matrix, packed storage: :meth:`dspcon`

    real symmetric positive definite band matrix: :meth:`dpbcon`

    real symmetric positive definite matrix: :meth:`dpocon`

    real symmetric positive definite matrix, packed storage: :meth:`dppcon`

    real symmetric positive definite tridiagonal matrix: :meth:`dptcon`

    real tridiagonal matrix: :meth:`dgtcon`

  complex triangular band matrix: :meth:`ztbcon`

  complex triangular matrix: :meth:`ztrcon`

  complex triangular matrix, packed storage: :meth:`ztpcon`

  real triangular band matrix: :meth:`dtbcon`

  real triangular matrix: :meth:`dtrcon`

  real triangular matrix, packed storage: :meth:`dtpcon`

:math:`LDL^\mathrm{T}` **factorization**

  complex Hermitian positive definite tridiagonal matrix: :meth:`zpttrf`

  real symmetric positive definite tridiagonal matrix: :meth:`dpttrf`

:math:`LL^\mathrm{H}` **or** :math:`U^\mathrm{H}U` **factorization**

  complex Hermitian positive definite band matrix: :meth:`zpbtrf`

  complex Hermitian positive definite matrix: :meth:`zpotrf`

  complex Hermitian positive definite matrix, packed storage: :meth:`zpptrf`

  complex Hermitian positive definite matrix, RFP storage: :meth:`zpftrf`

  complex Hermitian positive semidefinite matrix: :meth:`zpstrf`

:math:`LL^\mathrm{T}` **or** :math:`U^\mathrm{T}U` **factorization**

  real symmetric positive definite band matrix: :meth:`dpbtrf`

  real symmetric positive definite matrix: :meth:`dpotrf`

  real symmetric positive definite matrix, packed storage: :meth:`dpptrf`

  real symmetric positive definite matrix, RFP storage: :meth:`dpftrf`

  real symmetric positive semidefinite matrix: :meth:`dpstrf`

:math:`LU` **factorization**

  complex band matrix: :meth:`zgbtrf`

  complex matrix: :meth:`zgetrf`

  complex tridiagonal matrix: :meth:`zgttrf`

  real band matrix: :meth:`dgbtrf`

  real matrix: :meth:`dgetrf`

  real tridiagonal matrix: :meth:`dgttrf`

**Matrix inversion**

  after factorizing the matrix of coefficients

    complex Hermitian indefinite matrix: :meth:`zhetri`

    complex Hermitian indefinite matrix, packed storage: :meth:`zhptri`

    complex Hermitian positive definite matrix: :meth:`zpotri`

    complex Hermitian positive definite matrix, packed storage: :meth:`zpptri`

    complex Hermitian positive definite matrix, RFP storage: :meth:`zpftri`

    complex matrix: :meth:`zgetri`

    complex symmetric indefinite matrix: :meth:`zsytri`

    complex symmetric indefinite matrix, packed storage: :meth:`zsptri`

    real matrix: :meth:`dgetri`

    real symmetric indefinite matrix: :meth:`dsytri`

    real symmetric indefinite matrix, packed storage: :meth:`dsptri`

    real symmetric positive definite matrix: :meth:`dpotri`

    real symmetric positive definite matrix, packed storage: :meth:`dpptri`

    real symmetric positive definite matrix, RFP storage: :meth:`dpftri`

  complex triangular matrix: :meth:`ztrtri`

  complex triangular matrix, packed storage: :meth:`ztptri`

  complex triangular matrix, RFP storage

    expert driver: :meth:`ztftri`

  real triangular matrix: :meth:`dtrtri`

  real triangular matrix, packed storage: :meth:`dtptri`

  real triangular matrix, RFP storage

    expert driver: :meth:`dtftri`

:math:`PLDL^\mathrm{H}P^\mathrm{H}` **or** :math:`PUDU^\mathrm{H}P^\mathrm{H}` **factorization**

  complex Hermitian indefinite matrix: :meth:`zhetrf`

  complex Hermitian indefinite matrix, packed storage: :meth:`zhptrf`

:math:`PLDL^\mathrm{T}P^\mathrm{T}` **or** :math:`PUDU^\mathrm{T}P^\mathrm{T}` **factorization**

  complex symmetric indefinite matrix: :meth:`zsytrf`

  complex symmetric indefinite matrix, packed storage: :meth:`zsptrf`

  real symmetric indefinite matrix: :meth:`dsytrf`

  real symmetric indefinite matrix, packed storage: :meth:`dsptrf`

**Solution of simultaneous linear equations**

  after factorizing the matrix of coefficients

    complex band matrix: :meth:`zgbtrs`

    complex Hermitian indefinite matrix: :meth:`zhetrs`

    complex Hermitian indefinite matrix, packed storage: :meth:`zhptrs`

    complex Hermitian positive definite band matrix: :meth:`zpbtrs`

    complex Hermitian positive definite matrix: :meth:`zpotrs`

    complex Hermitian positive definite matrix, packed storage: :meth:`zpptrs`

    complex Hermitian positive definite matrix, RFP storage: :meth:`zpftrs`

    complex Hermitian positive definite tridiagonal matrix: :meth:`zpttrs`

    complex matrix: :meth:`zgetrs`

    complex symmetric indefinite matrix: :meth:`zsytrs`

    complex symmetric indefinite matrix, packed storage: :meth:`zsptrs`

    complex tridiagonal matrix: :meth:`zgttrs`

    real band matrix: :meth:`dgbtrs`

    real matrix: :meth:`dgetrs`

    real symmetric indefinite matrix: :meth:`dsytrs`

    real symmetric indefinite matrix, packed storage: :meth:`dsptrs`

    real symmetric positive definite band matrix: :meth:`dpbtrs`

    real symmetric positive definite matrix: :meth:`dpotrs`

    real symmetric positive definite matrix, packed storage: :meth:`dpptrs`

    real symmetric positive definite matrix, RFP storage: :meth:`dpftrs`

    real symmetric positive definite tridiagonal matrix: :meth:`dpttrs`

    real tridiagonal matrix: :meth:`dgttrs`

  expert drivers (with condition and error estimation)

    complex band matrix: :meth:`zgbsvx`

    complex Hermitian indefinite matrix: :meth:`zhesvx`

    complex Hermitian indefinite matrix, packed storage: :meth:`zhpsvx`

    complex Hermitian positive definite band matrix: :meth:`zpbsvx`

    complex Hermitian positive definite matrix: :meth:`zposvx`

    complex Hermitian positive definite matrix, packed storage: :meth:`zppsvx`

    complex Hermitian positive definite tridiagonal matrix: :meth:`zptsvx`

    complex matrix: :meth:`zgesvx`

    complex symmetric indefinite matrix: :meth:`zsysvx`

    complex symmetric indefinite matrix, packed storage: :meth:`zspsvx`

    complex tridiagonal matrix: :meth:`zgtsvx`

    real band matrix: :meth:`dgbsvx`

    real matrix: :meth:`dgesvx`

    real symmetric indefinite matrix: :meth:`dsysvx`

    real symmetric indefinite matrix, packed storage: :meth:`dspsvx`

    real symmetric positive definite band matrix: :meth:`dpbsvx`

    real symmetric positive definite matrix: :meth:`dposvx`

    real symmetric positive definite matrix, packed storage: :meth:`dppsvx`

    real symmetric positive definite tridiagonal matrix: :meth:`dptsvx`

    real tridiagonal matrix: :meth:`dgtsvx`

  simple drivers

    complex band matrix: :meth:`zgbsv`

    complex Hermitian indefinite matrix: :meth:`zhesv`

    complex Hermitian indefinite matrix, packed storage: :meth:`zhpsv`

    complex Hermitian positive definite band matrix: :meth:`zpbsv`

    complex Hermitian positive definite matrix: :meth:`zposv`

    complex Hermitian positive definite matrix, packed storage: :meth:`zppsv`

    complex Hermitian positive definite matrix, using mixed precision: :meth:`zcposv`

    complex Hermitian positive definite tridiagonal matrix: :meth:`zptsv`

    complex matrix: :meth:`zgesv`

    complex matrix, using mixed precision: :meth:`zcgesv`

    complex symmetric indefinite matrix: :meth:`zsysv`

    complex symmetric indefinite matrix, packed storage: :meth:`zspsv`

    complex triangular band matrix: :meth:`ztbtrs`

    complex triangular matrix: :meth:`ztrtrs`

    complex triangular matrix, packed storage: :meth:`ztptrs`

    complex tridiagonal matrix: :meth:`zgtsv`

    real band matrix: :meth:`dgbsv`

    real matrix: :meth:`dgesv`

    real matrix, using mixed precision: :meth:`dsgesv`

    real symmetric indefinite matrix: :meth:`dsysv`

    real symmetric indefinite matrix, packed storage: :meth:`dspsv`

    real symmetric positive definite band matrix: :meth:`dpbsv`

    real symmetric positive definite matrix: :meth:`dposv`

    real symmetric positive definite matrix, packed storage: :meth:`dppsv`

    real symmetric positive definite matrix, using mixed precision: :meth:`dsposv`

    real symmetric positive definite tridiagonal matrix: :meth:`dptsv`

    real triangular band matrix: :meth:`dtbtrs`

    real triangular matrix: :meth:`dtrtrs`

    real triangular matrix, packed storage: :meth:`dtptrs`

    real tridiagonal matrix: :meth:`dgtsv`

For full information please refer to the NAG Library document

https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07intro.html
"""

# NAG Copyright 2017-2021.

[docs]def dgesv(a, b): r""" ``dgesv`` computes the solution to a real system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices. .. _f07aa-py2-py-doc: For full information please refer to the NAG Library document for f07aa https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07aaf.html .. _f07aa-py2-py-parameters: **Parameters** **a** : float, array-like, shape :math:`\left(n, n\right)` The :math:`n\times n` coefficient matrix :math:`A`. **b** : float, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **a** : float, ndarray, shape :math:`\left(n, n\right)` The factors :math:`L` and :math:`U` from the factorization :math:`A = PLU`; the unit diagonal elements of :math:`L` are not stored. **ipiv** : int, ndarray, shape :math:`\left(n\right)` If no constraints are violated, the pivot indices that define the permutation matrix :math:`P`; at the :math:`i`\ th step row :math:`i` of the matrix was interchanged with row :math:`\mathrm{ipiv}[i-1]`. :math:`\mathrm{ipiv}[i-1] = i` indicates a row interchange was not required. **b** : float, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`. .. _f07aa-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`U` is exactly singular, so the solution could not be computed. .. _f07aa-py2-py-notes: **Notes** ``dgesv`` uses the :math:`LU` decomposition with partial pivoting and row interchanges to factor :math:`A` as .. math:: A = PLU\text{,} where :math:`P` is a permutation matrix, :math:`L` is unit lower triangular, and :math:`U` is upper triangular. The factored form of :math:`A` is then used to solve the system of equations :math:`AX = B`. .. _f07aa-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore See Also -------- :meth:`naginterfaces.library.examples.lapacklin.dgesv_ex.main` """ raise NotImplementedError
[docs]def dgesvx(fact, trans, n, nrhs, a, equed, b, af=None, ipiv=None, r=None, c=None): r""" ``dgesvx`` uses the :math:`LU` factorization to compute the solution to a real system of linear equations .. math:: AX = B\quad \text{ or }\quad A^\mathrm{T}X = B\text{,} where :math:`A` is an :math:`n\times n` matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices. Error bounds on the solution and a condition estimate are also provided. .. _f07ab-py2-py-doc: For full information please refer to the NAG Library document for f07ab https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07abf.html .. _f07ab-py2-py-parameters: **Parameters** **fact** : str, length 1 Specifies whether or not the factorized form of the matrix :math:`A` is supplied on entry, and if not, whether the matrix :math:`A` should be equilibrated before it is factorized. :math:`\mathrm{fact} = \texttt{'F'}` :math:`\mathrm{af}` and :math:`\mathrm{ipiv}` contain the factorized form of :math:`A`. If :math:`\mathrm{equed} \neq \texttt{'N'}`, the matrix :math:`A` has been equilibrated with scaling factors given by :math:`\mathrm{r}` and :math:`\mathrm{c}`. :math:`\mathrm{a}`, :math:`\mathrm{af}` and :math:`\mathrm{ipiv}` are not modified. :math:`\mathrm{fact} = \texttt{'N'}` The matrix :math:`A` will be copied to :math:`\mathrm{af}` and factorized. :math:`\mathrm{fact} = \texttt{'E'}` The matrix :math:`A` will be equilibrated if necessary, then copied to :math:`\mathrm{af}` and factorized. **trans** : str, length 1 Specifies the form of the system of equations. :math:`\mathrm{trans} = \texttt{'N'}` :math:`AX = B` (No transpose). :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}` :math:`A^\mathrm{T}X = B` (Transpose). **n** : int :math:`n`, the number of linear equations, i.e., the order of the matrix :math:`A`. **nrhs** : int :math:`r`, the number of right-hand sides, i.e., the number of columns of the matrix :math:`B`. **a** : float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` The :math:`n\times n` matrix :math:`A`. If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} \neq \texttt{'N'}`, :math:`\mathrm{a}` must have been equilibrated by the scaling factors in :math:`\mathrm{r}` and/or :math:`\mathrm{c}`. **equed** : None or str, length 1 If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{equed}` need not be set. If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` must specify the form of the equilibration that was performed as follows: if :math:`\mathrm{equed} = \texttt{'N'}`, no equilibration; if :math:`\mathrm{equed} = \texttt{'R'}`, row equilibration, i.e., :math:`A` has been premultiplied by :math:`D_R`; if :math:`\mathrm{equed} = \texttt{'C'}`, column equilibration, i.e., :math:`A` has been postmultiplied by :math:`D_C`; if :math:`\mathrm{equed} = \texttt{'B'}`, both row and column equilibration, i.e., :math:`A` has been replaced by :math:`D_RAD_C`. **b** : float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **af** : None or float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)`, optional If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{af}` contains the factors :math:`L` and :math:`U` from the factorization :math:`A = PLU` as computed by :meth:`dgetrf`. If :math:`\mathrm{equed} \neq \texttt{'N'}`, :math:`\mathrm{af}` is the factorized form of the equilibrated matrix :math:`A`. If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{af}` need not be set. **ipiv** : None or int, array-like, shape :math:`\left(\mathrm{n}\right)`, optional If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{ipiv}` contains the pivot indices from the factorization :math:`A = PLU` as computed by :meth:`dgetrf`; at the :math:`i`\ th step row :math:`i` of the matrix was interchanged with row :math:`\mathrm{ipiv}[i-1]`. :math:`\mathrm{ipiv}[i-1] = i` indicates a row interchange was not required. If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{ipiv}` need not be set. **r** : None or float, array-like, shape :math:`\left(\mathrm{n}\right)`, optional If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{r}` need not be set. If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{r}` must contain the row scale factors for :math:`A`, :math:`D_R`; each element of :math:`\mathrm{r}` must be positive. **c** : None or float, array-like, shape :math:`\left(\mathrm{n}\right)`, optional If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{c}` need not be set. If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'C'}` or :math:`\texttt{'B'}`, :math:`\mathrm{c}` must contain the column scale factors for :math:`A`, :math:`D_C`; each element of :math:`\mathrm{c}` must be positive. **Returns** **a** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'F'}` or :math:`\texttt{'N'}`, or if :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{a}` is not modified. If :math:`\mathrm{fact} = \texttt{'E'}` or :math:`\mathrm{equed} \neq \texttt{'N'}`, :math:`A` is scaled as follows: if :math:`\mathrm{equed} = \texttt{'R'}`, :math:`A = D_RA`; if :math:`\mathrm{equed} = \texttt{'C'}`, :math:`A = AD_C`; if :math:`\mathrm{equed} = \texttt{'B'}`, :math:`A = D_RAD_C`. **af** : None or float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{af}` returns the factors :math:`L` and :math:`U` from the factorization :math:`A = PLU` of the original matrix :math:`A`. If :math:`\mathrm{fact} = \texttt{'E'}`, :math:`\mathrm{af}` returns the factors :math:`L` and :math:`U` from the factorization :math:`A = PLU` of the equilibrated matrix :math:`A` (see the description of :math:`\mathrm{a}` for the form of the equilibrated matrix). If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{af}` is unchanged from entry. **ipiv** : None or int, ndarray, shape :math:`\left(\mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{ipiv}` contains the pivot indices from the factorization :math:`A = PLU` of the original matrix :math:`A`. If :math:`\mathrm{fact} = \texttt{'E'}`, :math:`\mathrm{ipiv}` contains the pivot indices from the factorization :math:`A = PLU` of the equilibrated matrix :math:`A`. If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{ipiv}` is unchanged from entry. **equed** : None or str, length 1 If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` is unchanged from entry. Otherwise, if no constraints are violated, :math:`\mathrm{equed}` specifies the form of equilibration that was performed as specified above. **r** : None or float, ndarray, shape :math:`\left(\mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{r}` is unchanged from entry. Otherwise, if no constraints are violated and :math:`\mathrm{equed} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{r}` contains the row scale factors for :math:`A`, :math:`D_R`, such that :math:`A` is multiplied on the left by :math:`D_R`; each element of :math:`\mathrm{r}` is positive. **c** : None or float, ndarray, shape :math:`\left(\mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{c}` is unchanged from entry. Otherwise, if no constraints are violated and :math:`\mathrm{equed} = \texttt{'C'}` or :math:`\texttt{'B'}`, :math:`\mathrm{c}` contains the row scale factors for :math:`A`, :math:`D_C`; each element of :math:`\mathrm{c}` is positive. **b** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` If :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{b}` is not modified. If :math:`\mathrm{trans} = \texttt{'N'}` and :math:`\mathrm{equed} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{b}` is overwritten by :math:`D_RB`. If :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}` and :math:`\mathrm{equed} = \texttt{'C'}` or :math:`\texttt{'B'}`, :math:`\mathrm{b}` is overwritten by :math:`D_CB`. **x** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, the :math:`n\times r` solution matrix :math:`X` to the original system of equations. Note that the arrays :math:`A` and :math:`B` are modified on exit if :math:`\mathrm{equed} \neq \texttt{'N'}`, and the solution to the equilibrated system is :math:`D_C^{-1}X` if :math:`\mathrm{trans} = \texttt{'N'}` and :math:`\mathrm{equed} = \texttt{'C'}` or :math:`\texttt{'B'}`, or :math:`D_R^{-1}X` if :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}` and :math:`\mathrm{equed} = \texttt{'R'}` or :math:`\texttt{'B'}`. **rcond** : float If no constraints are violated, an estimate of the reciprocal condition number of the matrix :math:`A` (after equilibration if that is performed), computed as :math:`\mathrm{rcond} = 1.0/\left(\left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\right)`. **ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the forward error bound for each computed solution vector, such that :math:`\left\lVert \hat{x}_j-x_j\right\rVert_\infty/\left\lVert x_j\right\rVert_\infty\leq \mathrm{ferr}[j-1]` where :math:`\hat{x}_j` is the :math:`j`\ th column of the computed solution returned in the array :math:`\mathrm{x}` and :math:`x_j` is the corresponding column of the exact solution :math:`X`. The estimate is as reliable as the estimate for :math:`\mathrm{rcond}`, and is almost always a slight overestimate of the true error. **berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the component-wise relative backward error of each computed solution vector :math:`\hat{x}_j` (i.e., the smallest relative change in any element of :math:`A` or :math:`B` that makes :math:`\hat{x}_j` an exact solution). **recip_growth_factor** : float If no exception or warning is raised, the reciprocal pivot growth factor :math:`\left\lVert A\right\rVert /\left\lVert U\right\rVert`, where :math:`\left\lVert.\right\rVert` denotes the maximum absolute element norm. If :math:`\mathrm{recip\_growth\_factor}≪1`, the stability of the :math:`LU` factorization of (equilibrated) :math:`A` could be poor. This also means that the solution :math:`\mathrm{x}`, condition estimate :math:`\mathrm{rcond}`, and forward error bound :math:`\mathrm{ferr}` could be unreliable. If the factorization fails with :math:`\mathrm{errno}` in 1 ... :math:`\mathrm{n}`, then :math:`\mathrm{recip\_growth\_factor}` contains the reciprocal pivot growth factor for the leading :math:`\textit{errno}` columns of :math:`A`. .. _f07ab-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{fact}`. Constraint: :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\texttt{'N'}` or :math:`\texttt{'E'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{trans}`. Constraint: :math:`\mathrm{trans} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\mathrm{nrhs}`. Constraint: :math:`\mathrm{nrhs}\geq 0`. (`errno` :math:`-10`) On entry, error in parameter :math:`\mathrm{equed}`. Constraint: :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\texttt{'R'}`, :math:`\texttt{'C'}` or :math:`\texttt{'B'}`. (`errno` :math:`-11`) On entry, error in parameter :math:`\mathrm{r}`. (`errno` :math:`-12`) On entry, error in parameter :math:`\mathrm{c}`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq \mathrm{n}\right)`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`U` is exactly singular, so the solution and error bounds could not be computed. :math:`\mathrm{rcond} = 0.0` is returned. (`errno` :math:`\mathrm{n}+1`) :math:`U` is nonsingular, but :math:`\mathrm{rcond}` is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of :math:`\mathrm{rcond}` would suggest. .. _f07ab-py2-py-notes: **Notes** ``dgesvx`` performs the following steps: (1) **Equilibration** The linear system to be solved may be badly scaled. However, the system can be equilibrated as a first stage by setting :math:`\mathrm{fact} = \texttt{'E'}`. In this case, real scaling factors are computed and these factors then determine whether the system is to be equilibrated. Equilibrated forms of the systems :math:`AX = B` and :math:`A^\mathrm{T}X = B` are .. math:: \left(D_RAD_C\right)\left(D_C^{-1}X\right) = D_RB and .. math:: \left(D_RAD_C\right)^\mathrm{T}\left(D_R^{-1}X\right) = D_CB\text{,} respectively, where :math:`D_R` and :math:`D_C` are diagonal matrices, with positive diagonal elements, formed from the computed scaling factors. When equilibration is used, :math:`A` will be overwritten by :math:`D_RAD_C` and :math:`B` will be overwritten by :math:`D_RB` (or :math:`D_CB` when the solution of :math:`A^\mathrm{T}X = B` is sought). (#) **Factorization** The matrix :math:`A`, or its scaled form, is copied and factored using the :math:`LU` decomposition .. math:: A = PLU\text{,} where :math:`P` is a permutation matrix, :math:`L` is a unit lower triangular matrix, and :math:`U` is upper triangular. This stage can be by-passed when a factored matrix (with scaled matrices and scaling factors) are supplied; for example, as provided by a previous call to ``dgesvx`` with the same matrix :math:`A`. (#) **Condition Number Estimation** The :math:`LU` factorization of :math:`A` determines whether a solution to the linear system exists. If some diagonal element of :math:`U` is zero, then :math:`U` is exactly singular, no solution exists and the function returns with a failure. Otherwise the factorized form of :math:`A` is used to estimate the condition number of the matrix :math:`A`. If the reciprocal of the condition number is less than machine precision then a warning code is returned on final exit. (#) **Solution** The (equilibrated) system is solved for :math:`X` (:math:`D_C^{-1}X` or :math:`D_R^{-1}X`) using the factored form of :math:`A` (:math:`D_RAD_C`). (#) **Iterative Refinement** Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for the computed solution. (#) **Construct Solution Matrix** :math:`X` If equilibration was used, the matrix :math:`X` is premultiplied by :math:`D_C` (if :math:`\mathrm{trans} = \texttt{'N'}`) or :math:`D_R` (if :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}`) so that it solves the original system before equilibration. .. _f07ab-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def dsgesv(a, b): r""" ``dsgesv`` computes the solution to a real system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices. .. _f07ac-py2-py-doc: For full information please refer to the NAG Library document for f07ac https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07acf.html .. _f07ac-py2-py-parameters: **Parameters** **a** : float, array-like, shape :math:`\left(n, n\right)` The :math:`n\times n` coefficient matrix :math:`A`. **b** : float, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **a** : float, ndarray, shape :math:`\left(n, n\right)` If iterative refinement has been successfully used (i.e., if no exception or warning is raised and :math:`\mathrm{itera}\geq 0`), then :math:`A` is unchanged. If double precision factorization has been used (when no exception or warning is raised and :math:`\mathrm{itera} < 0`), :math:`A` contains the factors :math:`L` and :math:`U` from the factorization :math:`A = PLU`; the unit diagonal elements of :math:`L` are not stored. **ipiv** : int, ndarray, shape :math:`\left(n\right)` If no constraints are violated, the pivot indices that define the permutation matrix :math:`P`; at the :math:`i`\ th step row :math:`i` of the matrix was interchanged with row :math:`\mathrm{ipiv}[i-1]`. :math:`\mathrm{ipiv}[i-1] = i` indicates a row interchange was not required. :math:`\mathrm{ipiv}` corresponds either to the single precision factorization (if no exception or warning is raised and :math:`\mathrm{itera}\geq 0`) or to the double precision factorization (if no exception or warning is raised and :math:`\mathrm{itera} < 0`). **x** : float, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`. **itera** : int If :math:`\mathrm{itera} > 0`, iterative refinement has been successfully used and :math:`\mathrm{itera}` is the number of iterations carried out. If :math:`\mathrm{itera} < 0`, iterative refinement has failed for one of the reasons given below and double precision factorization has been carried out instead. :math:`\mathrm{itera} = -1` Taking into account machine parameters, and the values of :math:`\textit{n}` and :math:`\textit{nrhs}`, it is not worth working in single precision. :math:`\mathrm{itera} = -2` Overflow of an entry occurred when moving from double to single precision. :math:`\mathrm{itera} = -3` An intermediate single precision factorization failed. :math:`\mathrm{itera} = -31` The maximum permitted number of iterations was exceeded. .. _f07ac-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`U` is exactly singular, so the solution could not be computed. .. _f07ac-py2-py-notes: **Notes** ``dsgesv`` first attempts to factorize the matrix in single precision and use this factorization within an iterative refinement procedure to produce a solution with full double precision accuracy. If the approach fails the method switches to a double precision factorization and solve. The iterative refinement process is stopped if .. math:: \mathrm{itera} > \textit{itermax}\text{,} where :math:`\mathrm{itera}` is the number of iterations carried out thus far and :math:`\textit{itermax}` is the maximum number of iterations allowed, which is fixed at :math:`30` iterations. The process is also stopped if for all right-hand sides we have .. math:: \left\lVert \textit{resid}\right\rVert < \sqrt{n}\left\lVert x\right\rVert \left\lVert A\right\rVert \epsilon \text{,} where :math:`\left\lVert \textit{resid}\right\rVert` is the :math:`\infty`-norm of the residual, :math:`\left\lVert x\right\rVert` is the :math:`\infty`-norm of the solution, :math:`\left\lVert A\right\rVert` is the :math:`\infty`-operator-norm of the matrix :math:`A` and :math:`\epsilon` is the machine precision returned by :meth:`machine.precision <naginterfaces.library.machine.precision>`. The iterative refinement strategy used by ``dsgesv`` can be more efficient than the corresponding direct full precision algorithm. Since this strategy must perform iterative refinement on each right-hand side, any efficiency gains will reduce as the number of right-hand sides increases. Conversely, as the matrix size increases the cost of these iterative refinements become less significant relative to the cost of factorization. Thus, any efficiency gains will be greatest for a very small number of right-hand sides and for large matrix sizes. The cut-off values for the number of right-hand sides and matrix size, for which the iterative refinement strategy performs better, depends on the relative performance of the reduced and full precision factorization and back-substitution. For now, ``dsgesv`` always attempts the iterative refinement strategy first; you are advised to compare the performance of ``dsgesv`` with that of its full precision counterpart :meth:`dgesv` to determine whether this strategy is worthwhile for your particular problem dimensions. .. _f07ac-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Buttari, A, Dongarra, J, Langou, J, Langou, J, Luszczek, P and Kurzak, J, 2007, `Mixed precision iterative refinement techniques for the solution of dense linear systems`, International Journal of High Performance Computing Applications Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def dgetrf(a): r""" ``dgetrf`` computes the :math:`LU` factorization of a real :math:`m\times n` matrix. .. _f07ad-py2-py-doc: For full information please refer to the NAG Library document for f07ad https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07adf.html .. _f07ad-py2-py-parameters: **Parameters** **a** : float, array-like, shape :math:`\left(m, n\right)` The :math:`m\times n` matrix :math:`A`. **Returns** **a** : float, ndarray, shape :math:`\left(m, n\right)` The factors :math:`L` and :math:`U` from the factorization :math:`A = PLU`; the unit diagonal elements of :math:`L` are not stored. **ipiv** : int, ndarray, shape :math:`\left(\min\left(m,n\right)\right)` The pivot indices that define the permutation matrix. At the :math:`\textit{i}`\ th step, if :math:`\mathrm{ipiv}[\textit{i}-1] > \textit{i}` then row :math:`\textit{i}` of the matrix :math:`A` was interchanged with row :math:`\mathrm{ipiv}[\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,\mathrm{min}\left(m, n\right)`. :math:`\mathrm{ipiv}[i-1]\leq i` indicates that, at the :math:`i`\ th step, a row interchange was not required. .. _f07ad-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\textit{m}`. Constraint: :math:`m\geq 0`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`U` is exactly singular, and division by zero will occur if it is used to solve a system of equations. .. _f07ad-py2-py-notes: **Notes** ``dgetrf`` forms the :math:`LU` factorization of a real :math:`m\times n` matrix :math:`A` as :math:`A = PLU`, where :math:`P` is a permutation matrix, :math:`L` is lower triangular with unit diagonal elements (lower trapezoidal if :math:`m > n`) and :math:`U` is upper triangular (upper trapezoidal if :math:`m < n`). Usually :math:`A` is square :math:`\left(m = n\right)`, and both :math:`L` and :math:`U` are triangular. The function uses partial pivoting, with row interchanges. .. _f07ad-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def dgetrs(trans, a, ipiv, b): r""" ``dgetrs`` solves a real system of linear equations with multiple right-hand sides, .. math:: AX = B\quad \text{ or }\quad A^\mathrm{T}X = B\text{,} where :math:`A` has been factorized by :meth:`dgetrf`. .. _f07ae-py2-py-doc: For full information please refer to the NAG Library document for f07ae https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07aef.html .. _f07ae-py2-py-parameters: **Parameters** **trans** : str, length 1 Indicates the form of the equations. :math:`\mathrm{trans} = \texttt{'N'}` :math:`AX = B` is solved for :math:`X`. :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}` :math:`A^\mathrm{T}X = B` is solved for :math:`X`. **a** : float, array-like, shape :math:`\left(n, n\right)` The :math:`LU` factorization of :math:`A`, as returned by :meth:`dgetrf`. **ipiv** : int, array-like, shape :math:`\left(n\right)` The pivot indices, as returned by :meth:`dgetrf`. **b** : float, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **b** : float, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`. .. _f07ae-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{trans}`. Constraint: :math:`\mathrm{trans} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. .. _f07ae-py2-py-notes: **Notes** ``dgetrs`` is used to solve a real system of linear equations :math:`AX = B` or :math:`A^\mathrm{T}X = B`, the function must be preceded by a call to :meth:`dgetrf` which computes the :math:`LU` factorization of :math:`A` as :math:`A = PLU`. The solution is computed by forward and backward substitution. If :math:`\mathrm{trans} = \texttt{'N'}`, the solution is computed by solving :math:`PLY = B` and then :math:`UX = Y`. If :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}`, the solution is computed by solving :math:`U^\mathrm{T}Y = B` and then :math:`L^\mathrm{T}P^\mathrm{T}X = Y`. .. _f07ae-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def dgeequ(a): r""" ``dgeequ`` computes diagonal scaling matrices :math:`D_R` and :math:`D_C` intended to equilibrate a real :math:`m\times n` matrix :math:`A` and reduce its condition number. .. _f07af-py2-py-doc: For full information please refer to the NAG Library document for f07af https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07aff.html .. _f07af-py2-py-parameters: **Parameters** **a** : float, array-like, shape :math:`\left(m, n\right)` The matrix :math:`A` whose scaling factors are to be computed. **Returns** **r** : float, ndarray, shape :math:`\left(m\right)` If no exception or warning is raised or :math:`\mathrm{errno}` > :math:`\mathrm{m}`, :math:`\mathrm{r}` contains the row scale factors, the diagonal elements of :math:`D_R`. The elements of :math:`\mathrm{r}` will be positive. **c** : float, ndarray, shape :math:`\left(n\right)` If no exception or warning is raised, :math:`\mathrm{c}` contains the column scale factors, the diagonal elements of :math:`D_C`. The elements of :math:`\mathrm{c}` will be positive. **rowcnd** : float If no exception or warning is raised or :math:`\mathrm{errno}` > :math:`\mathrm{m}`, :math:`\mathrm{rowcnd}` contains the ratio of the smallest value of :math:`\mathrm{r}[i-1]` to the largest value of :math:`\mathrm{r}[i-1]`. If :math:`\mathrm{rowcnd}\geq 0.1` and :math:`\mathrm{amax}` is neither too large nor too small, it is not worth scaling by :math:`D_R`. **colcnd** : float If no exception or warning is raised, :math:`\mathrm{colcnd}` contains the ratio of the smallest value of :math:`\mathrm{c}[i-1]` to the largest value of :math:`\mathrm{c}[i-1]`. If :math:`\mathrm{colcnd}\geq 0.1`, it is not worth scaling by :math:`D_C`. **amax** : float :math:`\mathrm{max}\left\lvert a_{{ij}}\right\rvert`. If :math:`\mathrm{amax}` is very close to overflow or underflow, the matrix :math:`A` should be scaled. .. _f07af-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\textit{m}`. Constraint: :math:`m\geq 0`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq m\right)`) Row :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is exactly zero. (`errno` :math:`i > m`) Column :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is exactly zero. .. _f07af-py2-py-notes: **Notes** ``dgeequ`` computes the diagonal scaling matrices. The diagonal scaling matrices are chosen to try to make the elements of largest absolute value in each row and column of the matrix :math:`B` given by .. math:: B = D_RAD_C have absolute value :math:`1`. The diagonal elements of :math:`D_R` and :math:`D_C` are restricted to lie in the safe range :math:`\left(\delta, {1/\delta }\right)`, where :math:`\delta` is the value returned by function :meth:`machine.real_safe <naginterfaces.library.machine.real_safe>`. Use of these scaling factors is not guaranteed to reduce the condition number of :math:`A` but works well in practice. """ raise NotImplementedError
[docs]def dgecon(norm, n, a, anorm): r""" ``dgecon`` estimates the condition number of a real matrix :math:`A`, where :math:`A` has been factorized by :meth:`dgetrf`. .. _f07ag-py2-py-doc: For full information please refer to the NAG Library document for f07ag https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07agf.html .. _f07ag-py2-py-parameters: **Parameters** **norm** : str, length 1 Indicates whether :math:`\kappa_1\left(A\right)` or :math:`\kappa_{\infty }\left(A\right)` is estimated. :math:`\mathrm{norm} = \texttt{'1'}` or :math:`\texttt{'O'}` :math:`\kappa_1\left(A\right)` is estimated. :math:`\mathrm{norm} = \texttt{'I'}` :math:`\kappa_{\infty }\left(A\right)` is estimated. **n** : int :math:`n`, the order of the matrix :math:`A`. **a** : float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` The :math:`LU` factorization of :math:`A`, as returned by :meth:`dgetrf`. **anorm** : float If :math:`\mathrm{norm} = \texttt{'1'}` or :math:`\texttt{'O'}`, the :math:`1`-norm of the **original** matrix :math:`A`. If :math:`\mathrm{norm} = \texttt{'I'}`, the :math:`\infty`-norm of the **original** matrix :math:`A`. :math:`\mathrm{anorm}` may be computed by calling :meth:`blas.dlange <naginterfaces.library.blas.dlange>` with the same value for the argument :math:`\mathrm{norm}`. :math:`\mathrm{anorm}` must be computed either **before** calling :meth:`dgetrf` or else from a **copy** of the original matrix :math:`A`. **Returns** **rcond** : float An estimate of the reciprocal of the condition number of :math:`A`. :math:`\mathrm{rcond}` is set to zero if exact singularity is detected or the estimate underflows. If :math:`\mathrm{rcond}` is less than machine precision, :math:`A` is singular to working precision. .. _f07ag-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{norm}`. Constraint: :math:`\mathrm{norm} = \texttt{'1'}`, :math:`\texttt{'O'}` or :math:`\texttt{'I'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-5`) On entry, error in parameter :math:`\mathrm{anorm}`. Constraint: :math:`\mathrm{anorm}\geq 0.0`. .. _f07ag-py2-py-notes: **Notes** ``dgecon`` estimates the condition number of a real matrix :math:`A`, in either the :math:`1`-norm or the :math:`\infty`-norm: .. math:: \kappa_1\left(A\right) = \left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\quad \text{ or }\quad \kappa_{\infty }\left(A\right) = \left\lVert A\right\rVert_\infty\left\lVert A^{-1}\right\rVert_\infty\text{.} Note that :math:`\kappa_{\infty }\left(A\right) = \kappa_1\left(A^\mathrm{T}\right)`. Because the condition number is infinite if :math:`A` is singular, the function actually returns an estimate of the **reciprocal** of the condition number. The function should be preceded by a call to :meth:`blas.dlange <naginterfaces.library.blas.dlange>` to compute :math:`\left\lVert A\right\rVert_1` or :math:`\left\lVert A\right\rVert_\infty`, and a call to :meth:`dgetrf` to compute the :math:`LU` factorization of :math:`A`. The function then uses Higham's implementation of Hager's method (see Higham (1988)) to estimate :math:`\left\lVert A^{-1}\right\rVert_1` or :math:`\left\lVert A^{-1}\right\rVert_\infty`. .. _f07ag-py2-py-references: **References** Higham, N J, 1988, `FORTRAN codes for estimating the one-norm of a real or complex matrix, with applications to condition estimation`, ACM Trans. Math. Software (14), 381--396 """ raise NotImplementedError
[docs]def dgerfs(trans, n, a, af, ipiv, b, x): r""" ``dgerfs`` returns error bounds for the solution of a real system of linear equations with multiple right-hand sides, :math:`AX = B` or :math:`A^\mathrm{T}X = B`. It improves the solution by iterative refinement, in order to reduce the backward error as much as possible. .. _f07ah-py2-py-doc: For full information please refer to the NAG Library document for f07ah https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07ahf.html .. _f07ah-py2-py-parameters: **Parameters** **trans** : str, length 1 Indicates the form of the linear equations for which :math:`X` is the computed solution. :math:`\mathrm{trans} = \texttt{'N'}` The linear equations are of the form :math:`AX = B`. :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}` The linear equations are of the form :math:`A^\mathrm{T}X = B`. **n** : int :math:`n`, the order of the matrix :math:`A`. **a** : float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` The :math:`n\times n` original matrix :math:`A` as supplied to :meth:`dgetrf`. **af** : float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` The :math:`LU` factorization of :math:`A`, as returned by :meth:`dgetrf`. **ipiv** : int, array-like, shape :math:`\left(\mathrm{n}\right)` The pivot indices, as returned by :meth:`dgetrf`. **b** : float, array-like, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **x** : float, array-like, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`, as returned by :meth:`dgetrs`. **Returns** **x** : float, ndarray, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The improved solution matrix :math:`X`. **ferr** : float, ndarray, shape :math:`\left(\textit{nrhs}\right)` :math:`\mathrm{ferr}[\textit{j}-1]` contains an estimated error bound for the :math:`\textit{j}`\ th solution vector, that is, the :math:`\textit{j}`\ th column of :math:`X`, for :math:`\textit{j} = 1,2,\ldots,r`. **berr** : float, ndarray, shape :math:`\left(\textit{nrhs}\right)` :math:`\mathrm{berr}[\textit{j}-1]` contains the component-wise backward error bound :math:`\beta` for the :math:`\textit{j}`\ th solution vector, that is, the :math:`\textit{j}`\ th column of :math:`X`, for :math:`\textit{j} = 1,2,\ldots,r`. .. _f07ah-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{trans}`. Constraint: :math:`\mathrm{trans} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. .. _f07ah-py2-py-notes: **Notes** ``dgerfs`` returns the backward errors and estimated bounds on the forward errors for the solution of a real system of linear equations with multiple right-hand sides :math:`AX = B` or :math:`A^\mathrm{T}X = B`. The function handles each right-hand side vector (stored as a column of the matrix :math:`B`) independently, so we describe the function of ``dgerfs`` in terms of a single right-hand side :math:`b` and solution :math:`x`. Given a computed solution :math:`x`, the function computes the `component-wise backward error` :math:`\beta`. This is the size of the smallest relative perturbation in each element of :math:`A` and :math:`b` such that :math:`x` is the exact solution of a perturbed system .. math:: \begin{array}{c}\left(A+\delta A\right)x = b+\delta b\\\left\lvert \delta a_{{ij}}\right\rvert \leq \beta \left\lvert a_{{ij}}\right\rvert \quad \text{ and }\quad \left\lvert \delta b_i\right\rvert \leq \beta \left\lvert b_i\right\rvert \text{.} \end{array} Then the function estimates a bound for the `component-wise forward error` in the computed solution, defined by: .. math:: \mathrm{max}_i\left\lvert x_i-\hat{x}_i\right\rvert /\mathrm{max}_i\left\lvert x_i\right\rvert where :math:`\hat{x}` is the true solution. For details of the method, see `the F07 Introduction <https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07intro.html>`__. .. _f07ah-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def dgetri(a, ipiv): r""" ``dgetri`` computes the inverse of a real matrix :math:`A`, where :math:`A` has been factorized by :meth:`dgetrf`. .. _f07aj-py2-py-doc: For full information please refer to the NAG Library document for f07aj https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07ajf.html .. _f07aj-py2-py-parameters: **Parameters** **a** : float, array-like, shape :math:`\left(n, n\right)` The :math:`LU` factorization of :math:`A`, as returned by :meth:`dgetrf`. **ipiv** : int, array-like, shape :math:`\left(n\right)` The pivot indices, as returned by :meth:`dgetrf`. **Returns** **a** : float, ndarray, shape :math:`\left(n, n\right)` The factorization is overwritten by the :math:`n\times n` matrix :math:`A^{-1}`. .. _f07aj-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is zero. :math:`U` is singular, and the inverse of :math:`A` cannot be computed. .. _f07aj-py2-py-notes: **Notes** ``dgetri`` is used to compute the inverse of a real matrix :math:`A`, the function must be preceded by a call to :meth:`dgetrf`, which computes the :math:`LU` factorization of :math:`A` as :math:`A = PLU`. The inverse of :math:`A` is computed by forming :math:`U^{-1}` and then solving the equation :math:`XPL = U^{-1}` for :math:`X`. .. _f07aj-py2-py-references: **References** Du Croz, J J and Higham, N J, 1992, `Stability of methods for matrix inversion`, IMA J. Numer. Anal. (12), 1--19 """ raise NotImplementedError
[docs]def zgesv(a, b): r""" ``zgesv`` computes the solution to a complex system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices. .. _f07an-py2-py-doc: For full information please refer to the NAG Library document for f07an https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07anf.html .. _f07an-py2-py-parameters: **Parameters** **a** : complex, array-like, shape :math:`\left(n, n\right)` The :math:`n\times n` coefficient matrix :math:`A`. **b** : complex, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **a** : complex, ndarray, shape :math:`\left(n, n\right)` The factors :math:`L` and :math:`U` from the factorization :math:`A = PLU`; the unit diagonal elements of :math:`L` are not stored. **ipiv** : int, ndarray, shape :math:`\left(n\right)` If no constraints are violated, the pivot indices that define the permutation matrix :math:`P`; at the :math:`i`\ th step row :math:`i` of the matrix was interchanged with row :math:`\mathrm{ipiv}[i-1]`. :math:`\mathrm{ipiv}[i-1] = i` indicates a row interchange was not required. **b** : complex, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`. .. _f07an-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`U` is exactly singular, so the solution could not be computed. .. _f07an-py2-py-notes: **Notes** ``zgesv`` uses the :math:`LU` decomposition with partial pivoting and row interchanges to factor :math:`A` as .. math:: A = PLU\text{,} where :math:`P` is a permutation matrix, :math:`L` is unit lower triangular, and :math:`U` is upper triangular. The factored form of :math:`A` is then used to solve the system of equations :math:`AX = B`. .. _f07an-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def zgesvx(fact, trans, nrhs, a, af, ipiv, equed, r, c, b): r""" ``zgesvx`` uses the :math:`LU` factorization to compute the solution to a complex system of linear equations .. math:: AX = B\quad \text{ or }\quad A^\mathrm{T}X = B\quad \text{ or }\quad A^\mathrm{H}X = B\text{,} where :math:`A` is an :math:`n\times n` matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices. Error bounds on the solution and a condition estimate are also provided. .. _f07ap-py2-py-doc: For full information please refer to the NAG Library document for f07ap https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07apf.html .. _f07ap-py2-py-parameters: **Parameters** **fact** : str, length 1 Specifies whether or not the factorized form of the matrix :math:`A` is supplied on entry, and if not, whether the matrix :math:`A` should be equilibrated before it is factorized. :math:`\mathrm{fact} = \texttt{'F'}` :math:`\mathrm{af}` and :math:`\mathrm{ipiv}` contain the factorized form of :math:`A`. If :math:`\mathrm{equed} \neq \texttt{'N'}`, the matrix :math:`A` has been equilibrated with scaling factors given by :math:`\mathrm{r}` and :math:`\mathrm{c}`. :math:`\mathrm{a}`, :math:`\mathrm{af}` and :math:`\mathrm{ipiv}` are not modified. :math:`\mathrm{fact} = \texttt{'N'}` The matrix :math:`A` will be copied to :math:`\mathrm{af}` and factorized. :math:`\mathrm{fact} = \texttt{'E'}` The matrix :math:`A` will be equilibrated if necessary, then copied to :math:`\mathrm{af}` and factorized. **trans** : str, length 1 Specifies the form of the system of equations. :math:`\mathrm{trans} = \texttt{'N'}` :math:`AX = B` (No transpose). :math:`\mathrm{trans} = \texttt{'T'}` :math:`A^\mathrm{T}X = B` (Transpose). :math:`\mathrm{trans} = \texttt{'C'}` :math:`A^\mathrm{H}X = B` (Conjugate transpose). **nrhs** : int :math:`r`, the number of right-hand sides, i.e., the number of columns of the matrix :math:`B`. **a** : complex, array-like, shape :math:`\left(n, n\right)` The :math:`n\times n` matrix :math:`A`. If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} \neq \texttt{'N'}`, :math:`\mathrm{a}` must have been equilibrated by the scaling factors in :math:`\mathrm{r}` and/or :math:`\mathrm{c}`. **af** : complex, array-like, shape :math:`\left(n, n\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{af}` contains the factors :math:`L` and :math:`U` from the factorization :math:`A = PLU` as computed by :meth:`zgetrf`. If :math:`\mathrm{equed} \neq \texttt{'N'}`, :math:`\mathrm{af}` is the factorized form of the equilibrated matrix :math:`A`. If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{af}` need not be set. **ipiv** : int, array-like, shape :math:`\left(n\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{ipiv}` contains the pivot indices from the factorization :math:`A = PLU` as computed by :meth:`zgetrf`; at the :math:`i`\ th step row :math:`i` of the matrix was interchanged with row :math:`\mathrm{ipiv}[i-1]`. :math:`\mathrm{ipiv}[i-1] = i` indicates a row interchange was not required. If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{ipiv}` need not be set. **equed** : str, length 1 If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{equed}` need not be set. If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` must specify the form of the equilibration that was performed as follows: if :math:`\mathrm{equed} = \texttt{'N'}`, no equilibration; if :math:`\mathrm{equed} = \texttt{'R'}`, row equilibration, i.e., :math:`A` has been premultiplied by :math:`D_R`; if :math:`\mathrm{equed} = \texttt{'C'}`, column equilibration, i.e., :math:`A` has been postmultiplied by :math:`D_C`; if :math:`\mathrm{equed} = \texttt{'B'}`, both row and column equilibration, i.e., :math:`A` has been replaced by :math:`D_RAD_C`. **r** : float, array-like, shape :math:`\left(n\right)` If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{r}` need not be set. If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{r}` must contain the row scale factors for :math:`A`, :math:`D_R`; each element of :math:`\mathrm{r}` must be positive. **c** : float, array-like, shape :math:`\left(n\right)` If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{c}` need not be set. If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'C'}` or :math:`\texttt{'B'}`, :math:`\mathrm{c}` must contain the column scale factors for :math:`A`, :math:`D_C`; each element of :math:`\mathrm{c}` must be positive. **b** : complex, array-like, shape :math:`\left(n, \mathrm{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **a** : complex, ndarray, shape :math:`\left(n, n\right)` If :math:`\mathrm{fact} = \texttt{'F'}` or :math:`\texttt{'N'}`, or if :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{a}` is not modified. If :math:`\mathrm{fact} = \texttt{'E'}` or :math:`\mathrm{equed} \neq \texttt{'N'}`, :math:`A` is scaled as follows: if :math:`\mathrm{equed} = \texttt{'R'}`, :math:`A = D_RA`; if :math:`\mathrm{equed} = \texttt{'C'}`, :math:`A = AD_C`; if :math:`\mathrm{equed} = \texttt{'B'}`, :math:`A = D_RAD_C`. **af** : complex, ndarray, shape :math:`\left(n, n\right)` If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{af}` returns the factors :math:`L` and :math:`U` from the factorization :math:`A = PLU` of the original matrix :math:`A`. If :math:`\mathrm{fact} = \texttt{'E'}`, :math:`\mathrm{af}` returns the factors :math:`L` and :math:`U` from the factorization :math:`A = PLU` of the equilibrated matrix :math:`A` (see the description of :math:`\mathrm{a}` for the form of the equilibrated matrix). If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{af}` is unchanged from entry. **ipiv** : int, ndarray, shape :math:`\left(n\right)` If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{ipiv}` contains the pivot indices from the factorization :math:`A = PLU` of the original matrix :math:`A`. If :math:`\mathrm{fact} = \texttt{'E'}`, :math:`\mathrm{ipiv}` contains the pivot indices from the factorization :math:`A = PLU` of the equilibrated matrix :math:`A`. If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{ipiv}` is unchanged from entry. **equed** : str, length 1 If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` is unchanged from entry. Otherwise, if no constraints are violated, :math:`\mathrm{equed}` specifies the form of equilibration that was performed as specified above. **r** : float, ndarray, shape :math:`\left(n\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{r}` is unchanged from entry. Otherwise, if no constraints are violated and :math:`\mathrm{equed} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{r}` contains the row scale factors for :math:`A`, :math:`D_R`, such that :math:`A` is multiplied on the left by :math:`D_R`; each element of :math:`\mathrm{r}` is positive. **c** : float, ndarray, shape :math:`\left(n\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{c}` is unchanged from entry. Otherwise, if no constraints are violated and :math:`\mathrm{equed} = \texttt{'C'}` or :math:`\texttt{'B'}`, :math:`\mathrm{c}` contains the row scale factors for :math:`A`, :math:`D_C`; each element of :math:`\mathrm{c}` is positive. **b** : complex, ndarray, shape :math:`\left(n, \mathrm{nrhs}\right)` If :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{b}` is not modified. If :math:`\mathrm{trans} = \texttt{'N'}` and :math:`\mathrm{equed} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{b}` is overwritten by :math:`D_RB`. If :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}` and :math:`\mathrm{equed} = \texttt{'C'}` or :math:`\texttt{'B'}`, :math:`\mathrm{b}` is overwritten by :math:`D_CB`. **x** : complex, ndarray, shape :math:`\left(n, \mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, the :math:`n\times r` solution matrix :math:`X` to the original system of equations. Note that the arrays :math:`A` and :math:`B` are modified on exit if :math:`\mathrm{equed} \neq \texttt{'N'}`, and the solution to the equilibrated system is :math:`D_C^{-1}X` if :math:`\mathrm{trans} = \texttt{'N'}` and :math:`\mathrm{equed} = \texttt{'C'}` or :math:`\texttt{'B'}`, or :math:`D_R^{-1}X` if :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}` and :math:`\mathrm{equed} = \texttt{'R'}` or :math:`\texttt{'B'}`. **rcond** : float If no constraints are violated, an estimate of the reciprocal condition number of the matrix :math:`A` (after equilibration if that is performed), computed as :math:`\mathrm{rcond} = 1.0/\left(\left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\right)`. **ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the forward error bound for each computed solution vector, such that :math:`\left\lVert \hat{x}_j-x_j\right\rVert_\infty/\left\lVert x_j\right\rVert_\infty\leq \mathrm{ferr}[j-1]` where :math:`\hat{x}_j` is the :math:`j`\ th column of the computed solution returned in the array :math:`\mathrm{x}` and :math:`x_j` is the corresponding column of the exact solution :math:`X`. The estimate is as reliable as the estimate for :math:`\mathrm{rcond}`, and is almost always a slight overestimate of the true error. **berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the component-wise relative backward error of each computed solution vector :math:`\hat{x}_j` (i.e., the smallest relative change in any element of :math:`A` or :math:`B` that makes :math:`\hat{x}_j` an exact solution). **recip_growth_factor** : float If no exception or warning is raised, the reciprocal pivot growth factor :math:`\left\lVert A\right\rVert /\left\lVert U\right\rVert`, where :math:`\left\lVert.\right\rVert` denotes the maximum absolute element norm. If :math:`\mathrm{recip\_growth\_factor}≪1`, the stability of the :math:`LU` factorization of (equilibrated) :math:`A` could be poor. This also means that the solution :math:`\mathrm{x}`, condition estimate :math:`\mathrm{rcond}`, and forward error bound :math:`\mathrm{ferr}` could be unreliable. If the factorization fails with :math:`\mathrm{errno}` in 1 ... :math:`\mathrm{n}`, then :math:`\mathrm{recip\_growth\_factor}` contains the reciprocal pivot growth factor for the leading :math:`\textit{errno}` columns of :math:`A`. .. _f07ap-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{fact}`. Constraint: :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\texttt{'N'}` or :math:`\texttt{'E'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{trans}`. Constraint: :math:`\mathrm{trans} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\mathrm{nrhs}`. Constraint: :math:`\mathrm{nrhs}\geq 0`. (`errno` :math:`-10`) On entry, error in parameter :math:`\mathrm{equed}`. Constraint: :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\texttt{'R'}`, :math:`\texttt{'C'}` or :math:`\texttt{'B'}`. (`errno` :math:`-11`) On entry, error in parameter :math:`\mathrm{r}`. (`errno` :math:`-12`) On entry, error in parameter :math:`\mathrm{c}`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq n\right)`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`U` is exactly singular, so the solution and error bounds could not be computed. :math:`\mathrm{rcond} = 0.0` is returned. (`errno` :math:`n+1`) :math:`U` is nonsingular, but :math:`\mathrm{rcond}` is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of :math:`\mathrm{rcond}` would suggest. .. _f07ap-py2-py-notes: **Notes** ``zgesvx`` performs the following steps: (1) **Equilibration** The linear system to be solved may be badly scaled. However, the system can be equilibrated as a first stage by setting :math:`\mathrm{fact} = \texttt{'E'}`. In this case, real scaling factors are computed and these factors then determine whether the system is to be equilibrated. Equilibrated forms of the systems :math:`AX = B`, :math:`A^\mathrm{T}X = B` and :math:`A^\mathrm{H}X = B` are .. math:: \left(D_RAD_C\right)\left(D_C^{-1}X\right) = D_RB\text{,} .. math:: \left(D_RAD_C\right)^\mathrm{T}\left(D_R^{-1}X\right) = D_CB\text{,} and .. math:: \left(D_RAD_C\right)^\mathrm{H}\left(D_R^{-1}X\right) = D_CB\text{,} respectively, where :math:`D_R` and :math:`D_C` are diagonal matrices, with positive diagonal elements, formed from the computed scaling factors. When equilibration is used, :math:`A` will be overwritten by :math:`D_RAD_C` and :math:`B` will be overwritten by :math:`D_RB` (or :math:`D_CB` when the solution of :math:`A^\mathrm{T}X = B` or :math:`A^\mathrm{H}X = B` is sought). (#) **Factorization** The matrix :math:`A`, or its scaled form, is copied and factored using the :math:`LU` decomposition .. math:: A = PLU\text{,} where :math:`P` is a permutation matrix, :math:`L` is a unit lower triangular matrix, and :math:`U` is upper triangular. This stage can be by-passed when a factored matrix (with scaled matrices and scaling factors) are supplied; for example, as provided by a previous call to ``zgesvx`` with the same matrix :math:`A`. (#) **Condition Number Estimation** The :math:`LU` factorization of :math:`A` determines whether a solution to the linear system exists. If some diagonal element of :math:`U` is zero, then :math:`U` is exactly singular, no solution exists and the function returns with a failure. Otherwise the factorized form of :math:`A` is used to estimate the condition number of the matrix :math:`A`. If the reciprocal of the condition number is less than machine precision then a warning code is returned on final exit. (#) **Solution** The (equilibrated) system is solved for :math:`X` (:math:`D_C^{-1}X` or :math:`D_R^{-1}X`) using the factored form of :math:`A` (:math:`D_RAD_C`). (#) **Iterative Refinement** Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for the computed solution. (#) **Construct Solution Matrix** :math:`X` If equilibration was used, the matrix :math:`X` is premultiplied by :math:`D_C` (if :math:`\mathrm{trans} = \texttt{'N'}`) or :math:`D_R` (if :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}`) so that it solves the original system before equilibration. .. _f07ap-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def zcgesv(a, b): r""" ``zcgesv`` computes the solution to a complex system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices. .. _f07aq-py2-py-doc: For full information please refer to the NAG Library document for f07aq https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07aqf.html .. _f07aq-py2-py-parameters: **Parameters** **a** : complex, array-like, shape :math:`\left(n, n\right)` The :math:`n\times n` coefficient matrix :math:`A`. **b** : complex, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **a** : complex, ndarray, shape :math:`\left(n, n\right)` If iterative refinement has been successfully used (i.e., if no exception or warning is raised and :math:`\mathrm{itera}\geq 0`), then :math:`A` is unchanged. If double precision factorization has been used (when no exception or warning is raised and :math:`\mathrm{itera} < 0`), :math:`A` contains the factors :math:`L` and :math:`U` from the factorization :math:`A = PLU`; the unit diagonal elements of :math:`L` are not stored. **ipiv** : int, ndarray, shape :math:`\left(n\right)` If no constraints are violated, the pivot indices that define the permutation matrix :math:`P`; at the :math:`i`\ th step row :math:`i` of the matrix was interchanged with row :math:`\mathrm{ipiv}[i-1]`. :math:`\mathrm{ipiv}[i-1] = i` indicates a row interchange was not required. :math:`\mathrm{ipiv}` corresponds either to the single precision factorization (if no exception or warning is raised and :math:`\mathrm{itera}\geq 0`) or to the double precision factorization (if no exception or warning is raised and :math:`\mathrm{itera} < 0`). **x** : complex, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`. **itera** : int If :math:`\mathrm{itera} > 0`, iterative refinement has been successfully used and :math:`\mathrm{itera}` is the number of iterations carried out. If :math:`\mathrm{itera} < 0`, iterative refinement has failed for one of the reasons given below and double precision factorization has been carried out instead. :math:`\mathrm{itera} = -1` Taking into account machine parameters, and the values of :math:`\textit{n}` and :math:`\textit{nrhs}`, it is not worth working in single precision. :math:`\mathrm{itera} = -2` Overflow of an entry occurred when moving from double to single precision. :math:`\mathrm{itera} = -3` An intermediate single precision factorization failed. :math:`\mathrm{itera} = -31` The maximum permitted number of iterations was exceeded. .. _f07aq-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`U` is exactly singular, so the solution could not be computed. .. _f07aq-py2-py-notes: **Notes** ``zcgesv`` first attempts to factorize the matrix in single precision and use this factorization within an iterative refinement procedure to produce a solution with double precision accuracy. If the approach fails the method switches to a double precision factorization and solve. The iterative refinement process is stopped if .. math:: \mathrm{itera} > \textit{itermax}\text{,} where :math:`\mathrm{itera}` is the number of iterations carried out thus far and :math:`\textit{itermax}` is the maximum number of iterations allowed, which is fixed at :math:`30` iterations. The process is also stopped if for all right-hand sides we have .. math:: \left\lVert \textit{resid}\right\rVert < \sqrt{n}\left\lVert x\right\rVert \left\lVert A\right\rVert \epsilon \text{,} where :math:`\left\lVert \textit{resid}\right\rVert` is the :math:`\infty`-norm of the residual, :math:`\left\lVert x\right\rVert` is the :math:`\infty`-norm of the solution, :math:`\left\lVert A\right\rVert` is the :math:`\infty`-operator-norm of the matrix :math:`A` and :math:`\epsilon` is the machine precision returned by :meth:`machine.precision <naginterfaces.library.machine.precision>`. The iterative refinement strategy used by ``zcgesv`` can be more efficient than the corresponding direct full precision algorithm. Since this strategy must perform iterative refinement on each right-hand side, any efficiency gains will reduce as the number of right-hand sides increases. Conversely, as the matrix size increases the cost of these iterative refinements become less significant relative to the cost of factorization. Thus, any efficiency gains will be greatest for a very small number of right-hand sides and for large matrix sizes. The cut-off values for the number of right-hand sides and matrix size, for which the iterative refinement strategy performs better, depends on the relative performance of the reduced and full precision factorization and back-substitution. For now, ``zcgesv`` always attempts the iterative refinement strategy first; you are advised to compare the performance of ``zcgesv`` with that of its full precision counterpart :meth:`zgesv` to determine whether this strategy is worthwhile for your particular problem dimensions. .. _f07aq-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Buttari, A, Dongarra, J, Langou, J, Langou, J, Luszczek, P and Kurzak, J, 2007, `Mixed precision iterative refinement techniques for the solution of dense linear systems`, International Journal of High Performance Computing Applications Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def zgetrf(a): r""" ``zgetrf`` computes the :math:`LU` factorization of a complex :math:`m\times n` matrix. .. _f07ar-py2-py-doc: For full information please refer to the NAG Library document for f07ar https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07arf.html .. _f07ar-py2-py-parameters: **Parameters** **a** : complex, array-like, shape :math:`\left(m, n\right)` The :math:`m\times n` matrix :math:`A`. **Returns** **a** : complex, ndarray, shape :math:`\left(m, n\right)` The factors :math:`L` and :math:`U` from the factorization :math:`A = PLU`; the unit diagonal elements of :math:`L` are not stored. **ipiv** : int, ndarray, shape :math:`\left(\min\left(m,n\right)\right)` The pivot indices that define the permutation matrix. At the :math:`\textit{i}`\ th step, if :math:`\mathrm{ipiv}[\textit{i}-1] > \textit{i}` then row :math:`\textit{i}` of the matrix :math:`A` was interchanged with row :math:`\mathrm{ipiv}[\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,\mathrm{min}\left(m, n\right)`. :math:`\mathrm{ipiv}[i-1]\leq i` indicates that, at the :math:`i`\ th step, a row interchange was not required. .. _f07ar-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\textit{m}`. Constraint: :math:`m\geq 0`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`U` is exactly singular, and division by zero will occur if it is used to solve a system of equations. .. _f07ar-py2-py-notes: **Notes** ``zgetrf`` forms the :math:`LU` factorization of a complex :math:`m\times n` matrix :math:`A` as :math:`A = PLU`, where :math:`P` is a permutation matrix, :math:`L` is lower triangular with unit diagonal elements (lower trapezoidal if :math:`m > n`) and :math:`U` is upper triangular (upper trapezoidal if :math:`m < n`). Usually :math:`A` is square :math:`\left(m = n\right)`, and both :math:`L` and :math:`U` are triangular. The function uses partial pivoting, with row interchanges. .. _f07ar-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def zgetrs(trans, a, ipiv, b): r""" ``zgetrs`` solves a complex system of linear equations with multiple right-hand sides, .. math:: AX = B\text{, }\quad A^\mathrm{T}X = B\quad \text{ or }\quad A^\mathrm{H}X = B\text{,} where :math:`A` has been factorized by :meth:`zgetrf`. .. _f07as-py2-py-doc: For full information please refer to the NAG Library document for f07as https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07asf.html .. _f07as-py2-py-parameters: **Parameters** **trans** : str, length 1 Indicates the form of the equations. :math:`\mathrm{trans} = \texttt{'N'}` :math:`AX = B` is solved for :math:`X`. :math:`\mathrm{trans} = \texttt{'T'}` :math:`A^\mathrm{T}X = B` is solved for :math:`X`. :math:`\mathrm{trans} = \texttt{'C'}` :math:`A^\mathrm{H}X = B` is solved for :math:`X`. **a** : complex, array-like, shape :math:`\left(n, n\right)` The :math:`LU` factorization of :math:`A`, as returned by :meth:`zgetrf`. **ipiv** : int, array-like, shape :math:`\left(n\right)` The pivot indices, as returned by :meth:`zgetrf`. **b** : complex, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **b** : complex, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`. .. _f07as-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{trans}`. Constraint: :math:`\mathrm{trans} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. .. _f07as-py2-py-notes: **Notes** ``zgetrs`` is used to solve a complex system of linear equations :math:`AX = B`, :math:`A^\mathrm{T}X = B` or :math:`A^\mathrm{H}X = B`, the function must be preceded by a call to :meth:`zgetrf` which computes the :math:`LU` factorization of :math:`A` as :math:`A = PLU`. The solution is computed by forward and backward substitution. If :math:`\mathrm{trans} = \texttt{'N'}`, the solution is computed by solving :math:`PLY = B` and then :math:`UX = Y`. If :math:`\mathrm{trans} = \texttt{'T'}`, the solution is computed by solving :math:`U^\mathrm{T}Y = B` and then :math:`L^\mathrm{T}P^\mathrm{T}X = Y`. If :math:`\mathrm{trans} = \texttt{'C'}`, the solution is computed by solving :math:`U^\mathrm{H}Y = B` and then :math:`L^\mathrm{H}P^\mathrm{T}X = Y`. .. _f07as-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def zgeequ(a): r""" ``zgeequ`` computes real diagonal scaling matrices :math:`D_R` and :math:`D_C` intended to equilibrate a complex :math:`m\times n` matrix :math:`A` and reduce its condition number. .. _f07at-py2-py-doc: For full information please refer to the NAG Library document for f07at https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07atf.html .. _f07at-py2-py-parameters: **Parameters** **a** : complex, array-like, shape :math:`\left(m, n\right)` The matrix :math:`A` whose scaling factors are to be computed. **Returns** **r** : float, ndarray, shape :math:`\left(m\right)` If no exception or warning is raised or :math:`\mathrm{errno}` > :math:`\mathrm{m}`, :math:`\mathrm{r}` contains the row scale factors, the diagonal elements of :math:`D_R`. The elements of :math:`\mathrm{r}` will be positive. **c** : float, ndarray, shape :math:`\left(n\right)` If no exception or warning is raised, :math:`\mathrm{c}` contains the column scale factors, the diagonal elements of :math:`D_C`. The elements of :math:`\mathrm{c}` will be positive. **rowcnd** : float If no exception or warning is raised or :math:`\mathrm{errno}` > :math:`\mathrm{m}`, :math:`\mathrm{rowcnd}` contains the ratio of the smallest value of :math:`\mathrm{r}[i-1]` to the largest value of :math:`\mathrm{r}[i-1]`. If :math:`\mathrm{rowcnd}\geq 0.1` and :math:`\mathrm{amax}` is neither too large nor too small, it is not worth scaling by :math:`D_R`. **colcnd** : float If no exception or warning is raised, :math:`\mathrm{colcnd}` contains the ratio of the smallest value of :math:`\mathrm{c}[i-1]` to the largest value of :math:`\mathrm{c}[i-1]`. If :math:`\mathrm{colcnd}\geq 0.1`, it is not worth scaling by :math:`D_C`. **amax** : float :math:`\mathrm{max}\left\lvert a_{{ij}}\right\rvert`. If :math:`\mathrm{amax}` is very close to overflow or underflow, the matrix :math:`A` should be scaled. .. _f07at-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\textit{m}`. Constraint: :math:`m\geq 0`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq m\right)`) Row :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is exactly zero. (`errno` :math:`i > m`) Column :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is exactly zero. .. _f07at-py2-py-notes: **Notes** ``zgeequ`` computes the diagonal scaling matrices. The diagonal scaling matrices are chosen to try to make the elements of largest absolute value in each row and column of the matrix :math:`B` given by .. math:: B = D_RAD_C have absolute value :math:`1`. The diagonal elements of :math:`D_R` and :math:`D_C` are restricted to lie in the safe range :math:`\left(\delta, {1/\delta }\right)`, where :math:`\delta` is the value returned by function :meth:`machine.real_safe <naginterfaces.library.machine.real_safe>`. Use of these scaling factors is not guaranteed to reduce the condition number of :math:`A` but works well in practice. """ raise NotImplementedError
[docs]def zgecon(norm, a, anorm): r""" ``zgecon`` estimates the condition number of a complex matrix :math:`A`, where :math:`A` has been factorized by :meth:`zgetrf`. .. _f07au-py2-py-doc: For full information please refer to the NAG Library document for f07au https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07auf.html .. _f07au-py2-py-parameters: **Parameters** **norm** : str, length 1 Indicates whether :math:`\kappa_1\left(A\right)` or :math:`\kappa_{\infty }\left(A\right)` is estimated. :math:`\mathrm{norm} = \texttt{'1'}` or :math:`\texttt{'O'}` :math:`\kappa_1\left(A\right)` is estimated. :math:`\mathrm{norm} = \texttt{'I'}` :math:`\kappa_{\infty }\left(A\right)` is estimated. **a** : complex, array-like, shape :math:`\left(n, n\right)` The :math:`LU` factorization of :math:`A`, as returned by :meth:`zgetrf`. **anorm** : float If :math:`\mathrm{norm} = \texttt{'1'}` or :math:`\texttt{'O'}`, the :math:`1`-norm of the **original** matrix :math:`A`. If :math:`\mathrm{norm} = \texttt{'I'}`, the :math:`\infty`-norm of the **original** matrix :math:`A`. :math:`\mathrm{anorm}` may be computed by calling :meth:`blas.zlange <naginterfaces.library.blas.zlange>` with the same value for the argument :math:`\mathrm{norm}`. :math:`\mathrm{anorm}` must be computed either **before** calling :meth:`zgetrf` or else from a **copy** of the original matrix :math:`A`. **Returns** **rcond** : float An estimate of the reciprocal of the condition number of :math:`A`. :math:`\mathrm{rcond}` is set to zero if exact singularity is detected or the estimate underflows. If :math:`\mathrm{rcond}` is less than machine precision, :math:`A` is singular to working precision. .. _f07au-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{norm}`. Constraint: :math:`\mathrm{norm} = \texttt{'1'}`, :math:`\texttt{'O'}` or :math:`\texttt{'I'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-5`) On entry, error in parameter :math:`\mathrm{anorm}`. Constraint: :math:`\mathrm{anorm}\geq 0.0`. .. _f07au-py2-py-notes: **Notes** ``zgecon`` estimates the condition number of a complex matrix :math:`A`, in either the :math:`1`-norm or the :math:`\infty`-norm: .. math:: \kappa_1\left(A\right) = \left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\quad \text{ or }\quad \kappa_{\infty }\left(A\right) = \left\lVert A\right\rVert_\infty\left\lVert A^{-1}\right\rVert_\infty\text{.} Note that :math:`\kappa_{\infty }\left(A\right) = \kappa_1\left(A^\mathrm{H}\right)`. Because the condition number is infinite if :math:`A` is singular, the function actually returns an estimate of the **reciprocal** of the condition number. The function should be preceded by a call to :meth:`blas.zlange <naginterfaces.library.blas.zlange>` to compute :math:`\left\lVert A\right\rVert_1` or :math:`\left\lVert A\right\rVert_\infty`, and a call to :meth:`zgetrf` to compute the :math:`LU` factorization of :math:`A`. The function then uses Higham's implementation of Hager's method (see Higham (1988)) to estimate :math:`\left\lVert A^{-1}\right\rVert_1` or :math:`\left\lVert A^{-1}\right\rVert_\infty`. .. _f07au-py2-py-references: **References** Higham, N J, 1988, `FORTRAN codes for estimating the one-norm of a real or complex matrix, with applications to condition estimation`, ACM Trans. Math. Software (14), 381--396 """ raise NotImplementedError
[docs]def zgerfs(trans, n, a, af, ipiv, b, x): r""" ``zgerfs`` returns error bounds for the solution of a complex system of linear equations with multiple right-hand sides, :math:`AX = B`, :math:`A^\mathrm{T}X = B` or :math:`A^\mathrm{H}X = B`. It improves the solution by iterative refinement, in order to reduce the backward error as much as possible. .. _f07av-py2-py-doc: For full information please refer to the NAG Library document for f07av https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07avf.html .. _f07av-py2-py-parameters: **Parameters** **trans** : str, length 1 Indicates the form of the linear equations for which :math:`X` is the computed solution as follows: :math:`\mathrm{trans} = \texttt{'N'}` The linear equations are of the form :math:`AX = B`. :math:`\mathrm{trans} = \texttt{'T'}` The linear equations are of the form :math:`A^\mathrm{T}X = B`. :math:`\mathrm{trans} = \texttt{'C'}` The linear equations are of the form :math:`A^\mathrm{H}X = B`. **n** : int :math:`n`, the order of the matrix :math:`A`. **a** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` The :math:`n\times n` original matrix :math:`A` as supplied to :meth:`zgetrf`. **af** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` The :math:`LU` factorization of :math:`A`, as returned by :meth:`zgetrf`. **ipiv** : int, array-like, shape :math:`\left(\mathrm{n}\right)` The pivot indices, as returned by :meth:`zgetrf`. **b** : complex, array-like, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **x** : complex, array-like, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`, as returned by :meth:`zgetrs`. **Returns** **x** : complex, ndarray, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The improved solution matrix :math:`X`. **ferr** : float, ndarray, shape :math:`\left(\textit{nrhs}\right)` :math:`\mathrm{ferr}[\textit{j}-1]` contains an estimated error bound for the :math:`\textit{j}`\ th solution vector, that is, the :math:`\textit{j}`\ th column of :math:`X`, for :math:`\textit{j} = 1,2,\ldots,r`. **berr** : float, ndarray, shape :math:`\left(\textit{nrhs}\right)` :math:`\mathrm{berr}[\textit{j}-1]` contains the component-wise backward error bound :math:`\beta` for the :math:`\textit{j}`\ th solution vector, that is, the :math:`\textit{j}`\ th column of :math:`X`, for :math:`\textit{j} = 1,2,\ldots,r`. .. _f07av-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{trans}`. Constraint: :math:`\mathrm{trans} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. .. _f07av-py2-py-notes: **Notes** ``zgerfs`` returns the backward errors and estimated bounds on the forward errors for the solution of a complex system of linear equations with multiple right-hand sides :math:`AX = B`, :math:`A^\mathrm{T}X = B` or :math:`A^\mathrm{H}X = B`. The function handles each right-hand side vector (stored as a column of the matrix :math:`B`) independently, so we describe the function of ``zgerfs`` in terms of a single right-hand side :math:`b` and solution :math:`x`. Given a computed solution :math:`x`, the function computes the `component-wise backward error` :math:`\beta`. This is the size of the smallest relative perturbation in each element of :math:`A` and :math:`b` such that :math:`x` is the exact solution of a perturbed system .. math:: \begin{array}{c}\left(A+\delta A\right)x = b+\delta b\\\left\lvert \delta a_{{ij}}\right\rvert \leq \beta \left\lvert a_{{ij}}\right\rvert \quad \text{ and }\quad \left\lvert \delta b_i\right\rvert \leq \beta \left\lvert b_i\right\rvert \text{.} \end{array} Then the function estimates a bound for the `component-wise forward error` in the computed solution, defined by: .. math:: \mathrm{max}_i\left\lvert x_i-\hat{x}_i\right\rvert /\mathrm{max}_i\left\lvert x_i\right\rvert where :math:`\hat{x}` is the true solution. For details of the method, see `the F07 Introduction <https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07intro.html>`__. .. _f07av-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def zgetri(a, ipiv): r""" ``zgetri`` computes the inverse of a complex matrix :math:`A`, where :math:`A` has been factorized by :meth:`zgetrf`. .. _f07aw-py2-py-doc: For full information please refer to the NAG Library document for f07aw https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07awf.html .. _f07aw-py2-py-parameters: **Parameters** **a** : complex, array-like, shape :math:`\left(n, n\right)` The :math:`LU` factorization of :math:`A`, as returned by :meth:`zgetrf`. **ipiv** : int, array-like, shape :math:`\left(n\right)` The pivot indices, as returned by :meth:`zgetrf`. **Returns** **a** : complex, ndarray, shape :math:`\left(n, n\right)` The factorization is overwritten by the :math:`n\times n` matrix :math:`A^{-1}`. .. _f07aw-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is zero. :math:`U` is singular, and the inverse of :math:`A` cannot be computed. .. _f07aw-py2-py-notes: **Notes** ``zgetri`` is used to compute the inverse of a complex matrix :math:`A`, the function must be preceded by a call to :meth:`zgetrf`, which computes the :math:`LU` factorization of :math:`A` as :math:`A = PLU`. The inverse of :math:`A` is computed by forming :math:`U^{-1}` and then solving the equation :math:`XPL = U^{-1}` for :math:`X`. .. _f07aw-py2-py-references: **References** Du Croz, J J and Higham, N J, 1992, `Stability of methods for matrix inversion`, IMA J. Numer. Anal. (12), 1--19 """ raise NotImplementedError
[docs]def dgbsv(kl, ku, ab, b): r""" ``dgbsv`` computes the solution to a real system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` band matrix, with :math:`k_l` subdiagonals and :math:`k_u` superdiagonals, and :math:`X` and :math:`B` are :math:`n\times r` matrices. .. _f07ba-py2-py-doc: For full information please refer to the NAG Library document for f07ba https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07baf.html .. _f07ba-py2-py-parameters: **Parameters** **kl** : int :math:`k_l`, the number of subdiagonals within the band of the matrix :math:`A`. **ku** : int :math:`k_u`, the number of superdiagonals within the band of the matrix :math:`A`. **ab** : float, array-like, shape :math:`\left(2\times \mathrm{kl}+\mathrm{ku}+1, n\right)` The :math:`n\times n` coefficient matrix :math:`A`. See `Further Comments <https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07baf.html#fcomments>`__ for further details. **b** : float, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **ab** : float, ndarray, shape :math:`\left(2\times \mathrm{kl}+\mathrm{ku}+1, n\right)` If :math:`\mathrm{errno}` >= 0, :math:`\mathrm{ab}` is overwritten by details of the factorization. **ipiv** : int, ndarray, shape :math:`\left(n\right)` If no constraints are violated, the pivot indices that define the permutation matrix :math:`P`; at the :math:`i`\ th step row :math:`i` of the matrix was interchanged with row :math:`\mathrm{ipiv}[i-1]`. :math:`\mathrm{ipiv}[i-1] = i` indicates a row interchange was not required. **b** : float, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`. .. _f07ba-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{kl}`. Constraint: :math:`\mathrm{kl}\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{ku}`. Constraint: :math:`\mathrm{ku}\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`U` is exactly singular, so the solution could not be computed. .. _f07ba-py2-py-notes: **Notes** ``dgbsv`` uses the :math:`LU` decomposition with partial pivoting and row interchanges to factor :math:`A` as :math:`A = PLU`, where :math:`P` is a permutation matrix, :math:`L` is a product of permutation and unit lower triangular matrices with :math:`k_l` subdiagonals, and :math:`U` is upper triangular with :math:`\left(k_l+k_u\right)` superdiagonals. The factored form of :math:`A` is then used to solve the system of equations :math:`AX = B`. .. _f07ba-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def dgbsvx(fact, trans, n, kl, ku, nrhs, ab, afb, ipiv, equed, r, c, b): r""" ``dgbsvx`` uses the :math:`LU` factorization to compute the solution to a real system of linear equations .. math:: AX = B\quad \text{ or }\quad A^\mathrm{T}X = B\text{,} where :math:`A` is an :math:`n\times n` band matrix with :math:`k_l` subdiagonals and :math:`k_u` superdiagonals, and :math:`X` and :math:`B` are :math:`n\times r` matrices. Error bounds on the solution and a condition estimate are also provided. .. _f07bb-py2-py-doc: For full information please refer to the NAG Library document for f07bb https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07bbf.html .. _f07bb-py2-py-parameters: **Parameters** **fact** : str, length 1 Specifies whether or not the factorized form of the matrix :math:`A` is supplied on entry, and if not, whether the matrix :math:`A` should be equilibrated before it is factorized. :math:`\mathrm{fact} = \texttt{'F'}` :math:`\mathrm{afb}` and :math:`\mathrm{ipiv}` contain the factorized form of :math:`A`. If :math:`\mathrm{equed} \neq \texttt{'N'}`, the matrix :math:`A` has been equilibrated with scaling factors given by :math:`\mathrm{r}` and :math:`\mathrm{c}`. :math:`\mathrm{ab}`, :math:`\mathrm{afb}` and :math:`\mathrm{ipiv}` are not modified. :math:`\mathrm{fact} = \texttt{'N'}` The matrix :math:`A` will be copied to :math:`\mathrm{afb}` and factorized. :math:`\mathrm{fact} = \texttt{'E'}` The matrix :math:`A` will be equilibrated if necessary, then copied to :math:`\mathrm{afb}` and factorized. **trans** : str, length 1 Specifies the form of the system of equations. :math:`\mathrm{trans} = \texttt{'N'}` :math:`AX = B` (No transpose). :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}` :math:`A^\mathrm{T}X = B` (Transpose). **n** : int :math:`n`, the number of linear equations, i.e., the order of the matrix :math:`A`. **kl** : int :math:`k_l`, the number of subdiagonals within the band of the matrix :math:`A`. **ku** : int :math:`k_u`, the number of superdiagonals within the band of the matrix :math:`A`. **nrhs** : int :math:`r`, the number of right-hand sides, i.e., the number of columns of the matrix :math:`B`. **ab** : float, array-like, shape :math:`\left(\mathrm{kl}+\mathrm{ku}+1, \mathrm{n}\right)` The :math:`n\times n` coefficient matrix :math:`A`. See `Further Comments <https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07bbf.html#fcomments>`__ for further details. If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} \neq \texttt{'N'}`, :math:`A` must have been equilibrated by the scaling factors in :math:`\mathrm{r}` and/or :math:`\mathrm{c}`. **afb** : float, array-like, shape :math:`\left(2\times \mathrm{kl}+\mathrm{ku}+1, \mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{afb}` need not be set. If :math:`\mathrm{fact} = \texttt{'F'}`, details of the :math:`LU` factorization of the :math:`n\times n` band matrix :math:`A`, as computed by :meth:`dgbtrf`. If :math:`\mathrm{equed} \neq \texttt{'N'}`, :math:`\mathrm{afb}` is the factorized form of the equilibrated matrix :math:`A`. **ipiv** : int, array-like, shape :math:`\left(\mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{ipiv}` need not be set. If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{ipiv}` contains the pivot indices from the factorization :math:`A = LU`, as computed by :meth:`dgbtrf`; row :math:`i` of the matrix was interchanged with row :math:`\mathrm{ipiv}[i-1]`. **equed** : str, length 1 If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{equed}` need not be set. If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` must specify the form of the equilibration that was performed as follows: if :math:`\mathrm{equed} = \texttt{'N'}`, no equilibration; if :math:`\mathrm{equed} = \texttt{'R'}`, row equilibration, i.e., :math:`A` has been premultiplied by :math:`D_R`; if :math:`\mathrm{equed} = \texttt{'C'}`, column equilibration, i.e., :math:`A` has been postmultiplied by :math:`D_C`; if :math:`\mathrm{equed} = \texttt{'B'}`, both row and column equilibration, i.e., :math:`A` has been replaced by :math:`D_RAD_C`. **r** : float, array-like, shape :math:`\left(\mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{r}` need not be set. If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{r}` must contain the row scale factors for :math:`A`, :math:`D_R`; each element of :math:`\mathrm{r}` must be positive. **c** : float, array-like, shape :math:`\left(\mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{c}` need not be set. If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'C'}` or :math:`\texttt{'B'}`, :math:`\mathrm{c}` must contain the column scale factors for :math:`A`, :math:`D_C`; each element of :math:`\mathrm{c}` must be positive. **b** : float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **ab** : float, ndarray, shape :math:`\left(\mathrm{kl}+\mathrm{ku}+1, \mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'F'}` or :math:`\texttt{'N'}`, or if :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{ab}` is not modified. If :math:`\mathrm{equed} \neq \texttt{'N'}` then, if no constraints are violated, :math:`A` is scaled as follows: if :math:`\mathrm{equed} = \texttt{'R'}`, :math:`A = D_rA`; if :math:`\mathrm{equed} = \texttt{'C'}`, :math:`A = AD_c`; if :math:`\mathrm{equed} = \texttt{'B'}`, :math:`A = D_rAD_c`. **afb** : float, ndarray, shape :math:`\left(2\times \mathrm{kl}+\mathrm{ku}+1, \mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{afb}` is unchanged from entry. Otherwise, if no constraints are violated, then if :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{afb}` returns details of the :math:`LU` factorization of the band matrix :math:`A`, and if :math:`\mathrm{fact} = \texttt{'E'}`, :math:`\mathrm{afb}` returns details of the :math:`LU` factorization of the equilibrated band matrix :math:`A` (see the description of :math:`\mathrm{ab}` for the form of the equilibrated matrix). **ipiv** : int, ndarray, shape :math:`\left(\mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{ipiv}` is unchanged from entry. Otherwise, if no constraints are violated, :math:`\mathrm{ipiv}` contains the pivot indices that define the permutation matrix :math:`P`; at the :math:`i`\ th step row :math:`i` of the matrix was interchanged with row :math:`\mathrm{ipiv}[i-1]`. :math:`\mathrm{ipiv}[i-1] = i` indicates a row interchange was not required. If :math:`\mathrm{fact} = \texttt{'N'}`, the pivot indices are those corresponding to the factorization :math:`A = LU` of the original matrix :math:`A`. If :math:`\mathrm{fact} = \texttt{'E'}`, the pivot indices are those corresponding to the factorization of :math:`A = LU` of the equilibrated matrix :math:`A`. **equed** : str, length 1 If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` is unchanged from entry. Otherwise, if no constraints are violated, :math:`\mathrm{equed}` specifies the form of equilibration that was performed as specified above. **r** : float, ndarray, shape :math:`\left(\mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{r}` is unchanged from entry. Otherwise, if no constraints are violated and :math:`\mathrm{equed} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{r}` contains the row scale factors for :math:`A`, :math:`D_R`, such that :math:`A` is multiplied on the left by :math:`D_R`; each element of :math:`\mathrm{r}` is positive. **c** : float, ndarray, shape :math:`\left(\mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{c}` is unchanged from entry. Otherwise, if no constraints are violated and :math:`\mathrm{equed} = \texttt{'C'}` or :math:`\texttt{'B'}`, :math:`\mathrm{c}` contains the row scale factors for :math:`A`, :math:`D_C`; each element of :math:`\mathrm{c}` is positive. **b** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` If :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{b}` is not modified. If :math:`\mathrm{trans} = \texttt{'N'}` and :math:`\mathrm{equed} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{b}` is overwritten by :math:`D_RB`. If :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}` and :math:`\mathrm{equed} = \texttt{'C'}` or :math:`\texttt{'B'}`, :math:`\mathrm{b}` is overwritten by :math:`D_CB`. **x** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, the :math:`n\times r` solution matrix :math:`X` to the original system of equations. Note that the arrays :math:`A` and :math:`B` are modified on exit if :math:`\mathrm{equed} \neq \texttt{'N'}`, and the solution to the equilibrated system is :math:`D_C^{-1}X` if :math:`\mathrm{trans} = \texttt{'N'}` and :math:`\mathrm{equed} = \texttt{'C'}` or :math:`\texttt{'B'}`, or :math:`D_R^{-1}X` if :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}` and :math:`\mathrm{equed} = \texttt{'R'}` or :math:`\texttt{'B'}`. **rcond** : float If no constraints are violated, an estimate of the reciprocal condition number of the matrix :math:`A` (after equilibration if that is performed), computed as :math:`\mathrm{rcond} = 1.0/\left(\left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\right)`. **ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the forward error bound for each computed solution vector, such that :math:`\left\lVert \hat{x}_j-x_j\right\rVert_\infty/\left\lVert x_j\right\rVert_\infty\leq \mathrm{ferr}[j-1]` where :math:`\hat{x}_j` is the :math:`j`\ th column of the computed solution returned in the array :math:`\mathrm{x}` and :math:`x_j` is the corresponding column of the exact solution :math:`X`. The estimate is as reliable as the estimate for :math:`\mathrm{rcond}`, and is almost always a slight overestimate of the true error. **berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the component-wise relative backward error of each computed solution vector :math:`\hat{x}_j` (i.e., the smallest relative change in any element of :math:`A` or :math:`B` that makes :math:`\hat{x}_j` an exact solution). **recip_growth_factor** : float If no exception or warning is raised, the reciprocal pivot growth factor :math:`\left\lVert A\right\rVert /\left\lVert U\right\rVert`, where :math:`\left\lVert.\right\rVert` denotes the maximum absolute element norm. If :math:`\mathrm{recip\_growth\_factor}≪1`, the stability of the :math:`LU` factorization of (equilibrated) :math:`A` could be poor. This also means that the solution :math:`\mathrm{x}`, condition estimate :math:`\mathrm{rcond}`, and forward error bound :math:`\mathrm{ferr}` could be unreliable. If the factorization fails with :math:`\mathrm{errno}` in 1 ... :math:`\mathrm{n}`, then :math:`\mathrm{recip\_growth\_factor}` contains the reciprocal pivot growth factor for the leading :math:`\textit{errno}` columns of :math:`A`. .. _f07bb-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{fact}`. Constraint: :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\texttt{'N'}` or :math:`\texttt{'E'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{trans}`. Constraint: :math:`\mathrm{trans} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\mathrm{kl}`. Constraint: :math:`\mathrm{kl}\geq 0`. (`errno` :math:`-5`) On entry, error in parameter :math:`\mathrm{ku}`. Constraint: :math:`\mathrm{ku}\geq 0`. (`errno` :math:`-6`) On entry, error in parameter :math:`\mathrm{nrhs}`. Constraint: :math:`\mathrm{nrhs}\geq 0`. (`errno` :math:`-12`) On entry, error in parameter :math:`\mathrm{equed}`. Constraint: :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\texttt{'R'}`, :math:`\texttt{'C'}` or :math:`\texttt{'B'}`. (`errno` :math:`-13`) On entry, error in parameter :math:`\mathrm{r}`. (`errno` :math:`-14`) On entry, error in parameter :math:`\mathrm{c}`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq \mathrm{n}\right)`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`U` is exactly singular, so the solution and error bounds could not be computed. :math:`\mathrm{rcond} = 0.0` is returned. (`errno` :math:`\mathrm{n}+1`) :math:`U` is nonsingular, but :math:`\mathrm{rcond}` is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of :math:`\mathrm{rcond}` would suggest. .. _f07bb-py2-py-notes: **Notes** ``dgbsvx`` performs the following steps: (1) **Equilibration** The linear system to be solved may be badly scaled. However, the system can be equilibrated as a first stage by setting :math:`\mathrm{fact} = \texttt{'E'}`. In this case, real scaling factors are computed and these factors then determine whether the system is to be equilibrated. Equilibrated forms of the systems :math:`AX = B` and :math:`A^\mathrm{T}X = B` are .. math:: \left(D_RAD_C\right)\left(D_C^{-1}X\right) = D_RB and .. math:: \left(D_RAD_C\right)^\mathrm{T}\left(D_R^{-1}X\right) = D_CB\text{,} respectively, where :math:`D_R` and :math:`D_C` are diagonal matrices, with positive diagonal elements, formed from the computed scaling factors. When equilibration is used, :math:`A` will be overwritten by :math:`D_RAD_C` and :math:`B` will be overwritten by :math:`D_RB` (or :math:`D_CB` when the solution of :math:`A^\mathrm{T}X = B` is sought). (#) **Factorization** The matrix :math:`A`, or its scaled form, is copied and factored using the :math:`LU` decomposition .. math:: A = PLU\text{,} where :math:`P` is a permutation matrix, :math:`L` is a unit lower triangular matrix, and :math:`U` is upper triangular. This stage can be by-passed when a factored matrix (with scaled matrices and scaling factors) are supplied; for example, as provided by a previous call to ``dgbsvx`` with the same matrix :math:`A`. (#) **Condition Number Estimation** The :math:`LU` factorization of :math:`A` determines whether a solution to the linear system exists. If some diagonal element of :math:`U` is zero, then :math:`U` is exactly singular, no solution exists and the function returns with a failure. Otherwise the factorized form of :math:`A` is used to estimate the condition number of the matrix :math:`A`. If the reciprocal of the condition number is less than machine precision then a warning code is returned on final exit. (#) **Solution** The (equilibrated) system is solved for :math:`X` (:math:`D_C^{-1}X` or :math:`D_R^{-1}X`) using the factored form of :math:`A` (:math:`D_RAD_C`). (#) **Iterative Refinement** Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for the computed solution. (#) **Construct Solution Matrix** :math:`X` If equilibration was used, the matrix :math:`X` is premultiplied by :math:`D_C` (if :math:`\mathrm{trans} = \texttt{'N'}`) or :math:`D_R` (if :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}`) so that it solves the original system before equilibration. .. _f07bb-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def dgbtrf(m, kl, ku, ab): r""" ``dgbtrf`` computes the :math:`LU` factorization of a real :math:`m\times n` band matrix. .. _f07bd-py2-py-doc: For full information please refer to the NAG Library document for f07bd https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07bdf.html .. _f07bd-py2-py-parameters: **Parameters** **m** : int :math:`m`, the number of rows of the matrix :math:`A`. **kl** : int :math:`k_l`, the number of subdiagonals within the band of the matrix :math:`A`. **ku** : int :math:`k_u`, the number of superdiagonals within the band of the matrix :math:`A`. **ab** : float, array-like, shape :math:`\left(2\times \mathrm{kl}+\mathrm{ku}+1, n\right)` The :math:`m\times n` matrix :math:`A`. See `Further Comments <https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07baf.html#fcomments>`__ for further details. **Returns** **ab** : float, ndarray, shape :math:`\left(2\times \mathrm{kl}+\mathrm{ku}+1, n\right)` If :math:`\mathrm{errno}` >= 0, :math:`\mathrm{ab}` is overwritten by details of the factorization. **ipiv** : int, ndarray, shape :math:`\left(\min\left(\mathrm{m},n\right)\right)` The pivot indices that define the permutation matrix. At the :math:`\textit{i}`\ th step, if :math:`\mathrm{ipiv}[\textit{i}-1] > \textit{i}` then row :math:`\textit{i}` of the matrix :math:`A` was interchanged with row :math:`\mathrm{ipiv}[\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,\mathrm{min}\left(m, n\right)`. :math:`\mathrm{ipiv}[i-1]\leq i` indicates that, at the :math:`i`\ th step, a row interchange was not required. .. _f07bd-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{m}`. Constraint: :math:`\mathrm{m}\geq 0`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{kl}`. Constraint: :math:`\mathrm{kl}\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\mathrm{ku}`. Constraint: :math:`\mathrm{ku}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`U` is exactly singular, and division by zero will occur if it is used to solve a system of equations. .. _f07bd-py2-py-notes: **Notes** ``dgbtrf`` forms the :math:`LU` factorization of a real :math:`m\times n` band matrix :math:`A` using partial pivoting, with row interchanges. Usually :math:`m = n`, and then, if :math:`A` has :math:`k_l` nonzero subdiagonals and :math:`k_u` nonzero superdiagonals, the factorization has the form :math:`A = PLU`, where :math:`P` is a permutation matrix, :math:`L` is a lower triangular matrix with unit diagonal elements and at most :math:`k_l` nonzero elements in each column, and :math:`U` is an upper triangular band matrix with :math:`k_l+k_u` superdiagonals. Note that :math:`L` is not a band matrix, but the nonzero elements of :math:`L` can be stored in the same space as the subdiagonal elements of :math:`A`. :math:`U` is a band matrix but with :math:`k_l` additional superdiagonals compared with :math:`A`. These additional superdiagonals are created by the row interchanges. .. _f07bd-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def dgbtrs(trans, kl, ku, ab, ipiv, b): r""" ``dgbtrs`` solves a real band system of linear equations with multiple right-hand sides, .. math:: AX = B\quad \text{ or }\quad A^\mathrm{T}X = B\text{,} where :math:`A` has been factorized by :meth:`dgbtrf`. .. _f07be-py2-py-doc: For full information please refer to the NAG Library document for f07be https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07bef.html .. _f07be-py2-py-parameters: **Parameters** **trans** : str, length 1 Indicates the form of the equations. :math:`\mathrm{trans} = \texttt{'N'}` :math:`AX = B` is solved for :math:`X`. :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}` :math:`A^\mathrm{T}X = B` is solved for :math:`X`. **kl** : int :math:`k_l`, the number of subdiagonals within the band of the matrix :math:`A`. **ku** : int :math:`k_u`, the number of superdiagonals within the band of the matrix :math:`A`. **ab** : float, array-like, shape :math:`\left(2\times \mathrm{kl}+\mathrm{ku}+1, n\right)` The :math:`LU` factorization of :math:`A`, as returned by :meth:`dgbtrf`. **ipiv** : int, array-like, shape :math:`\left(n\right)` The pivot indices, as returned by :meth:`dgbtrf`. **b** : float, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **b** : float, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`. .. _f07be-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{trans}`. Constraint: :math:`\mathrm{trans} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{kl}`. Constraint: :math:`\mathrm{kl}\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\mathrm{ku}`. Constraint: :math:`\mathrm{ku}\geq 0`. (`errno` :math:`-5`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. .. _f07be-py2-py-notes: **Notes** ``dgbtrs`` is used to solve a real band system of linear equations :math:`AX = B` or :math:`A^\mathrm{T}X = B`, the function must be preceded by a call to :meth:`dgbtrf` which computes the :math:`LU` factorization of :math:`A` as :math:`A = PLU`. The solution is computed by forward and backward substitution. If :math:`\mathrm{trans} = \texttt{'N'}`, the solution is computed by solving :math:`PLY = B` and then :math:`UX = Y`. If :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}`, the solution is computed by solving :math:`U^\mathrm{T}Y = B` and then :math:`L^\mathrm{T}P^\mathrm{T}X = Y`. .. _f07be-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def dgbequ(m, kl, ku, ab): r""" ``dgbequ`` computes diagonal scaling matrices :math:`D_R` and :math:`D_C` intended to equilibrate a real :math:`m\times n` band matrix :math:`A` of band width :math:`\left(k_l+k_u+1\right)`, and reduce its condition number. .. _f07bf-py2-py-doc: For full information please refer to the NAG Library document for f07bf https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07bff.html .. _f07bf-py2-py-parameters: **Parameters** **m** : int :math:`m`, the number of rows of the matrix :math:`A`. **kl** : int :math:`k_l`, the number of subdiagonals of the matrix :math:`A`. **ku** : int :math:`k_u`, the number of superdiagonals of the matrix :math:`A`. **ab** : float, array-like, shape :math:`\left(\mathrm{kl}+\mathrm{ku}+1, n\right)` The :math:`m\times n` band matrix :math:`A` whose scaling factors are to be computed. See `Further Comments <https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07baf.html#fcomments>`__ for further details. **Returns** **r** : float, ndarray, shape :math:`\left(\mathrm{m}\right)` If no exception or warning is raised or :math:`\mathrm{errno}` > :math:`\mathrm{m}`, :math:`\mathrm{r}` contains the row scale factors, the diagonal elements of :math:`D_R`. The elements of :math:`\mathrm{r}` will be positive. **c** : float, ndarray, shape :math:`\left(n\right)` If no exception or warning is raised, :math:`\mathrm{c}` contains the column scale factors, the diagonal elements of :math:`D_C`. The elements of :math:`\mathrm{c}` will be positive. **rowcnd** : float If no exception or warning is raised or :math:`\mathrm{errno}` > :math:`\mathrm{m}`, :math:`\mathrm{rowcnd}` contains the ratio of the smallest value of :math:`\mathrm{r}[i-1]` to the largest value of :math:`\mathrm{r}[i-1]`. If :math:`\mathrm{rowcnd}\geq 0.1` and :math:`\mathrm{amax}` is neither too large nor too small, it is not worth scaling by :math:`D_R`. **colcnd** : float If no exception or warning is raised, :math:`\mathrm{colcnd}` contains the ratio of the smallest value of :math:`\mathrm{c}[i-1]` to the largest value of :math:`\mathrm{c}[i-1]`. If :math:`\mathrm{colcnd}\geq 0.1`, it is not worth scaling by :math:`D_C`. **amax** : float :math:`\mathrm{max}\left\lvert a_{{ij}}\right\rvert`. If :math:`\mathrm{amax}` is very close to overflow or underflow, the matrix :math:`A` should be scaled. .. _f07bf-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{m}`. Constraint: :math:`\mathrm{m}\geq 0`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{kl}`. Constraint: :math:`\mathrm{kl}\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\mathrm{ku}`. Constraint: :math:`\mathrm{ku}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq \mathrm{m}\right)`) Row :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is exactly zero. (`errno` :math:`i > \mathrm{m}`) Column :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is exactly zero. .. _f07bf-py2-py-notes: **Notes** ``dgbequ`` computes the diagonal scaling matrices. The diagonal scaling matrices are chosen to try to make the elements of largest absolute value in each row and column of the matrix :math:`B` given by .. math:: B = D_RAD_C have absolute value :math:`1`. The diagonal elements of :math:`D_R` and :math:`D_C` are restricted to lie in the safe range :math:`\left(\delta, {1/\delta }\right)`, where :math:`\delta` is the value returned by function :meth:`machine.real_safe <naginterfaces.library.machine.real_safe>`. Use of these scaling factors is not guaranteed to reduce the condition number of :math:`A` but works well in practice. """ raise NotImplementedError
[docs]def dgbcon(norm, kl, ku, ab, ipiv, anorm): r""" ``dgbcon`` estimates the condition number of a real band matrix :math:`A`, where :math:`A` has been factorized by :meth:`dgbtrf`. .. _f07bg-py2-py-doc: For full information please refer to the NAG Library document for f07bg https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07bgf.html .. _f07bg-py2-py-parameters: **Parameters** **norm** : str, length 1 Indicates whether :math:`\kappa_1\left(A\right)` or :math:`\kappa_{\infty }\left(A\right)` is estimated. :math:`\mathrm{norm} = \texttt{'1'}` or :math:`\texttt{'O'}` :math:`\kappa_1\left(A\right)` is estimated. :math:`\mathrm{norm} = \texttt{'I'}` :math:`\kappa_{\infty }\left(A\right)` is estimated. **kl** : int :math:`k_l`, the number of subdiagonals within the band of the matrix :math:`A`. **ku** : int :math:`k_u`, the number of superdiagonals within the band of the matrix :math:`A`. **ab** : float, array-like, shape :math:`\left(2\times \mathrm{kl}+\mathrm{ku}+1, n\right)` The :math:`LU` factorization of :math:`A`, as returned by :meth:`dgbtrf`. **ipiv** : int, array-like, shape :math:`\left(n\right)` The pivot indices, as returned by :meth:`dgbtrf`. **anorm** : float If :math:`\mathrm{norm} = \texttt{'1'}` or :math:`\texttt{'O'}`, the :math:`1`-norm of the **original** matrix :math:`A`. If :math:`\mathrm{norm} = \texttt{'I'}`, the :math:`\infty`-norm of the **original** matrix :math:`A`. :math:`\mathrm{anorm}` may be computed by calling :meth:`blas.dlangb <naginterfaces.library.blas.dlangb>` with the same value for the argument :math:`\mathrm{norm}`. :math:`\mathrm{anorm}` must be computed either **before** calling :meth:`dgbtrf` or else from a **copy** of the original matrix :math:`A`. **Returns** **rcond** : float An estimate of the reciprocal of the condition number of :math:`A`. :math:`\mathrm{rcond}` is set to zero if exact singularity is detected or the estimate underflows. If :math:`\mathrm{rcond}` is less than machine precision, :math:`A` is singular to working precision. .. _f07bg-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{norm}`. Constraint: :math:`\mathrm{norm} = \texttt{'1'}`, :math:`\texttt{'O'}` or :math:`\texttt{'I'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{kl}`. Constraint: :math:`\mathrm{kl}\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\mathrm{ku}`. Constraint: :math:`\mathrm{ku}\geq 0`. (`errno` :math:`-8`) On entry, error in parameter :math:`\mathrm{anorm}`. Constraint: :math:`\mathrm{anorm}\geq 0.0`. .. _f07bg-py2-py-notes: **Notes** ``dgbcon`` estimates the condition number of a real band matrix :math:`A`, in either the :math:`1`-norm or the :math:`\infty`-norm: .. math:: \kappa_1\left(A\right) = \left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\quad \text{ or }\quad \kappa_{\infty }\left(A\right) = \left\lVert A\right\rVert_\infty\left\lVert A^{-1}\right\rVert_\infty\text{.} Note that :math:`\kappa_{\infty }\left(A\right) = \kappa_1\left(A^\mathrm{T}\right)`. Because the condition number is infinite if :math:`A` is singular, the function actually returns an estimate of the **reciprocal** of the condition number. The function should be preceded by a call to :meth:`blas.dlangb <naginterfaces.library.blas.dlangb>` to compute :math:`\left\lVert A\right\rVert_1` or :math:`\left\lVert A\right\rVert_\infty`, and a call to :meth:`dgbtrf` to compute the :math:`LU` factorization of :math:`A`. The function then uses Higham's implementation of Hager's method (see Higham (1988)) to estimate :math:`\left\lVert A^{-1}\right\rVert_1` or :math:`\left\lVert A^{-1}\right\rVert_\infty`. .. _f07bg-py2-py-references: **References** Higham, N J, 1988, `FORTRAN codes for estimating the one-norm of a real or complex matrix, with applications to condition estimation`, ACM Trans. Math. Software (14), 381--396 """ raise NotImplementedError
[docs]def dgbrfs(trans, kl, ku, nrhs, ab, afb, ipiv, b, x): r""" ``dgbrfs`` returns error bounds for the solution of a real band system of linear equations with multiple right-hand sides, :math:`AX = B` or :math:`A^\mathrm{T}X = B`. It improves the solution by iterative refinement, in order to reduce the backward error as much as possible. .. _f07bh-py2-py-doc: For full information please refer to the NAG Library document for f07bh https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07bhf.html .. _f07bh-py2-py-parameters: **Parameters** **trans** : str, length 1 Indicates the form of the linear equations for which :math:`X` is the computed solution. :math:`\mathrm{trans} = \texttt{'N'}` The linear equations are of the form :math:`AX = B`. :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}` The linear equations are of the form :math:`A^\mathrm{T}X = B`. **kl** : int :math:`k_l`, the number of subdiagonals within the band of the matrix :math:`A`. **ku** : int :math:`k_u`, the number of superdiagonals within the band of the matrix :math:`A`. **nrhs** : int :math:`r`, the number of right-hand sides. **ab** : float, array-like, shape :math:`\left(\mathrm{kl}+\mathrm{ku}+1, n\right)` The original :math:`n\times n` band matrix :math:`A` as supplied to :meth:`dgbtrf` but with reduced requirements since the matrix is not factorized. See `Further Comments <https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07baf.html#fcomments>`__ for further details. **afb** : float, array-like, shape :math:`\left(2\times \mathrm{kl}+\mathrm{ku}+1, n\right)` The :math:`LU` factorization of :math:`A`, as returned by :meth:`dgbtrf`. **ipiv** : int, array-like, shape :math:`\left(n\right)` The pivot indices, as returned by :meth:`dgbtrf`. **b** : float, array-like, shape :math:`\left(n, \mathrm{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **x** : float, array-like, shape :math:`\left(n, \mathrm{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`, as returned by :meth:`dgbtrs`. **Returns** **x** : float, ndarray, shape :math:`\left(n, \mathrm{nrhs}\right)` The improved solution matrix :math:`X`. **ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` :math:`\mathrm{ferr}[\textit{j}-1]` contains an estimated error bound for the :math:`\textit{j}`\ th solution vector, that is, the :math:`\textit{j}`\ th column of :math:`X`, for :math:`\textit{j} = 1,2,\ldots,r`. **berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` :math:`\mathrm{berr}[\textit{j}-1]` contains the component-wise backward error bound :math:`\beta` for the :math:`\textit{j}`\ th solution vector, that is, the :math:`\textit{j}`\ th column of :math:`X`, for :math:`\textit{j} = 1,2,\ldots,r`. .. _f07bh-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{trans}`. Constraint: :math:`\mathrm{trans} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{kl}`. Constraint: :math:`\mathrm{kl}\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\mathrm{ku}`. Constraint: :math:`\mathrm{ku}\geq 0`. (`errno` :math:`-5`) On entry, error in parameter :math:`\mathrm{nrhs}`. Constraint: :math:`\mathrm{nrhs}\geq 0`. .. _f07bh-py2-py-notes: **Notes** ``dgbrfs`` returns the backward errors and estimated bounds on the forward errors for the solution of a real band system of linear equations with multiple right-hand sides :math:`AX = B` or :math:`A^\mathrm{T}X = B`. The function handles each right-hand side vector (stored as a column of the matrix :math:`B`) independently, so we describe the function of ``dgbrfs`` in terms of a single right-hand side :math:`b` and solution :math:`x`. Given a computed solution :math:`x`, the function computes the `component-wise backward error` :math:`\beta`. This is the size of the smallest relative perturbation in each element of :math:`A` and :math:`b` such that :math:`x` is the exact solution of a perturbed system .. math:: \begin{array}{c}\left(A+\delta A\right)x = b+\delta b\\\left\lvert \delta a_{{ij}}\right\rvert \leq \beta \left\lvert a_{{ij}}\right\rvert \quad \text{ and }\quad \left\lvert \delta b_i\right\rvert \leq \beta \left\lvert b_i\right\rvert \text{.} \end{array} Then the function estimates a bound for the `component-wise forward error` in the computed solution, defined by: .. math:: \mathrm{max}_i\left\lvert x_i-\hat{x}_i\right\rvert /\mathrm{max}_i\left\lvert x_i\right\rvert where :math:`\hat{x}` is the true solution. For details of the method, see `the F07 Introduction <https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07intro.html>`__. .. _f07bh-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def zgbsv(kl, ku, ab, b): r""" ``zgbsv`` computes the solution to a complex system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` band matrix, with :math:`k_l` subdiagonals and :math:`k_u` superdiagonals, and :math:`X` and :math:`B` are :math:`n\times r` matrices. .. _f07bn-py2-py-doc: For full information please refer to the NAG Library document for f07bn https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07bnf.html .. _f07bn-py2-py-parameters: **Parameters** **kl** : int :math:`k_l`, the number of subdiagonals within the band of the matrix :math:`A`. **ku** : int :math:`k_u`, the number of superdiagonals within the band of the matrix :math:`A`. **ab** : complex, array-like, shape :math:`\left(2\times \mathrm{kl}+\mathrm{ku}+1, n\right)` The :math:`n\times n` coefficient matrix :math:`A`. See `Further Comments <https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07bnf.html#fcomments>`__ for further details. **b** : complex, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **ab** : complex, ndarray, shape :math:`\left(2\times \mathrm{kl}+\mathrm{ku}+1, n\right)` If :math:`\mathrm{errno}` >= 0, :math:`\mathrm{ab}` is overwritten by details of the factorization. **ipiv** : int, ndarray, shape :math:`\left(n\right)` If no constraints are violated, the pivot indices that define the permutation matrix :math:`P`; at the :math:`i`\ th step row :math:`i` of the matrix was interchanged with row :math:`\mathrm{ipiv}[i-1]`. :math:`\mathrm{ipiv}[i-1] = i` indicates a row interchange was not required. **b** : complex, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`. .. _f07bn-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{kl}`. Constraint: :math:`\mathrm{kl}\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{ku}`. Constraint: :math:`\mathrm{ku}\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`U` is exactly singular, so the solution could not be computed. .. _f07bn-py2-py-notes: **Notes** ``zgbsv`` uses the :math:`LU` decomposition with partial pivoting and row interchanges to factor :math:`A` as :math:`A = PLU`, where :math:`P` is a permutation matrix, :math:`L` is a product of permutation and unit lower triangular matrices with :math:`k_l` subdiagonals, and :math:`U` is upper triangular with :math:`\left(k_l+k_u\right)` superdiagonals. The factored form of :math:`A` is then used to solve the system of equations :math:`AX = B`. .. _f07bn-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def zgbsvx(fact, trans, kl, ku, nrhs, ab, afb, ipiv, equed, r, c, b): r""" ``zgbsvx`` uses the :math:`LU` factorization to compute the solution to a complex system of linear equations .. math:: AX = B\text{, }\quad A^\mathrm{T}X = B\quad \text{ or }\quad A^\mathrm{H}X = B\text{,} where :math:`A` is an :math:`n\times n` band matrix with :math:`k_l` subdiagonals and :math:`k_u` superdiagonals, and :math:`X` and :math:`B` are :math:`n\times r` matrices. Error bounds on the solution and a condition estimate are also provided. .. _f07bp-py2-py-doc: For full information please refer to the NAG Library document for f07bp https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07bpf.html .. _f07bp-py2-py-parameters: **Parameters** **fact** : str, length 1 Specifies whether or not the factorized form of the matrix :math:`A` is supplied on entry, and if not, whether the matrix :math:`A` should be equilibrated before it is factorized. :math:`\mathrm{fact} = \texttt{'F'}` :math:`\mathrm{afb}` and :math:`\mathrm{ipiv}` contain the factorized form of :math:`A`. If :math:`\mathrm{equed} \neq \texttt{'N'}`, the matrix :math:`A` has been equilibrated with scaling factors given by :math:`\mathrm{r}` and :math:`\mathrm{c}`. :math:`\mathrm{ab}`, :math:`\mathrm{afb}` and :math:`\mathrm{ipiv}` are not modified. :math:`\mathrm{fact} = \texttt{'N'}` The matrix :math:`A` will be copied to :math:`\mathrm{afb}` and factorized. :math:`\mathrm{fact} = \texttt{'E'}` The matrix :math:`A` will be equilibrated if necessary, then copied to :math:`\mathrm{afb}` and factorized. **trans** : str, length 1 Specifies the form of the system of equations. :math:`\mathrm{trans} = \texttt{'N'}` :math:`AX = B` (No transpose). :math:`\mathrm{trans} = \texttt{'T'}` :math:`A^\mathrm{T}X = B` (Transpose). :math:`\mathrm{trans} = \texttt{'C'}` :math:`A^\mathrm{H}X = B` (Conjugate transpose). **kl** : int :math:`k_l`, the number of subdiagonals within the band of the matrix :math:`A`. **ku** : int :math:`k_u`, the number of superdiagonals within the band of the matrix :math:`A`. **nrhs** : int :math:`r`, the number of right-hand sides, i.e., the number of columns of the matrix :math:`B`. **ab** : complex, array-like, shape :math:`\left(\mathrm{kl}+\mathrm{ku}+1, n\right)` The :math:`n\times n` coefficient matrix :math:`A`. See `Further Comments <https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07bpf.html#fcomments>`__ for further details. If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} \neq \texttt{'N'}`, :math:`A` must have been equilibrated by the scaling factors in :math:`\mathrm{r}` and/or :math:`\mathrm{c}`. **afb** : complex, array-like, shape :math:`\left(2\times \mathrm{kl}+\mathrm{ku}+1, n\right)` If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{afb}` need not be set. If :math:`\mathrm{fact} = \texttt{'F'}`, details of the :math:`LU` factorization of the :math:`n\times n` band matrix :math:`A`, as computed by :meth:`zgbtrf`. If :math:`\mathrm{equed} \neq \texttt{'N'}`, :math:`\mathrm{afb}` is the factorized form of the equilibrated matrix :math:`A`. **ipiv** : int, array-like, shape :math:`\left(n\right)` If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{ipiv}` need not be set. If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{ipiv}` contains the pivot indices from the factorization :math:`A = LU`, as computed by :meth:`dgbtrf`; row :math:`i` of the matrix was interchanged with row :math:`\mathrm{ipiv}[i-1]`. **equed** : str, length 1 If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{equed}` need not be set. If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` must specify the form of the equilibration that was performed as follows: if :math:`\mathrm{equed} = \texttt{'N'}`, no equilibration; if :math:`\mathrm{equed} = \texttt{'R'}`, row equilibration, i.e., :math:`A` has been premultiplied by :math:`D_R`; if :math:`\mathrm{equed} = \texttt{'C'}`, column equilibration, i.e., :math:`A` has been postmultiplied by :math:`D_C`; if :math:`\mathrm{equed} = \texttt{'B'}`, both row and column equilibration, i.e., :math:`A` has been replaced by :math:`D_RAD_C`. **r** : float, array-like, shape :math:`\left(n\right)` If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{r}` need not be set. If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{r}` must contain the row scale factors for :math:`A`, :math:`D_R`; each element of :math:`\mathrm{r}` must be positive. **c** : float, array-like, shape :math:`\left(n\right)` If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{c}` need not be set. If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'C'}` or :math:`\texttt{'B'}`, :math:`\mathrm{c}` must contain the column scale factors for :math:`A`, :math:`D_C`; each element of :math:`\mathrm{c}` must be positive. **b** : complex, array-like, shape :math:`\left(n, \mathrm{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **ab** : complex, ndarray, shape :math:`\left(\mathrm{kl}+\mathrm{ku}+1, n\right)` If :math:`\mathrm{fact} = \texttt{'F'}` or :math:`\texttt{'N'}`, or if :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{ab}` is not modified. If :math:`\mathrm{equed} \neq \texttt{'N'}` then, if no constraints are violated, :math:`A` is scaled as follows: if :math:`\mathrm{equed} = \texttt{'R'}`, :math:`A = D_rA`; if :math:`\mathrm{equed} = \texttt{'C'}`, :math:`A = AD_c`; if :math:`\mathrm{equed} = \texttt{'B'}`, :math:`A = D_rAD_c`. **afb** : complex, ndarray, shape :math:`\left(2\times \mathrm{kl}+\mathrm{ku}+1, n\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{afb}` is unchanged from entry. Otherwise, if no constraints are violated, then if :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{afb}` returns details of the :math:`LU` factorization of the band matrix :math:`A`, and if :math:`\mathrm{fact} = \texttt{'E'}`, :math:`\mathrm{afb}` returns details of the :math:`LU` factorization of the equilibrated band matrix :math:`A` (see the description of :math:`\mathrm{ab}` for the form of the equilibrated matrix). **ipiv** : int, ndarray, shape :math:`\left(n\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{ipiv}` is unchanged from entry. Otherwise, if no constraints are violated, :math:`\mathrm{ipiv}` contains the pivot indices that define the permutation matrix :math:`P`; at the :math:`i`\ th step row :math:`i` of the matrix was interchanged with row :math:`\mathrm{ipiv}[i-1]`. :math:`\mathrm{ipiv}[i-1] = i` indicates a row interchange was not required. If :math:`\mathrm{fact} = \texttt{'N'}`, the pivot indices are those corresponding to the factorization :math:`A = LU` of the original matrix :math:`A`. If :math:`\mathrm{fact} = \texttt{'E'}`, the pivot indices are those corresponding to the factorization of :math:`A = LU` of the equilibrated matrix :math:`A`. **equed** : str, length 1 If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` is unchanged from entry. Otherwise, if no constraints are violated, :math:`\mathrm{equed}` specifies the form of equilibration that was performed as specified above. **r** : float, ndarray, shape :math:`\left(n\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{r}` is unchanged from entry. Otherwise, if no constraints are violated and :math:`\mathrm{equed} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{r}` contains the row scale factors for :math:`A`, :math:`D_R`, such that :math:`A` is multiplied on the left by :math:`D_R`; each element of :math:`\mathrm{r}` is positive. **c** : float, ndarray, shape :math:`\left(n\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{c}` is unchanged from entry. Otherwise, if no constraints are violated and :math:`\mathrm{equed} = \texttt{'C'}` or :math:`\texttt{'B'}`, :math:`\mathrm{c}` contains the row scale factors for :math:`A`, :math:`D_C`; each element of :math:`\mathrm{c}` is positive. **b** : complex, ndarray, shape :math:`\left(n, \mathrm{nrhs}\right)` If :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{b}` is not modified. If :math:`\mathrm{trans} = \texttt{'N'}` and :math:`\mathrm{equed} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{b}` is overwritten by :math:`D_RB`. If :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}` and :math:`\mathrm{equed} = \texttt{'C'}` or :math:`\texttt{'B'}`, :math:`\mathrm{b}` is overwritten by :math:`D_CB`. **x** : complex, ndarray, shape :math:`\left(n, \mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, the :math:`n\times r` solution matrix :math:`X` to the original system of equations. Note that the arrays :math:`A` and :math:`B` are modified on exit if :math:`\mathrm{equed} \neq \texttt{'N'}`, and the solution to the equilibrated system is :math:`D_C^{-1}X` if :math:`\mathrm{trans} = \texttt{'N'}` and :math:`\mathrm{equed} = \texttt{'C'}` or :math:`\texttt{'B'}`, or :math:`D_R^{-1}X` if :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}` and :math:`\mathrm{equed} = \texttt{'R'}` or :math:`\texttt{'B'}`. **rcond** : float If no constraints are violated, an estimate of the reciprocal condition number of the matrix :math:`A` (after equilibration if that is performed), computed as :math:`\mathrm{rcond} = 1.0/\left(\left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\right)`. **ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the forward error bound for each computed solution vector, such that :math:`\left\lVert \hat{x}_j-x_j\right\rVert_\infty/\left\lVert x_j\right\rVert_\infty\leq \mathrm{ferr}[j-1]` where :math:`\hat{x}_j` is the :math:`j`\ th column of the computed solution returned in the array :math:`\mathrm{x}` and :math:`x_j` is the corresponding column of the exact solution :math:`X`. The estimate is as reliable as the estimate for :math:`\mathrm{rcond}`, and is almost always a slight overestimate of the true error. **berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the component-wise relative backward error of each computed solution vector :math:`\hat{x}_j` (i.e., the smallest relative change in any element of :math:`A` or :math:`B` that makes :math:`\hat{x}_j` an exact solution). **recip_growth_factor** : float If no exception or warning is raised, the reciprocal pivot growth factor :math:`\left\lVert A\right\rVert /\left\lVert U\right\rVert`, where :math:`\left\lVert.\right\rVert` denotes the maximum absolute element norm. If :math:`\mathrm{recip\_growth\_factor}≪1`, the stability of the :math:`LU` factorization of (equilibrated) :math:`A` could be poor. This also means that the solution :math:`\mathrm{x}`, condition estimate :math:`\mathrm{rcond}`, and forward error bound :math:`\mathrm{ferr}` could be unreliable. If the factorization fails with :math:`\mathrm{errno}` in 1 ... :math:`\mathrm{n}`, then :math:`\mathrm{recip\_growth\_factor}` contains the reciprocal pivot growth factor for the leading :math:`\textit{errno}` columns of :math:`A`. .. _f07bp-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{fact}`. Constraint: :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\texttt{'N'}` or :math:`\texttt{'E'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{trans}`. Constraint: :math:`\mathrm{trans} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\mathrm{kl}`. Constraint: :math:`\mathrm{kl}\geq 0`. (`errno` :math:`-5`) On entry, error in parameter :math:`\mathrm{ku}`. Constraint: :math:`\mathrm{ku}\geq 0`. (`errno` :math:`-6`) On entry, error in parameter :math:`\mathrm{nrhs}`. Constraint: :math:`\mathrm{nrhs}\geq 0`. (`errno` :math:`-12`) On entry, error in parameter :math:`\mathrm{equed}`. Constraint: :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\texttt{'R'}`, :math:`\texttt{'C'}` or :math:`\texttt{'B'}`. (`errno` :math:`-13`) On entry, error in parameter :math:`\mathrm{r}`. (`errno` :math:`-14`) On entry, error in parameter :math:`\mathrm{c}`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq n\right)`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`U` is exactly singular, so the solution and error bounds could not be computed. :math:`\mathrm{rcond} = 0.0` is returned. (`errno` :math:`n+1`) :math:`U` is nonsingular, but :math:`\mathrm{rcond}` is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of :math:`\mathrm{rcond}` would suggest. .. _f07bp-py2-py-notes: **Notes** ``zgbsvx`` performs the following steps: (1) **Equilibration** The linear system to be solved may be badly scaled. However, the system can be equilibrated as a first stage by setting :math:`\mathrm{fact} = \texttt{'E'}`. In this case, real scaling factors are computed and these factors then determine whether the system is to be equilibrated. Equilibrated forms of the systems :math:`AX = B`, :math:`A^\mathrm{T}X = B` and :math:`A^\mathrm{H}X = B` are .. math:: \left(D_RAD_C\right)\left(D_C^{-1}X\right) = D_RB\text{,} .. math:: \left(D_RAD_C\right)^\mathrm{T}\left(D_R^{-1}X\right) = D_CB\text{,} and .. math:: \left(D_RAD_C\right)^\mathrm{H}\left(D_R^{-1}X\right) = D_CB\text{,} respectively, where :math:`D_R` and :math:`D_C` are diagonal matrices, with positive diagonal elements, formed from the computed scaling factors. When equilibration is used, :math:`A` will be overwritten by :math:`D_RAD_C` and :math:`B` will be overwritten by :math:`D_RB` (or :math:`D_CB` when the solution of :math:`A^\mathrm{T}X = B` or :math:`A^\mathrm{H}X = B` is sought). (#) **Factorization** The matrix :math:`A`, or its scaled form, is copied and factored using the :math:`LU` decomposition .. math:: A = PLU\text{,} where :math:`P` is a permutation matrix, :math:`L` is a unit lower triangular matrix, and :math:`U` is upper triangular. This stage can be by-passed when a factored matrix (with scaled matrices and scaling factors) are supplied; for example, as provided by a previous call to ``zgbsvx`` with the same matrix :math:`A`. (#) **Condition Number Estimation** The :math:`LU` factorization of :math:`A` determines whether a solution to the linear system exists. If some diagonal element of :math:`U` is zero, then :math:`U` is exactly singular, no solution exists and the function returns with a failure. Otherwise the factorized form of :math:`A` is used to estimate the condition number of the matrix :math:`A`. If the reciprocal of the condition number is less than machine precision then a warning code is returned on final exit. (#) **Solution** The (equilibrated) system is solved for :math:`X` (:math:`D_C^{-1}X` or :math:`D_R^{-1}X`) using the factored form of :math:`A` (:math:`D_RAD_C`). (#) **Iterative Refinement** Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for the computed solution. (#) **Construct Solution Matrix** :math:`X` If equilibration was used, the matrix :math:`X` is premultiplied by :math:`D_C` (if :math:`\mathrm{trans} = \texttt{'N'}`) or :math:`D_R` (if :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}`) so that it solves the original system before equilibration. .. _f07bp-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def zgbtrf(m, kl, ku, ab): r""" ``zgbtrf`` computes the :math:`LU` factorization of a complex :math:`m\times n` band matrix. .. _f07br-py2-py-doc: For full information please refer to the NAG Library document for f07br https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07brf.html .. _f07br-py2-py-parameters: **Parameters** **m** : int :math:`m`, the number of rows of the matrix :math:`A`. **kl** : int :math:`k_l`, the number of subdiagonals within the band of the matrix :math:`A`. **ku** : int :math:`k_u`, the number of superdiagonals within the band of the matrix :math:`A`. **ab** : complex, array-like, shape :math:`\left(2\times \mathrm{kl}+\mathrm{ku}+1, n\right)` The :math:`m\times n` matrix :math:`A`. See `Further Comments <https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07bnf.html#fcomments>`__ for further details. **Returns** **ab** : complex, ndarray, shape :math:`\left(2\times \mathrm{kl}+\mathrm{ku}+1, n\right)` If :math:`\mathrm{errno}` >= 0, :math:`\mathrm{ab}` is overwritten by details of the factorization. **ipiv** : int, ndarray, shape :math:`\left(\min\left(\mathrm{m},n\right)\right)` The pivot indices that define the permutation matrix. At the :math:`\textit{i}`\ th step, if :math:`\mathrm{ipiv}[\textit{i}-1] > \textit{i}` then row :math:`\textit{i}` of the matrix :math:`A` was interchanged with row :math:`\mathrm{ipiv}[\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,\mathrm{min}\left(m, n\right)`. :math:`\mathrm{ipiv}[i-1]\leq i` indicates that, at the :math:`i`\ th step, a row interchange was not required. .. _f07br-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{m}`. Constraint: :math:`\mathrm{m}\geq 0`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{kl}`. Constraint: :math:`\mathrm{kl}\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\mathrm{ku}`. Constraint: :math:`\mathrm{ku}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`U` is exactly singular, and division by zero will occur if it is used to solve a system of equations. .. _f07br-py2-py-notes: **Notes** ``zgbtrf`` forms the :math:`LU` factorization of a complex :math:`m\times n` band matrix :math:`A` using partial pivoting, with row interchanges. Usually :math:`m = n`, and then, if :math:`A` has :math:`k_l` nonzero subdiagonals and :math:`k_u` nonzero superdiagonals, the factorization has the form :math:`A = PLU`, where :math:`P` is a permutation matrix, :math:`L` is a lower triangular matrix with unit diagonal elements and at most :math:`k_l` nonzero elements in each column, and :math:`U` is an upper triangular band matrix with :math:`k_l+k_u` superdiagonals. Note that :math:`L` is not a band matrix, but the nonzero elements of :math:`L` can be stored in the same space as the subdiagonal elements of :math:`A`. :math:`U` is a band matrix but with :math:`k_l` additional superdiagonals compared with :math:`A`. These additional superdiagonals are created by the row interchanges. .. _f07br-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def zgbtrs(trans, kl, ku, ab, ipiv, b): r""" ``zgbtrs`` solves a complex band system of linear equations with multiple right-hand sides, .. math:: AX = B\text{, }\quad A^\mathrm{T}X = B\quad \text{ or }\quad A^\mathrm{H}X = B\text{,} where :math:`A` has been factorized by :meth:`zgbtrf`. .. _f07bs-py2-py-doc: For full information please refer to the NAG Library document for f07bs https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07bsf.html .. _f07bs-py2-py-parameters: **Parameters** **trans** : str, length 1 Indicates the form of the equations. :math:`\mathrm{trans} = \texttt{'N'}` :math:`AX = B` is solved for :math:`X`. :math:`\mathrm{trans} = \texttt{'T'}` :math:`A^\mathrm{T}X = B` is solved for :math:`X`. :math:`\mathrm{trans} = \texttt{'C'}` :math:`A^\mathrm{H}X = B` is solved for :math:`X`. **kl** : int :math:`k_l`, the number of subdiagonals within the band of the matrix :math:`A`. **ku** : int :math:`k_u`, the number of superdiagonals within the band of the matrix :math:`A`. **ab** : complex, array-like, shape :math:`\left(2\times \mathrm{kl}+\mathrm{ku}+1, n\right)` The :math:`LU` factorization of :math:`A`, as returned by :meth:`zgbtrf`. **ipiv** : int, array-like, shape :math:`\left(n\right)` The pivot indices, as returned by :meth:`zgbtrf`. **b** : complex, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **b** : complex, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`. .. _f07bs-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{trans}`. Constraint: :math:`\mathrm{trans} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{kl}`. Constraint: :math:`\mathrm{kl}\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\mathrm{ku}`. Constraint: :math:`\mathrm{ku}\geq 0`. (`errno` :math:`-5`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. .. _f07bs-py2-py-notes: **Notes** ``zgbtrs`` is used to solve a complex band system of linear equations :math:`AX = B`, :math:`A^\mathrm{T}X = B` or :math:`A^\mathrm{H}X = B`, the function must be preceded by a call to :meth:`zgbtrf` which computes the :math:`LU` factorization of :math:`A` as :math:`A = PLU`. The solution is computed by forward and backward substitution. If :math:`\mathrm{trans} = \texttt{'N'}`, the solution is computed by solving :math:`PLY = B` and then :math:`UX = Y`. If :math:`\mathrm{trans} = \texttt{'T'}`, the solution is computed by solving :math:`U^\mathrm{T}Y = B` and then :math:`L^\mathrm{T}P^\mathrm{T}X = Y`. If :math:`\mathrm{trans} = \texttt{'C'}`, the solution is computed by solving :math:`U^\mathrm{H}Y = B` and then :math:`L^\mathrm{H}P^\mathrm{T}X = Y`. .. _f07bs-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def zgbequ(m, kl, ku, ab): r""" ``zgbequ`` computes diagonal scaling matrices :math:`D_R` and :math:`D_C` intended to equilibrate a complex :math:`m\times n` band matrix :math:`A` of band width :math:`\left(k_l+k_u+1\right)`, and reduce its condition number. .. _f07bt-py2-py-doc: For full information please refer to the NAG Library document for f07bt https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07btf.html .. _f07bt-py2-py-parameters: **Parameters** **m** : int :math:`m`, the number of rows of the matrix :math:`A`. **kl** : int :math:`k_l`, the number of subdiagonals of the matrix :math:`A`. **ku** : int :math:`k_u`, the number of superdiagonals of the matrix :math:`A`. **ab** : complex, array-like, shape :math:`\left(\mathrm{kl}+\mathrm{ku}+1, n\right)` The :math:`m\times n` band matrix :math:`A` whose scaling factors are to be computed. See `Further Comments <https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07bnf.html#fcomments>`__ for further details. **Returns** **r** : float, ndarray, shape :math:`\left(\mathrm{m}\right)` If no exception or warning is raised or :math:`\mathrm{errno}` > :math:`\mathrm{m}`, :math:`\mathrm{r}` contains the row scale factors, the diagonal elements of :math:`D_R`. The elements of :math:`\mathrm{r}` will be positive. **c** : float, ndarray, shape :math:`\left(n\right)` If no exception or warning is raised, :math:`\mathrm{c}` contains the column scale factors, the diagonal elements of :math:`D_C`. The elements of :math:`\mathrm{c}` will be positive. **rowcnd** : float If no exception or warning is raised or :math:`\mathrm{errno}` > :math:`\mathrm{m}`, :math:`\mathrm{rowcnd}` contains the ratio of the smallest value of :math:`\mathrm{r}[i-1]` to the largest value of :math:`\mathrm{r}[i-1]`. If :math:`\mathrm{rowcnd}\geq 0.1` and :math:`\mathrm{amax}` is neither too large nor too small, it is not worth scaling by :math:`D_R`. **colcnd** : float If no exception or warning is raised, :math:`\mathrm{colcnd}` contains the ratio of the smallest value of :math:`\mathrm{c}[i-1]` to the largest value of :math:`\mathrm{c}[i-1]`. If :math:`\mathrm{colcnd}\geq 0.1`, it is not worth scaling by :math:`D_C`. **amax** : float :math:`\mathrm{max}\left\lvert a_{{ij}}\right\rvert`. If :math:`\mathrm{amax}` is very close to overflow or underflow, the matrix :math:`A` should be scaled. .. _f07bt-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{m}`. Constraint: :math:`\mathrm{m}\geq 0`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{kl}`. Constraint: :math:`\mathrm{kl}\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\mathrm{ku}`. Constraint: :math:`\mathrm{ku}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq \mathrm{m}\right)`) Row :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is exactly zero. (`errno` :math:`i > \mathrm{m}`) Column :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is exactly zero. .. _f07bt-py2-py-notes: **Notes** ``zgbequ`` computes the diagonal scaling matrices. The diagonal scaling matrices are chosen to try to make the elements of largest absolute value in each row and column of the matrix :math:`B` given by .. math:: B = D_RAD_C have absolute value :math:`1`. The diagonal elements of :math:`D_R` and :math:`D_C` are restricted to lie in the safe range :math:`\left(\delta, {1/\delta }\right)`, where :math:`\delta` is the value returned by function :meth:`machine.real_safe <naginterfaces.library.machine.real_safe>`. Use of these scaling factors is not guaranteed to reduce the condition number of :math:`A` but works well in practice. """ raise NotImplementedError
[docs]def zgbcon(norm, kl, ku, ab, ipiv, anorm): r""" ``zgbcon`` estimates the condition number of a complex band matrix :math:`A`, where :math:`A` has been factorized by :meth:`zgbtrf`. .. _f07bu-py2-py-doc: For full information please refer to the NAG Library document for f07bu https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07buf.html .. _f07bu-py2-py-parameters: **Parameters** **norm** : str, length 1 Indicates whether :math:`\kappa_1\left(A\right)` or :math:`\kappa_{\infty }\left(A\right)` is estimated. :math:`\mathrm{norm} = \texttt{'1'}` or :math:`\texttt{'O'}` :math:`\kappa_1\left(A\right)` is estimated. :math:`\mathrm{norm} = \texttt{'I'}` :math:`\kappa_{\infty }\left(A\right)` is estimated. **kl** : int :math:`k_l`, the number of subdiagonals within the band of the matrix :math:`A`. **ku** : int :math:`k_u`, the number of superdiagonals within the band of the matrix :math:`A`. **ab** : complex, array-like, shape :math:`\left(2\times \mathrm{kl}+\mathrm{ku}+1, n\right)` The :math:`LU` factorization of :math:`A`, as returned by :meth:`zgbtrf`. **ipiv** : int, array-like, shape :math:`\left(n\right)` The pivot indices, as returned by :meth:`zgbtrf`. **anorm** : float If :math:`\mathrm{norm} = \texttt{'1'}` or :math:`\texttt{'O'}`, the :math:`1`-norm of the **original** matrix :math:`A`. If :math:`\mathrm{norm} = \texttt{'I'}`, the :math:`\infty`-norm of the **original** matrix :math:`A`. :math:`\mathrm{anorm}` may be computed by calling :meth:`blas.zlangb <naginterfaces.library.blas.zlangb>` with the same value for the argument :math:`\mathrm{norm}`. :math:`\mathrm{anorm}` must be computed either **before** calling :meth:`zgbtrf` or else from a **copy** of the original matrix :math:`A`. **Returns** **rcond** : float An estimate of the reciprocal of the condition number of :math:`A`. :math:`\mathrm{rcond}` is set to zero if exact singularity is detected or the estimate underflows. If :math:`\mathrm{rcond}` is less than machine precision, :math:`A` is singular to working precision. .. _f07bu-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{norm}`. Constraint: :math:`\mathrm{norm} = \texttt{'1'}`, :math:`\texttt{'O'}` or :math:`\texttt{'I'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{kl}`. Constraint: :math:`\mathrm{kl}\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\mathrm{ku}`. Constraint: :math:`\mathrm{ku}\geq 0`. (`errno` :math:`-8`) On entry, error in parameter :math:`\mathrm{anorm}`. Constraint: :math:`\mathrm{anorm}\geq 0.0`. .. _f07bu-py2-py-notes: **Notes** ``zgbcon`` estimates the condition number of a complex band matrix :math:`A`, in either the :math:`1`-norm or the :math:`\infty`-norm: .. math:: \kappa_1\left(A\right) = \left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\quad \text{ or }\quad \kappa_{\infty }\left(A\right) = \left\lVert A\right\rVert_\infty\left\lVert A^{-1}\right\rVert_\infty\text{.} Note that :math:`\kappa_{\infty }\left(A\right) = \kappa_1\left(A^\mathrm{H}\right)`. Because the condition number is infinite if :math:`A` is singular, the function actually returns an estimate of the **reciprocal** of the condition number. The function should be preceded by a call to :meth:`blas.zlangb <naginterfaces.library.blas.zlangb>` to compute :math:`\left\lVert A\right\rVert_1` or :math:`\left\lVert A\right\rVert_\infty`, and a call to :meth:`zgbtrf` to compute the :math:`LU` factorization of :math:`A`. The function then uses Higham's implementation of Hager's method (see Higham (1988)) to estimate :math:`\left\lVert A^{-1}\right\rVert_1` or :math:`\left\lVert A^{-1}\right\rVert_\infty`. .. _f07bu-py2-py-references: **References** Higham, N J, 1988, `FORTRAN codes for estimating the one-norm of a real or complex matrix, with applications to condition estimation`, ACM Trans. Math. Software (14), 381--396 """ raise NotImplementedError
[docs]def zgbrfs(trans, kl, ku, nrhs, ab, afb, ipiv, b, x): r""" ``zgbrfs`` returns error bounds for the solution of a complex band system of linear equations with multiple right-hand sides, :math:`AX = B`, :math:`A^\mathrm{T}X = B` or :math:`A^\mathrm{H}X = B`. It improves the solution by iterative refinement, in order to reduce the backward error as much as possible. .. _f07bv-py2-py-doc: For full information please refer to the NAG Library document for f07bv https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07bvf.html .. _f07bv-py2-py-parameters: **Parameters** **trans** : str, length 1 Indicates the form of the linear equations for which :math:`X` is the computed solution as follows: :math:`\mathrm{trans} = \texttt{'N'}` The linear equations are of the form :math:`AX = B`. :math:`\mathrm{trans} = \texttt{'T'}` The linear equations are of the form :math:`A^\mathrm{T}X = B`. :math:`\mathrm{trans} = \texttt{'C'}` The linear equations are of the form :math:`A^\mathrm{H}X = B`. **kl** : int :math:`k_l`, the number of subdiagonals within the band of the matrix :math:`A`. **ku** : int :math:`k_u`, the number of superdiagonals within the band of the matrix :math:`A`. **nrhs** : int :math:`r`, the number of right-hand sides. **ab** : complex, array-like, shape :math:`\left(\mathrm{kl}+\mathrm{ku}+1, n\right)` The original :math:`n\times n` band matrix :math:`A` as supplied to :meth:`zgbtrf` but with reduced requirements since the matrix is not factorized. See `Further Comments <https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07bnf.html#fcomments>`__ for further details. **afb** : complex, array-like, shape :math:`\left(2\times \mathrm{kl}+\mathrm{ku}+1, n\right)` The :math:`LU` factorization of :math:`A`, as returned by :meth:`zgbtrf`. **ipiv** : int, array-like, shape :math:`\left(n\right)` The pivot indices, as returned by :meth:`zgbtrf`. **b** : complex, array-like, shape :math:`\left(n, \mathrm{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **x** : complex, array-like, shape :math:`\left(n, \mathrm{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`, as returned by :meth:`zgbtrs`. **Returns** **x** : complex, ndarray, shape :math:`\left(n, \mathrm{nrhs}\right)` The improved solution matrix :math:`X`. **ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` :math:`\mathrm{ferr}[\textit{j}-1]` contains an estimated error bound for the :math:`\textit{j}`\ th solution vector, that is, the :math:`\textit{j}`\ th column of :math:`X`, for :math:`\textit{j} = 1,2,\ldots,r`. **berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` :math:`\mathrm{berr}[\textit{j}-1]` contains the component-wise backward error bound :math:`\beta` for the :math:`\textit{j}`\ th solution vector, that is, the :math:`\textit{j}`\ th column of :math:`X`, for :math:`\textit{j} = 1,2,\ldots,r`. .. _f07bv-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{trans}`. Constraint: :math:`\mathrm{trans} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{kl}`. Constraint: :math:`\mathrm{kl}\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\mathrm{ku}`. Constraint: :math:`\mathrm{ku}\geq 0`. (`errno` :math:`-5`) On entry, error in parameter :math:`\mathrm{nrhs}`. Constraint: :math:`\mathrm{nrhs}\geq 0`. .. _f07bv-py2-py-notes: **Notes** ``zgbrfs`` returns the backward errors and estimated bounds on the forward errors for the solution of a complex band system of linear equations with multiple right-hand sides :math:`AX = B`, :math:`A^\mathrm{T}X = B` or :math:`A^\mathrm{H}X = B`. The function handles each right-hand side vector (stored as a column of the matrix :math:`B`) independently, so we describe the function of ``zgbrfs`` in terms of a single right-hand side :math:`b` and solution :math:`x`. Given a computed solution :math:`x`, the function computes the `component-wise` `backward` `error` :math:`\beta`. This is the size of the smallest relative perturbation in each element of :math:`A` and :math:`b` such that :math:`x` is the exact solution of a perturbed system .. math:: \begin{array}{c}\left(A+\delta A\right)x = b+\delta b\\\left\lvert \delta a_{{ij}}\right\rvert \leq \beta \left\lvert a_{{ij}}\right\rvert \quad \text{ and }\quad \left\lvert \delta b_i\right\rvert \leq \beta \left\lvert b_i\right\rvert \text{.} \end{array} Then the function estimates a bound for the `component-wise` `forward` `error` in the computed solution, defined by: .. math:: \mathrm{max}_i\left\lvert x_i-\hat{x}_i\right\rvert /\mathrm{max}_i\left\lvert x_i\right\rvert where :math:`\hat{x}` is the true solution. For details of the method, see `the F07 Introduction <https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07intro.html>`__. .. _f07bv-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def dgtsv(dl, d, du, b): r""" ``dgtsv`` computes the solution to a real system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` tridiagonal matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices. .. _f07ca-py2-py-doc: For full information please refer to the NAG Library document for f07ca https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07caf.html .. _f07ca-py2-py-parameters: **Parameters** **dl** : float, array-like, shape :math:`\left(n-1\right)` Must contain the :math:`\left(n-1\right)` subdiagonal elements of the matrix :math:`A`. **d** : float, array-like, shape :math:`\left(n\right)` Must contain the :math:`n` diagonal elements of the matrix :math:`A`. **du** : float, array-like, shape :math:`\left(n-1\right)` Must contain the :math:`\left(n-1\right)` superdiagonal elements of the matrix :math:`A`. **b** : float, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **dl** : float, ndarray, shape :math:`\left(n-1\right)` If no constraints are violated, :math:`\mathrm{dl}` is overwritten by the (:math:`n-2`) elements of the second superdiagonal of the upper triangular matrix :math:`U` from the :math:`LU` factorization of :math:`A`, in :math:`\mathrm{dl}[0],\mathrm{dl}[1],\ldots,\mathrm{dl}[n-3]`. **d** : float, ndarray, shape :math:`\left(n\right)` If no constraints are violated, :math:`\mathrm{d}` is overwritten by the :math:`n` diagonal elements of the upper triangular matrix :math:`U` from the :math:`LU` factorization of :math:`A`. **du** : float, ndarray, shape :math:`\left(n-1\right)` If no constraints are violated, :math:`\mathrm{du}` is overwritten by the :math:`\left(n-1\right)` elements of the first superdiagonal of :math:`U`. **b** : float, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`. .. _f07ca-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero, and the solution has not been computed. The factorization has not been completed unless :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`. .. _f07ca-py2-py-notes: **Notes** ``dgtsv`` uses Gaussian elimination with partial pivoting and row interchanges to solve the equations :math:`AX = B`. The matrix :math:`A` is factorized as :math:`A = PLU`, where :math:`P` is a permutation matrix, :math:`L` is unit lower triangular with at most one nonzero subdiagonal element per column, and :math:`U` is an upper triangular band matrix, with two superdiagonals. Note that equations :math:`A^\mathrm{T}X = B` may be solved by interchanging the order of the arguments :math:`\mathrm{du}` and :math:`\mathrm{dl}`. .. _f07ca-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug """ raise NotImplementedError
[docs]def dgtsvx(fact, trans, n, nrhs, dl, d, du, dlf, df, duf, du2, ipiv, b): r""" ``dgtsvx`` uses the :math:`LU` factorization to compute the solution to a real system of linear equations .. math:: AX = B\quad \text{ or }\quad A^\mathrm{T}X = B\text{,} where :math:`A` is a tridiagonal matrix of order :math:`n` and :math:`X` and :math:`B` are :math:`n\times r` matrices. Error bounds on the solution and a condition estimate are also provided. .. _f07cb-py2-py-doc: For full information please refer to the NAG Library document for f07cb https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07cbf.html .. _f07cb-py2-py-parameters: **Parameters** **fact** : str, length 1 Specifies whether or not the factorized form of the matrix :math:`A` has been supplied. :math:`\mathrm{fact} = \texttt{'F'}` :math:`\mathrm{dlf}`, :math:`\mathrm{df}`, :math:`\mathrm{duf}`, :math:`\mathrm{du2}` and :math:`\mathrm{ipiv}` contain the factorized form of the matrix :math:`A`. :math:`\mathrm{dlf}`, :math:`\mathrm{df}`, :math:`\mathrm{duf}`, :math:`\mathrm{du2}` and :math:`\mathrm{ipiv}` will not be modified. :math:`\mathrm{fact} = \texttt{'N'}` The matrix :math:`A` will be copied to :math:`\mathrm{dlf}`, :math:`\mathrm{df}` and :math:`\mathrm{duf}` and factorized. **trans** : str, length 1 Specifies the form of the system of equations. :math:`\mathrm{trans} = \texttt{'N'}` :math:`AX = B` (No transpose). :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}` :math:`A^\mathrm{T}X = B` (Transpose). **n** : int :math:`n`, the order of the matrix :math:`A`. **nrhs** : int :math:`r`, the number of right-hand sides, i.e., the number of columns of the matrix :math:`B`. **dl** : float, array-like, shape :math:`\left(\mathrm{n}-1\right)` The :math:`\left(n-1\right)` subdiagonal elements of :math:`A`. **d** : float, array-like, shape :math:`\left(\mathrm{n}\right)` The :math:`n` diagonal elements of :math:`A`. **du** : float, array-like, shape :math:`\left(\mathrm{n}-1\right)` The :math:`\left(n-1\right)` superdiagonal elements of :math:`A`. **dlf** : float, array-like, shape :math:`\left(\mathrm{n}-1\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{dlf}` contains the :math:`\left(n-1\right)` multipliers that define the matrix :math:`L` from the :math:`LU` factorization of :math:`A`. **df** : float, array-like, shape :math:`\left(\mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{df}` contains the :math:`n` diagonal elements of the upper triangular matrix :math:`U` from the :math:`LU` factorization of :math:`A`. **duf** : float, array-like, shape :math:`\left(\mathrm{n}-1\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{duf}` contains the :math:`\left(n-1\right)` elements of the first superdiagonal of :math:`U`. **du2** : float, array-like, shape :math:`\left(\mathrm{n}-2\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{du2}` contains the (:math:`n-2`) elements of the second superdiagonal of :math:`U`. **ipiv** : int, array-like, shape :math:`\left(\mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{ipiv}` contains the pivot indices from the :math:`LU` factorization of :math:`A`. **b** : float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **dlf** : float, ndarray, shape :math:`\left(\mathrm{n}-1\right)` If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{dlf}` contains the :math:`\left(n-1\right)` multipliers that define the matrix :math:`L` from the :math:`LU` factorization of :math:`A`. **df** : float, ndarray, shape :math:`\left(\mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{df}` contains the :math:`n` diagonal elements of the upper triangular matrix :math:`U` from the :math:`LU` factorization of :math:`A`. **duf** : float, ndarray, shape :math:`\left(\mathrm{n}-1\right)` If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{duf}` contains the :math:`\left(n-1\right)` elements of the first superdiagonal of :math:`U`. **du2** : float, ndarray, shape :math:`\left(\mathrm{n}-2\right)` If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{du2}` contains the (:math:`n-2`) elements of the second superdiagonal of :math:`U`. **ipiv** : int, ndarray, shape :math:`\left(\mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{ipiv}` contains the pivot indices from the :math:`LU` factorization of :math:`A`; row :math:`i` of the matrix was interchanged with row :math:`\mathrm{ipiv}[i-1]`. :math:`\mathrm{ipiv}[i-1]` will always be either :math:`i` or :math:`i+1`; :math:`\mathrm{ipiv}[i-1] = i` indicates a row interchange was not required. **x** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, the :math:`n\times r` solution matrix :math:`X`. **rcond** : float The estimate of the reciprocal condition number of the matrix :math:`A`. If :math:`\mathrm{rcond} = 0.0`, the matrix may be exactly singular. This condition is indicated by :math:`\mathrm{errno}` in 1 ... :math:`\mathrm{n}`. Otherwise, if :math:`\mathrm{rcond}` is less than the machine precision, the matrix is singular to working precision. This condition is indicated by :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1. **ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the forward error bound for each computed solution vector, such that :math:`\left\lVert \hat{x}_j-x_j\right\rVert_\infty/\left\lVert x_j\right\rVert_\infty\leq \mathrm{ferr}[j-1]` where :math:`\hat{x}_j` is the :math:`j`\ th column of the computed solution returned in the array :math:`\mathrm{x}` and :math:`x_j` is the corresponding column of the exact solution :math:`X`. The estimate is as reliable as the estimate for :math:`\mathrm{rcond}`, and is almost always a slight overestimate of the true error. **berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the component-wise relative backward error of each computed solution vector :math:`\hat{x}_j` (i.e., the smallest relative change in any element of :math:`A` or :math:`B` that makes :math:`\hat{x}_j` an exact solution). .. _f07cb-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{fact}`. Constraint: :math:`\mathrm{fact} = \texttt{'F'}` or :math:`\texttt{'N'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{trans}`. Constraint: :math:`\mathrm{trans} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\mathrm{nrhs}`. Constraint: :math:`\mathrm{nrhs}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`\left(i > 0\right)\text{ and }\left(i < \mathrm{n}\right)`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has not been completed, but the factor :math:`U` is exactly singular, so the solution and error bounds could not be computed. :math:`\mathrm{rcond} = 0.0` is returned. (`errno` :math:`\left(i > 0\right)\text{ and }(\mathrm{n})`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`U` is exactly singular, so the solution and error bounds could not be computed. :math:`\mathrm{rcond} = 0.0` is returned. (`errno` :math:`\mathrm{n}+1`) :math:`U` is nonsingular, but :math:`\mathrm{rcond}` is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of :math:`\mathrm{rcond}` would suggest. .. _f07cb-py2-py-notes: **Notes** ``dgtsvx`` performs the following steps: (1) If :math:`\mathrm{fact} = \texttt{'N'}`, the :math:`LU` decomposition is used to factor the matrix :math:`A` as :math:`A = LU`, where :math:`L` is a product of permutation and unit lower bidiagonal matrices and :math:`U` is upper triangular with nonzeros in only the main diagonal and first two superdiagonals. (#) If some :math:`u_{{ii}} = 0`, so that :math:`U` is exactly singular, then the function returns with :math:`\textit{errno} = i`. Otherwise, the factored form of :math:`A` is used to estimate the condition number of the matrix :math:`A`. If the reciprocal of the condition number is less than machine precision, :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1 is returned as a warning, but the function still goes on to solve for :math:`X` and compute error bounds as described below. (#) The system of equations is solved for :math:`X` using the factored form of :math:`A`. (#) Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for it. .. _f07cb-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def dgttrf(n, dl, d, du): r""" ``dgttrf`` computes the :math:`LU` factorization of a real :math:`n\times n` tridiagonal matrix :math:`A`. .. _f07cd-py2-py-doc: For full information please refer to the NAG Library document for f07cd https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07cdf.html .. _f07cd-py2-py-parameters: **Parameters** **n** : int :math:`n`, the order of the matrix :math:`A`. **dl** : float, array-like, shape :math:`\left(\mathrm{n}-1\right)` Must contain the :math:`\left(n-1\right)` subdiagonal elements of the matrix :math:`A`. **d** : float, array-like, shape :math:`\left(\mathrm{n}\right)` Must contain the :math:`n` diagonal elements of the matrix :math:`A`. **du** : float, array-like, shape :math:`\left(\mathrm{n}-1\right)` Must contain the :math:`\left(n-1\right)` superdiagonal elements of the matrix :math:`A`. **Returns** **dl** : float, ndarray, shape :math:`\left(\mathrm{n}-1\right)` Is overwritten by the :math:`\left(n-1\right)` multipliers that define the matrix :math:`L` of the :math:`LU` factorization of :math:`A`. **d** : float, ndarray, shape :math:`\left(\mathrm{n}\right)` Is overwritten by the :math:`n` diagonal elements of the upper triangular matrix :math:`U` from the :math:`LU` factorization of :math:`A`. **du** : float, ndarray, shape :math:`\left(\mathrm{n}-1\right)` Is overwritten by the :math:`\left(n-1\right)` elements of the first superdiagonal of :math:`U`. **du2** : float, ndarray, shape :math:`\left(\mathrm{n}-2\right)` Contains the :math:`\left(n-2\right)` elements of the second superdiagonal of :math:`U`. **ipiv** : int, ndarray, shape :math:`\left(\mathrm{n}\right)` Contains the :math:`n` pivot indices that define the permutation matrix :math:`P`. At the :math:`i`\ th step, row :math:`i` of the matrix was interchanged with row :math:`\mathrm{ipiv}[i-1]`. :math:`\mathrm{ipiv}[i-1]` will always be either :math:`i` or :math:`\left(i+1\right)`, :math:`\mathrm{ipiv}[i-1] = i` indicating that a row interchange was not performed. .. _f07cd-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`U` is exactly singular, and division by zero will occur if it is used to solve a system of equations. .. _f07cd-py2-py-notes: **Notes** ``dgttrf`` uses Gaussian elimination with partial pivoting and row interchanges to factorize the matrix :math:`A` as .. math:: A = PLU\text{,} where :math:`P` is a permutation matrix, :math:`L` is unit lower triangular with at most one nonzero subdiagonal element in each column, and :math:`U` is an upper triangular band matrix, with two superdiagonals. .. _f07cd-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug """ raise NotImplementedError
[docs]def dgttrs(trans, dl, d, du, du2, ipiv, b): r""" ``dgttrs`` computes the solution to a real system of linear equations :math:`AX = B` or :math:`A^\mathrm{T}X = B`, where :math:`A` is an :math:`n\times n` tridiagonal matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices, using the :math:`LU` factorization returned by :meth:`dgttrf`. .. _f07ce-py2-py-doc: For full information please refer to the NAG Library document for f07ce https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07cef.html .. _f07ce-py2-py-parameters: **Parameters** **trans** : str, length 1 Specifies the equations to be solved as follows: :math:`\mathrm{trans} = \texttt{'N'}` Solve :math:`AX = B` for :math:`X`. :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}` Solve :math:`A^\mathrm{T}X = B` for :math:`X`. **dl** : float, array-like, shape :math:`\left(n-1\right)` Must contain the :math:`\left(n-1\right)` multipliers that define the matrix :math:`L` of the :math:`LU` factorization of :math:`A`. **d** : float, array-like, shape :math:`\left(n\right)` Must contain the :math:`n` diagonal elements of the upper triangular matrix :math:`U` from the :math:`LU` factorization of :math:`A`. **du** : float, array-like, shape :math:`\left(n-1\right)` Must contain the :math:`\left(n-1\right)` elements of the first superdiagonal of :math:`U`. **du2** : float, array-like, shape :math:`\left(n-2\right)` Must contain the :math:`\left(n-2\right)` elements of the second superdiagonal of :math:`U`. **ipiv** : int, array-like, shape :math:`\left(n\right)` Must contain the :math:`n` pivot indices that define the permutation matrix :math:`P`. At the :math:`i`\ th step, row :math:`i` of the matrix was interchanged with row :math:`\mathrm{ipiv}[i-1]`, and :math:`\mathrm{ipiv}[i-1]` must always be either :math:`i` or :math:`\left(i+1\right)`, :math:`\mathrm{ipiv}[i-1] = i` indicating that a row interchange was not performed. **b** : float, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` matrix of right-hand sides :math:`B`. **Returns** **b** : float, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`. .. _f07ce-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{trans}`. Constraint: :math:`\mathrm{trans} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. .. _f07ce-py2-py-notes: **Notes** ``dgttrs`` should be preceded by a call to :meth:`dgttrf`, which uses Gaussian elimination with partial pivoting and row interchanges to factorize the matrix :math:`A` as .. math:: A = PLU\text{,} where :math:`P` is a permutation matrix, :math:`L` is unit lower triangular with at most one nonzero subdiagonal element in each column, and :math:`U` is an upper triangular band matrix, with two superdiagonals. ``dgttrs`` then utilizes the factorization to solve the required equations. .. _f07ce-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug """ raise NotImplementedError
[docs]def dgtcon(norm, n, dl, d, du, du2, ipiv, anorm): r""" ``dgtcon`` estimates the reciprocal condition number of a real :math:`n\times n` tridiagonal matrix :math:`A`, using the :math:`LU` factorization returned by :meth:`dgttrf`. .. _f07cg-py2-py-doc: For full information please refer to the NAG Library document for f07cg https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07cgf.html .. _f07cg-py2-py-parameters: **Parameters** **norm** : str, length 1 Specifies the norm to be used to estimate :math:`\kappa \left(A\right)`. :math:`\mathrm{norm} = \texttt{'1'}` or :math:`\texttt{'O'}` Estimate :math:`\kappa_1\left(A\right)`. :math:`\mathrm{norm} = \texttt{'I'}` Estimate :math:`\kappa_{\infty }\left(A\right)`. **n** : int :math:`n`, the order of the matrix :math:`A`. **dl** : float, array-like, shape :math:`\left(\mathrm{n}-1\right)` Must contain the :math:`\left(n-1\right)` multipliers that define the matrix :math:`L` of the :math:`LU` factorization of :math:`A`. **d** : float, array-like, shape :math:`\left(\mathrm{n}\right)` Must contain the :math:`n` diagonal elements of the upper triangular matrix :math:`U` from the :math:`LU` factorization of :math:`A`. **du** : float, array-like, shape :math:`\left(\mathrm{n}-1\right)` Must contain the :math:`\left(n-1\right)` elements of the first superdiagonal of :math:`U`. **du2** : float, array-like, shape :math:`\left(\mathrm{n}-2\right)` Must contain the :math:`\left(n-2\right)` elements of the second superdiagonal of :math:`U`. **ipiv** : int, array-like, shape :math:`\left(\mathrm{n}\right)` Must contain the :math:`n` pivot indices that define the permutation matrix :math:`P`. At the :math:`i`\ th step, row :math:`i` of the matrix was interchanged with row :math:`\mathrm{ipiv}[i-1]`, and :math:`\mathrm{ipiv}[i-1]` must always be either :math:`i` or :math:`\left(i+1\right)`, :math:`\mathrm{ipiv}[i-1] = i` indicating that a row interchange was not performed. **anorm** : float If :math:`\mathrm{norm} = \texttt{'1'}` or :math:`\texttt{'O'}`, the :math:`1`-norm of the **original** matrix :math:`A`. If :math:`\mathrm{norm} = \texttt{'I'}`, the :math:`\infty`-norm of the **original** matrix :math:`A`. :math:`\mathrm{anorm}` may be computed by calling :meth:`blas.dlangt <naginterfaces.library.blas.dlangt>` with the same value for the argument :math:`\mathrm{norm}`. :math:`\mathrm{anorm}` must be computed either **before** calling :meth:`dgttrf` or else from a **copy** of the original matrix :math:`A`. **Returns** **rcond** : float Contains an estimate of the reciprocal condition number. .. _f07cg-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{norm}`. Constraint: :math:`\mathrm{norm} = \texttt{'1'}`, :math:`\texttt{'O'}` or :math:`\texttt{'I'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-8`) On entry, error in parameter :math:`\mathrm{anorm}`. Constraint: :math:`\mathrm{anorm}\geq 0.0`. .. _f07cg-py2-py-notes: **Notes** ``dgtcon`` should be preceded by a call to :meth:`dgttrf`, which uses Gaussian elimination with partial pivoting and row interchanges to factorize the matrix :math:`A` as .. math:: A = PLU\text{,} where :math:`P` is a permutation matrix, :math:`L` is unit lower triangular with at most one nonzero subdiagonal element in each column, and :math:`U` is an upper triangular band matrix, with two superdiagonals. ``dgtcon`` then utilizes the factorization to estimate either :math:`\left\lVert A^{-1}\right\rVert_1` or :math:`\left\lVert A^{-1}\right\rVert_\infty`, from which the estimate of the reciprocal of the condition number of :math:`A`, :math:`1/\kappa \left(A\right)` is computed as either .. math:: 1/\kappa_1\left(A\right) = 1/\left(\left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\right) or .. math:: 1/\kappa_{\infty }\left(A\right) = 1/\left(\left\lVert A\right\rVert_\infty\left\lVert A^{-1}\right\rVert_\infty\right)\text{.} :math:`1/\kappa \left(A\right)` is returned, rather than :math:`\kappa \left(A\right)`, since when :math:`A` is singular :math:`\kappa \left(A\right)` is infinite. Note that :math:`\kappa_{\infty }\left(A\right) = \kappa_1\left(A^\mathrm{T}\right)`. .. _f07cg-py2-py-references: **References** Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def dgtrfs(trans, n, nrhs, dl, d, du, dlf, df, duf, du2, ipiv, b, x): r""" ``dgtrfs`` computes error bounds and refines the solution to a real system of linear equations :math:`AX = B` or :math:`A^\mathrm{T}X = B`, where :math:`A` is an :math:`n\times n` tridiagonal matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices, using the :math:`LU` factorization returned by :meth:`dgttrf` and an initial solution returned by :meth:`dgttrs`. Iterative refinement is used to reduce the backward error as much as possible. .. _f07ch-py2-py-doc: For full information please refer to the NAG Library document for f07ch https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07chf.html .. _f07ch-py2-py-parameters: **Parameters** **trans** : str, length 1 Specifies the equations to be solved as follows: :math:`\mathrm{trans} = \texttt{'N'}` Solve :math:`AX = B` for :math:`X`. :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}` Solve :math:`A^\mathrm{T}X = B` for :math:`X`. **n** : int :math:`n`, the order of the matrix :math:`A`. **nrhs** : int :math:`r`, the number of right-hand sides, i.e., the number of columns of the matrix :math:`B`. **dl** : float, array-like, shape :math:`\left(\mathrm{n}-1\right)` Must contain the :math:`\left(n-1\right)` subdiagonal elements of the matrix :math:`A`. **d** : float, array-like, shape :math:`\left(\mathrm{n}\right)` Must contain the :math:`n` diagonal elements of the matrix :math:`A`. **du** : float, array-like, shape :math:`\left(\mathrm{n}-1\right)` Must contain the :math:`\left(n-1\right)` superdiagonal elements of the matrix :math:`A`. **dlf** : float, array-like, shape :math:`\left(\mathrm{n}-1\right)` Must contain the :math:`\left(n-1\right)` multipliers that define the matrix :math:`L` of the :math:`LU` factorization of :math:`A`. **df** : float, array-like, shape :math:`\left(\mathrm{n}\right)` Must contain the :math:`n` diagonal elements of the upper triangular matrix :math:`U` from the :math:`LU` factorization of :math:`A`. **duf** : float, array-like, shape :math:`\left(\mathrm{n}-1\right)` Must contain the :math:`\left(n-1\right)` elements of the first superdiagonal of :math:`U`. **du2** : float, array-like, shape :math:`\left(\mathrm{n}-2\right)` Must contain the :math:`\left(n-2\right)` elements of the second superdiagonal of :math:`U`. **ipiv** : int, array-like, shape :math:`\left(\mathrm{n}\right)` Must contain the :math:`n` pivot indices that define the permutation matrix :math:`P`. At the :math:`i`\ th step, row :math:`i` of the matrix was interchanged with row :math:`\mathrm{ipiv}[i-1]`, and :math:`\mathrm{ipiv}[i-1]` must always be either :math:`i` or :math:`\left(i+1\right)`, :math:`\mathrm{ipiv}[i-1] = i` indicating that a row interchange was not performed. **b** : float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` The :math:`n\times r` matrix of right-hand sides :math:`B`. **x** : float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` The :math:`n\times r` initial solution matrix :math:`X`. **Returns** **x** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` The :math:`n\times r` refined solution matrix :math:`X`. **ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` Estimate of the forward error bound for each computed solution vector, such that :math:`\left\lVert \hat{x}_j-x_j\right\rVert_\infty/\left\lVert \hat{x}_j\right\rVert_\infty\leq \mathrm{ferr}[j-1]`, where :math:`\hat{x}_j` is the :math:`j`\ th column of the computed solution returned in the array :math:`\mathrm{x}` and :math:`x_j` is the corresponding column of the exact solution :math:`X`. The estimate is almost always a slight overestimate of the true error. **berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` Estimate of the component-wise relative backward error of each computed solution vector :math:`\hat{x}_j` (i.e., the smallest relative change in any element of :math:`A` or :math:`B` that makes :math:`\hat{x}_j` an exact solution). .. _f07ch-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{trans}`. Constraint: :math:`\mathrm{trans} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{nrhs}`. Constraint: :math:`\mathrm{nrhs}\geq 0`. .. _f07ch-py2-py-notes: **Notes** ``dgtrfs`` should normally be preceded by calls to :meth:`dgttrf` and :meth:`dgttrs`. :meth:`dgttrf` uses Gaussian elimination with partial pivoting and row interchanges to factorize the matrix :math:`A` as .. math:: A = PLU\text{,} where :math:`P` is a permutation matrix, :math:`L` is unit lower triangular with at most one nonzero subdiagonal element in each column, and :math:`U` is an upper triangular band matrix, with two superdiagonals. :meth:`dgttrs` then utilizes the factorization to compute a solution, :math:`\hat{X}`, to the required equations. Letting :math:`\hat{x}` denote a column of :math:`\hat{X}`, ``dgtrfs`` computes a `component-wise backward error`, :math:`\beta`, the smallest relative perturbation in each element of :math:`A` and :math:`b` such that :math:`\hat{x}` is the exact solution of a perturbed system .. math:: \left(A+E\right)\hat{x} = b+f\text{, with }\quad \left\lvert e_{{ij}}\right\rvert \leq \beta \left\lvert a_{{ij}}\right\rvert \text{, and }\quad \left\lvert f_j\right\rvert \leq \beta \left\lvert b_j\right\rvert \text{.} The function also estimates a bound for the `component-wise forward error` in the computed solution defined by :math:`\mathrm{max}\left\lvert x_i-\hat{x_i}\right\rvert /\mathrm{max}\left\lvert \hat{x_i}\right\rvert`, where :math:`x` is the corresponding column of the exact solution, :math:`X`. .. _f07ch-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug """ raise NotImplementedError
[docs]def zgtsv(dl, d, du, b): r""" ``zgtsv`` computes the solution to a complex system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` tridiagonal matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices. .. _f07cn-py2-py-doc: For full information please refer to the NAG Library document for f07cn https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07cnf.html .. _f07cn-py2-py-parameters: **Parameters** **dl** : complex, array-like, shape :math:`\left(n-1\right)` Must contain the :math:`\left(n-1\right)` subdiagonal elements of the matrix :math:`A`. **d** : complex, array-like, shape :math:`\left(n\right)` Must contain the :math:`n` diagonal elements of the matrix :math:`A`. **du** : complex, array-like, shape :math:`\left(n-1\right)` Must contain the :math:`\left(n-1\right)` superdiagonal elements of the matrix :math:`A`. **b** : complex, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **dl** : complex, ndarray, shape :math:`\left(n-1\right)` If no constraints are violated, :math:`\mathrm{dl}` is overwritten by the (:math:`n-2`) elements of the second superdiagonal of the upper triangular matrix :math:`U` from the :math:`LU` factorization of :math:`A`, in :math:`\mathrm{dl}[0],\mathrm{dl}[1],\ldots,\mathrm{dl}[n-3]`. **d** : complex, ndarray, shape :math:`\left(n\right)` If no constraints are violated, :math:`\mathrm{d}` is overwritten by the :math:`n` diagonal elements of the upper triangular matrix :math:`U` from the :math:`LU` factorization of :math:`A`. **du** : complex, ndarray, shape :math:`\left(n-1\right)` If no constraints are violated, :math:`\mathrm{du}` is overwritten by the :math:`\left(n-1\right)` elements of the first superdiagonal of :math:`U`. **b** : complex, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`. .. _f07cn-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero, and the solution has not been computed. The factorization has not been completed unless :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`. .. _f07cn-py2-py-notes: **Notes** ``zgtsv`` uses Gaussian elimination with partial pivoting and row interchanges to solve the equations :math:`AX = B`. The matrix :math:`A` is factorized as :math:`A = PLU`, where :math:`P` is a permutation matrix, :math:`L` is unit lower triangular with at most one nonzero subdiagonal element per column, and :math:`U` is an upper triangular band matrix, with two superdiagonals. Note that the equations :math:`A^\mathrm{T}X = B` may be solved by interchanging the order of the arguments :math:`\mathrm{du}` and :math:`\mathrm{dl}`. .. _f07cn-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug """ raise NotImplementedError
[docs]def zgtsvx(fact, trans, n, nrhs, dl, d, du, dlf, df, duf, du2, ipiv, b): r""" ``zgtsvx`` uses the :math:`LU` factorization to compute the solution to a complex system of linear equations .. math:: AX = B\text{, }\quad A^\mathrm{T}X = B\quad \text{ or }\quad A^\mathrm{H}X = B\text{,} where :math:`A` is a tridiagonal matrix of order :math:`n` and :math:`X` and :math:`B` are :math:`n\times r` matrices. Error bounds on the solution and a condition estimate are also provided. .. _f07cp-py2-py-doc: For full information please refer to the NAG Library document for f07cp https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07cpf.html .. _f07cp-py2-py-parameters: **Parameters** **fact** : str, length 1 Specifies whether or not the factorized form of the matrix :math:`A` has been supplied. :math:`\mathrm{fact} = \texttt{'F'}` :math:`\mathrm{dlf}`, :math:`\mathrm{df}`, :math:`\mathrm{duf}`, :math:`\mathrm{du2}` and :math:`\mathrm{ipiv}` contain the factorized form of the matrix :math:`A`. :math:`\mathrm{dlf}`, :math:`\mathrm{df}`, :math:`\mathrm{duf}`, :math:`\mathrm{du2}` and :math:`\mathrm{ipiv}` will not be modified. :math:`\mathrm{fact} = \texttt{'N'}` The matrix :math:`A` will be copied to :math:`\mathrm{dlf}`, :math:`\mathrm{df}` and :math:`\mathrm{duf}` and factorized. **trans** : str, length 1 Specifies the form of the system of equations. :math:`\mathrm{trans} = \texttt{'N'}` :math:`AX = B` (No transpose). :math:`\mathrm{trans} = \texttt{'T'}` :math:`A^\mathrm{T}X = B` (Transpose). :math:`\mathrm{trans} = \texttt{'C'}` :math:`A^\mathrm{H}X = B` (Conjugate transpose). **n** : int :math:`n`, the order of the matrix :math:`A`. **nrhs** : int :math:`r`, the number of right-hand sides, i.e., the number of columns of the matrix :math:`B`. **dl** : complex, array-like, shape :math:`\left(\mathrm{n}-1\right)` The :math:`\left(n-1\right)` subdiagonal elements of :math:`A`. **d** : complex, array-like, shape :math:`\left(\mathrm{n}\right)` The :math:`n` diagonal elements of :math:`A`. **du** : complex, array-like, shape :math:`\left(\mathrm{n}-1\right)` The :math:`\left(n-1\right)` superdiagonal elements of :math:`A`. **dlf** : complex, array-like, shape :math:`\left(\mathrm{n}-1\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{dlf}` contains the :math:`\left(n-1\right)` multipliers that define the matrix :math:`L` from the :math:`LU` factorization of :math:`A`. **df** : complex, array-like, shape :math:`\left(\mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{df}` contains the :math:`n` diagonal elements of the upper triangular matrix :math:`U` from the :math:`LU` factorization of :math:`A`. **duf** : complex, array-like, shape :math:`\left(\mathrm{n}-1\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{duf}` contains the :math:`\left(n-1\right)` elements of the first superdiagonal of :math:`U`. **du2** : complex, array-like, shape :math:`\left(\mathrm{n}-2\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{du2}` contains the (:math:`n-2`) elements of the second superdiagonal of :math:`U`. **ipiv** : int, array-like, shape :math:`\left(\mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{ipiv}` contains the pivot indices from the :math:`LU` factorization of :math:`A`. **b** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **dlf** : complex, ndarray, shape :math:`\left(\mathrm{n}-1\right)` If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{dlf}` contains the :math:`\left(n-1\right)` multipliers that define the matrix :math:`L` from the :math:`LU` factorization of :math:`A`. **df** : complex, ndarray, shape :math:`\left(\mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{df}` contains the :math:`n` diagonal elements of the upper triangular matrix :math:`U` from the :math:`LU` factorization of :math:`A`. **duf** : complex, ndarray, shape :math:`\left(\mathrm{n}-1\right)` If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{duf}` contains the :math:`\left(n-1\right)` elements of the first superdiagonal of :math:`U`. **du2** : complex, ndarray, shape :math:`\left(\mathrm{n}-2\right)` If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{du2}` contains the (:math:`n-2`) elements of the second superdiagonal of :math:`U`. **ipiv** : int, ndarray, shape :math:`\left(\mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{ipiv}` contains the pivot indices from the :math:`LU` factorization of :math:`A`; row :math:`i` of the matrix was interchanged with row :math:`\mathrm{ipiv}[i-1]`. :math:`\mathrm{ipiv}[i-1]` will always be either :math:`i` or :math:`i+1`; :math:`\mathrm{ipiv}[i-1] = i` indicates a row interchange was not required. **x** : complex, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, the :math:`n\times r` solution matrix :math:`X`. **rcond** : float The estimate of the reciprocal condition number of the matrix :math:`A`. If :math:`\mathrm{rcond} = 0.0`, the matrix may be exactly singular. This condition is indicated by :math:`\mathrm{errno}` in 1 ... :math:`\mathrm{n}`. Otherwise, if :math:`\mathrm{rcond}` is less than the machine precision, the matrix is singular to working precision. This condition is indicated by :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1. **ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the forward error bound for each computed solution vector, such that :math:`\left\lVert \hat{x}_j-x_j\right\rVert_\infty/\left\lVert x_j\right\rVert_\infty\leq \mathrm{ferr}[j-1]` where :math:`\hat{x}_j` is the :math:`j`\ th column of the computed solution returned in the array :math:`\mathrm{x}` and :math:`x_j` is the corresponding column of the exact solution :math:`X`. The estimate is as reliable as the estimate for :math:`\mathrm{rcond}`, and is almost always a slight overestimate of the true error. **berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the component-wise relative backward error of each computed solution vector :math:`\hat{x}_j` (i.e., the smallest relative change in any element of :math:`A` or :math:`B` that makes :math:`\hat{x}_j` an exact solution). .. _f07cp-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{fact}`. Constraint: :math:`\mathrm{fact} = \texttt{'F'}` or :math:`\texttt{'N'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{trans}`. Constraint: :math:`\mathrm{trans} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\mathrm{nrhs}`. Constraint: :math:`\mathrm{nrhs}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`\left(i > 0\right)\text{ and }\left(i < \mathrm{n}\right)`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has not been completed, but the factor :math:`U` is exactly singular, so the solution and error bounds could not be computed. :math:`\mathrm{rcond} = 0.0` is returned. (`errno` :math:`\left(i > 0\right)\text{ and }(\mathrm{n})`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`U` is exactly singular, so the solution and error bounds could not be computed. :math:`\mathrm{rcond} = 0.0` is returned. (`errno` :math:`\mathrm{n}+1`) :math:`U` is nonsingular, but :math:`\mathrm{rcond}` is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of :math:`\mathrm{rcond}` would suggest. .. _f07cp-py2-py-notes: **Notes** ``zgtsvx`` performs the following steps: (1) If :math:`\mathrm{fact} = \texttt{'N'}`, the :math:`LU` decomposition is used to factor the matrix :math:`A` as :math:`A = LU`, where :math:`L` is a product of permutation and unit lower bidiagonal matrices and :math:`U` is upper triangular with nonzeros in only the main diagonal and first two superdiagonals. (#) If some :math:`u_{{ii}} = 0`, so that :math:`U` is exactly singular, then the function returns with :math:`\textit{errno} = i`. Otherwise, the factored form of :math:`A` is used to estimate the condition number of the matrix :math:`A`. If the reciprocal of the condition number is less than machine precision, :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1 is returned as a warning, but the function still goes on to solve for :math:`X` and compute error bounds as described below. (#) The system of equations is solved for :math:`X` using the factored form of :math:`A`. (#) Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for it. .. _f07cp-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def zgttrf(n, dl, d, du): r""" ``zgttrf`` computes the :math:`LU` factorization of a complex :math:`n\times n` tridiagonal matrix :math:`A`. .. _f07cr-py2-py-doc: For full information please refer to the NAG Library document for f07cr https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07crf.html .. _f07cr-py2-py-parameters: **Parameters** **n** : int :math:`n`, the order of the matrix :math:`A`. **dl** : complex, array-like, shape :math:`\left(\mathrm{n}-1\right)` Must contain the :math:`\left(n-1\right)` subdiagonal elements of the matrix :math:`A`. **d** : complex, array-like, shape :math:`\left(\mathrm{n}\right)` Must contain the :math:`n` diagonal elements of the matrix :math:`A`. **du** : complex, array-like, shape :math:`\left(\mathrm{n}-1\right)` Must contain the :math:`\left(n-1\right)` superdiagonal elements of the matrix :math:`A`. **Returns** **dl** : complex, ndarray, shape :math:`\left(\mathrm{n}-1\right)` Is overwritten by the :math:`\left(n-1\right)` multipliers that define the matrix :math:`L` of the :math:`LU` factorization of :math:`A`. **d** : complex, ndarray, shape :math:`\left(\mathrm{n}\right)` Is overwritten by the :math:`n` diagonal elements of the upper triangular matrix :math:`U` from the :math:`LU` factorization of :math:`A`. **du** : complex, ndarray, shape :math:`\left(\mathrm{n}-1\right)` Is overwritten by the :math:`\left(n-1\right)` elements of the first superdiagonal of :math:`U`. **du2** : complex, ndarray, shape :math:`\left(\mathrm{n}-2\right)` Contains the :math:`\left(n-2\right)` elements of the second superdiagonal of :math:`U`. **ipiv** : int, ndarray, shape :math:`\left(\mathrm{n}\right)` Contains the :math:`n` pivot indices that define the permutation matrix :math:`P`. At the :math:`i`\ th step, row :math:`i` of the matrix was interchanged with row :math:`\mathrm{ipiv}[i-1]`. :math:`\mathrm{ipiv}[i-1]` will always be either :math:`i` or :math:`\left(i+1\right)`, :math:`\mathrm{ipiv}[i-1] = i` indicating that a row interchange was not performed. .. _f07cr-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`U` is exactly singular, and division by zero will occur if it is used to solve a system of equations. .. _f07cr-py2-py-notes: **Notes** ``zgttrf`` uses Gaussian elimination with partial pivoting and row interchanges to factorize the matrix :math:`A` as .. math:: A = PLU\text{,} where :math:`P` is a permutation matrix, :math:`L` is unit lower triangular with at most one nonzero subdiagonal element in each column, and :math:`U` is an upper triangular band matrix, with two superdiagonals. .. _f07cr-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug """ raise NotImplementedError
[docs]def zgttrs(trans, dl, d, du, du2, ipiv, b): r""" ``zgttrs`` computes the solution to a complex system of linear equations :math:`AX = B` or :math:`A^\mathrm{T}X = B` or :math:`A^\mathrm{H}X = B`, where :math:`A` is an :math:`n\times n` tridiagonal matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices, using the :math:`LU` factorization returned by :meth:`zgttrf`. .. _f07cs-py2-py-doc: For full information please refer to the NAG Library document for f07cs https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07csf.html .. _f07cs-py2-py-parameters: **Parameters** **trans** : str, length 1 Specifies the equations to be solved as follows: :math:`\mathrm{trans} = \texttt{'N'}` Solve :math:`AX = B` for :math:`X`. :math:`\mathrm{trans} = \texttt{'T'}` Solve :math:`A^\mathrm{T}X = B` for :math:`X`. :math:`\mathrm{trans} = \texttt{'C'}` Solve :math:`A^\mathrm{H}X = B` for :math:`X`. **dl** : complex, array-like, shape :math:`\left(n-1\right)` Must contain the :math:`\left(n-1\right)` multipliers that define the matrix :math:`L` of the :math:`LU` factorization of :math:`A`. **d** : complex, array-like, shape :math:`\left(n\right)` Must contain the :math:`n` diagonal elements of the upper triangular matrix :math:`U` from the :math:`LU` factorization of :math:`A`. **du** : complex, array-like, shape :math:`\left(n-1\right)` Must contain the :math:`\left(n-1\right)` elements of the first superdiagonal of :math:`U`. **du2** : complex, array-like, shape :math:`\left(n-2\right)` Must contain the :math:`\left(n-2\right)` elements of the second superdiagonal of :math:`U`. **ipiv** : int, array-like, shape :math:`\left(n\right)` Must contain the :math:`n` pivot indices that define the permutation matrix :math:`P`. At the :math:`i`\ th step, row :math:`i` of the matrix was interchanged with row :math:`\mathrm{ipiv}[i-1]`, and :math:`\mathrm{ipiv}[i-1]` must always be either :math:`i` or :math:`\left(i+1\right)`, :math:`\mathrm{ipiv}[i-1] = i` indicating that a row interchange was not performed. **b** : complex, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` matrix of right-hand sides :math:`B`. **Returns** **b** : complex, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`. .. _f07cs-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{trans}`. Constraint: :math:`\mathrm{trans} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. .. _f07cs-py2-py-notes: **Notes** ``zgttrs`` should be preceded by a call to :meth:`zgttrf`, which uses Gaussian elimination with partial pivoting and row interchanges to factorize the matrix :math:`A` as .. math:: A = PLU\text{,} where :math:`P` is a permutation matrix, :math:`L` is unit lower triangular with at most one nonzero subdiagonal element in each column, and :math:`U` is an upper triangular band matrix, with two superdiagonals. ``zgttrs`` then utilizes the factorization to solve the required equations. .. _f07cs-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def zgtcon(norm, dl, d, du, du2, ipiv, anorm): r""" ``zgtcon`` estimates the reciprocal condition number of a complex :math:`n\times n` tridiagonal matrix :math:`A`, using the :math:`LU` factorization returned by :meth:`zgttrf`. .. _f07cu-py2-py-doc: For full information please refer to the NAG Library document for f07cu https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07cuf.html .. _f07cu-py2-py-parameters: **Parameters** **norm** : str, length 1 Specifies the norm to be used to estimate :math:`\kappa \left(A\right)`. :math:`\mathrm{norm} = \texttt{'1'}` or :math:`\texttt{'O'}` Estimate :math:`\kappa_1\left(A\right)`. :math:`\mathrm{norm} = \texttt{'I'}` Estimate :math:`\kappa_{\infty }\left(A\right)`. **dl** : complex, array-like, shape :math:`\left(n-1\right)` Must contain the :math:`\left(n-1\right)` multipliers that define the matrix :math:`L` of the :math:`LU` factorization of :math:`A`. **d** : complex, array-like, shape :math:`\left(n\right)` Must contain the :math:`n` diagonal elements of the upper triangular matrix :math:`U` from the :math:`LU` factorization of :math:`A`. **du** : complex, array-like, shape :math:`\left(n-1\right)` Must contain the :math:`\left(n-1\right)` elements of the first superdiagonal of :math:`U`. **du2** : complex, array-like, shape :math:`\left(n-2\right)` Must contain the :math:`\left(n-2\right)` elements of the second superdiagonal of :math:`U`. **ipiv** : int, array-like, shape :math:`\left(n\right)` Must contain the :math:`n` pivot indices that define the permutation matrix :math:`P`. At the :math:`i`\ th step, row :math:`i` of the matrix was interchanged with row :math:`\mathrm{ipiv}[i-1]`, and :math:`\mathrm{ipiv}[i-1]` must always be either :math:`i` or :math:`\left(i+1\right)`, :math:`\mathrm{ipiv}[i-1] = i` indicating that a row interchange was not performed. **anorm** : float If :math:`\mathrm{norm} = \texttt{'1'}` or :math:`\texttt{'O'}`, the :math:`1`-norm of the **original** matrix :math:`A`. If :math:`\mathrm{norm} = \texttt{'I'}`, the :math:`\infty`-norm of the **original** matrix :math:`A`. :math:`\mathrm{anorm}` may be computed by calling :meth:`blas.zlangt <naginterfaces.library.blas.zlangt>` with the same value for the argument :math:`\mathrm{norm}`. :math:`\mathrm{anorm}` must be computed either **before** calling :meth:`zgttrf` or else from a **copy** of the original matrix :math:`A`. **Returns** **rcond** : float Contains an estimate of the reciprocal condition number. .. _f07cu-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{norm}`. Constraint: :math:`\mathrm{norm} = \texttt{'1'}`, :math:`\texttt{'O'}` or :math:`\texttt{'I'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-8`) On entry, error in parameter :math:`\mathrm{anorm}`. Constraint: :math:`\mathrm{anorm}\geq 0.0`. .. _f07cu-py2-py-notes: **Notes** ``zgtcon`` should be preceded by a call to :meth:`zgttrf`, which uses Gaussian elimination with partial pivoting and row interchanges to factorize the matrix :math:`A` as .. math:: A = PLU\text{,} where :math:`P` is a permutation matrix, :math:`L` is unit lower triangular with at most one nonzero subdiagonal element in each column, and :math:`U` is an upper triangular band matrix, with two superdiagonals. ``zgtcon`` then utilizes the factorization to estimate either :math:`\left\lVert A^{-1}\right\rVert_1` or :math:`\left\lVert A^{-1}\right\rVert_\infty`, from which the estimate of the reciprocal of the condition number of :math:`A`, :math:`1/\kappa \left(A\right)` is computed as either .. math:: 1/\kappa_1\left(A\right) = 1/\left(\left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\right) or .. math:: 1/\kappa_{\infty }\left(A\right) = 1/\left(\left\lVert A\right\rVert_\infty\left\lVert A^{-1}\right\rVert_\infty\right)\text{.} :math:`1/\kappa \left(A\right)` is returned, rather than :math:`\kappa \left(A\right)`, since when :math:`A` is singular :math:`\kappa \left(A\right)` is infinite. Note that :math:`\kappa_{\infty }\left(A\right) = \kappa_1\left(A^\mathrm{T}\right)`. .. _f07cu-py2-py-references: **References** Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def zgtrfs(trans, n, nrhs, dl, d, du, dlf, df, duf, du2, ipiv, b, x): r""" ``zgtrfs`` computes error bounds and refines the solution to a complex system of linear equations :math:`AX = B` or :math:`A^\mathrm{T}X = B` or :math:`A^\mathrm{H}X = B`, where :math:`A` is an :math:`n\times n` tridiagonal matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices, using the :math:`LU` factorization returned by :meth:`zgttrf` and an initial solution returned by :meth:`zgttrs`. Iterative refinement is used to reduce the backward error as much as possible. .. _f07cv-py2-py-doc: For full information please refer to the NAG Library document for f07cv https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07cvf.html .. _f07cv-py2-py-parameters: **Parameters** **trans** : str, length 1 Specifies the equations to be solved as follows: :math:`\mathrm{trans} = \texttt{'N'}` Solve :math:`AX = B` for :math:`X`. :math:`\mathrm{trans} = \texttt{'T'}` Solve :math:`A^\mathrm{T}X = B` for :math:`X`. :math:`\mathrm{trans} = \texttt{'C'}` Solve :math:`A^\mathrm{H}X = B` for :math:`X`. **n** : int :math:`n`, the order of the matrix :math:`A`. **nrhs** : int :math:`r`, the number of right-hand sides, i.e., the number of columns of the matrix :math:`B`. **dl** : complex, array-like, shape :math:`\left(\mathrm{n}-1\right)` Must contain the :math:`\left(n-1\right)` subdiagonal elements of the matrix :math:`A`. **d** : complex, array-like, shape :math:`\left(\mathrm{n}\right)` Must contain the :math:`n` diagonal elements of the matrix :math:`A`. **du** : complex, array-like, shape :math:`\left(\mathrm{n}-1\right)` Must contain the :math:`\left(n-1\right)` superdiagonal elements of the matrix :math:`A`. **dlf** : complex, array-like, shape :math:`\left(\mathrm{n}-1\right)` Must contain the :math:`\left(n-1\right)` multipliers that define the matrix :math:`L` of the :math:`LU` factorization of :math:`A`. **df** : complex, array-like, shape :math:`\left(\mathrm{n}\right)` Must contain the :math:`n` diagonal elements of the upper triangular matrix :math:`U` from the :math:`LU` factorization of :math:`A`. **duf** : complex, array-like, shape :math:`\left(\mathrm{n}-1\right)` Must contain the :math:`\left(n-1\right)` elements of the first superdiagonal of :math:`U`. **du2** : complex, array-like, shape :math:`\left(\mathrm{n}-2\right)` Must contain the :math:`\left(n-2\right)` elements of the second superdiagonal of :math:`U`. **ipiv** : int, array-like, shape :math:`\left(\mathrm{n}\right)` Must contain the :math:`n` pivot indices that define the permutation matrix :math:`P`. At the :math:`i`\ th step, row :math:`i` of the matrix was interchanged with row :math:`\mathrm{ipiv}[i-1]`, and :math:`\mathrm{ipiv}[i-1]` must always be either :math:`i` or :math:`\left(i+1\right)`, :math:`\mathrm{ipiv}[i-1] = i` indicating that a row interchange was not performed. **b** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` The :math:`n\times r` matrix of right-hand sides :math:`B`. **x** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` The :math:`n\times r` initial solution matrix :math:`X`. **Returns** **x** : complex, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` The :math:`n\times r` refined solution matrix :math:`X`. **ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` Estimate of the forward error bound for each computed solution vector, such that :math:`\left\lVert \hat{x}_j-x_j\right\rVert_\infty/\left\lVert \hat{x}_j\right\rVert_\infty\leq \mathrm{ferr}[j-1]`, where :math:`\hat{x}_j` is the :math:`j`\ th column of the computed solution returned in the array :math:`\mathrm{x}` and :math:`x_j` is the corresponding column of the exact solution :math:`X`. The estimate is almost always a slight overestimate of the true error. **berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` Estimate of the component-wise relative backward error of each computed solution vector :math:`\hat{x}_j` (i.e., the smallest relative change in any element of :math:`A` or :math:`B` that makes :math:`\hat{x}_j` an exact solution). .. _f07cv-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{trans}`. Constraint: :math:`\mathrm{trans} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{nrhs}`. Constraint: :math:`\mathrm{nrhs}\geq 0`. .. _f07cv-py2-py-notes: **Notes** ``zgtrfs`` should normally be preceded by calls to :meth:`zgttrf` and :meth:`zgttrs`. :meth:`zgttrf` uses Gaussian elimination with partial pivoting and row interchanges to factorize the matrix :math:`A` as .. math:: A = PLU\text{,} where :math:`P` is a permutation matrix, :math:`L` is unit lower triangular with at most one nonzero subdiagonal element in each column, and :math:`U` is an upper triangular band matrix, with two superdiagonals. :meth:`zgttrs` then utilizes the factorization to compute a solution, :math:`\hat{X}`, to the required equations. Letting :math:`\hat{x}` denote a column of :math:`\hat{X}`, ``zgtrfs`` computes a `component-wise backward error`, :math:`\beta`, the smallest relative perturbation in each element of :math:`A` and :math:`b` such that :math:`\hat{x}` is the exact solution of a perturbed system .. math:: \left(A+E\right)\hat{x} = b+f\text{, with }\quad \left\lvert e_{{ij}}\right\rvert \leq \beta \left\lvert a_{{ij}}\right\rvert \text{, and }\quad \left\lvert f_j\right\rvert \leq \beta \left\lvert b_j\right\rvert \text{.} The function also estimates a bound for the `component-wise forward error` in the computed solution defined by :math:`\mathrm{max}\left\lvert x_i-\hat{x_i}\right\rvert /\mathrm{max}\left\lvert \hat{x_i}\right\rvert`, where :math:`x` is the corresponding column of the exact solution, :math:`X`. .. _f07cv-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug """ raise NotImplementedError
[docs]def dposv(uplo, a, b): r""" ``dposv`` computes the solution to a real system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` symmetric positive definite matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices. .. _f07fa-py2-py-doc: For full information please refer to the NAG Library document for f07fa https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07faf.html .. _f07fa-py2-py-parameters: **Parameters** **uplo** : str, length 1 If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored. If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored. **a** : float, array-like, shape :math:`\left(n, n\right)` The :math:`n\times n` symmetric matrix :math:`A`. **b** : float, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **a** : float, ndarray, shape :math:`\left(n, n\right)` If no exception or warning is raised, the factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{T}U` or :math:`A = LL^\mathrm{T}`. **b** : float, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`. .. _f07fa-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. (`errno` :math:`i > 0`) The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is not positive definite, so the factorization could not be completed, and the solution has not been computed. .. _f07fa-py2-py-notes: **Notes** ``dposv`` uses the Cholesky decomposition to factor :math:`A` as :math:`A = U^\mathrm{T}U` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LL^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` is an upper triangular matrix and :math:`L` is a lower triangular matrix. The factored form of :math:`A` is then used to solve the system of equations :math:`AX = B`. .. _f07fa-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def dposvx(fact, uplo, n, nrhs, a, af, equed, s, b): r""" ``dposvx`` uses the Cholesky factorization .. math:: A = U^\mathrm{T}U\quad \text{ or }\quad A = LL^\mathrm{T} to compute the solution to a real system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` symmetric positive definite matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices. Error bounds on the solution and a condition estimate are also provided. .. _f07fb-py2-py-doc: For full information please refer to the NAG Library document for f07fb https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07fbf.html .. _f07fb-py2-py-parameters: **Parameters** **fact** : str, length 1 Specifies whether or not the factorized form of the matrix :math:`A` is supplied on entry, and if not, whether the matrix :math:`A` should be equilibrated before it is factorized. :math:`\mathrm{fact} = \texttt{'F'}` :math:`\mathrm{af}` contains the factorized form of :math:`A`. If :math:`\mathrm{equed} = \texttt{'Y'}`, the matrix :math:`A` has been equilibrated with scaling factors given by :math:`\mathrm{s}`. :math:`\mathrm{a}` and :math:`\mathrm{af}` will not be modified. :math:`\mathrm{fact} = \texttt{'N'}` The matrix :math:`A` will be copied to :math:`\mathrm{af}` and factorized. :math:`\mathrm{fact} = \texttt{'E'}` The matrix :math:`A` will be equilibrated if necessary, then copied to :math:`\mathrm{af}` and factorized. **uplo** : str, length 1 If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored. If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored. **n** : int :math:`n`, the number of linear equations, i.e., the order of the matrix :math:`A`. **nrhs** : int :math:`r`, the number of right-hand sides, i.e., the number of columns of the matrix :math:`B`. **a** : float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` The :math:`n\times n` symmetric matrix :math:`A`. If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{a}` must have been equilibrated by the scaling factor in :math:`\mathrm{s}` as :math:`D_SAD_S`. **af** : float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{af}` contains the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{T}U` or :math:`A = LL^\mathrm{T}`, in the same storage format as :math:`\mathrm{a}`. If :math:`\mathrm{equed} \neq \texttt{'N'}`, :math:`\mathrm{af}` is the factorized form of the equilibrated matrix :math:`D_SAD_S`. **equed** : str, length 1 If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{equed}` need not be set. If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` must specify the form of the equilibration that was performed as follows: if :math:`\mathrm{equed} = \texttt{'N'}`, no equilibration; if :math:`\mathrm{equed} = \texttt{'Y'}`, equilibration was performed, i.e., :math:`A` has been replaced by :math:`D_SAD_S`. **s** : float, array-like, shape :math:`\left(\mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{s}` need not be set. If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{s}` must contain the scale factors, :math:`D_S`, for :math:`A`; each element of :math:`\mathrm{s}` must be positive. **b** : float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **a** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'F'}` or :math:`\texttt{'N'}`, or if :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{a}` is not modified. If :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{a}` is overwritten by :math:`D_SAD_S`. **af** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{af}` returns the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{T}U` or :math:`A = LL^\mathrm{T}` of the original matrix :math:`A`. If :math:`\mathrm{fact} = \texttt{'E'}`, :math:`\mathrm{af}` returns the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{T}U` or :math:`A = LL^\mathrm{T}` of the equilibrated matrix :math:`A` (see the description of :math:`\mathrm{a}` for the form of the equilibrated matrix). **equed** : str, length 1 If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` is unchanged from entry. Otherwise, if no constraints are violated, :math:`\mathrm{equed}` specifies the form of the equilibration that was performed as specified above. **s** : float, ndarray, shape :math:`\left(\mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{s}` is unchanged from entry. Otherwise, if no constraints are violated and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{s}` contains the scale factors, :math:`D_S`, for :math:`A`; each element of :math:`\mathrm{s}` is positive. **b** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` If :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{b}` is not modified. If :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{b}` is overwritten by :math:`D_SB`. **x** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, the :math:`n\times r` solution matrix :math:`X` to the original system of equations. Note that the arrays :math:`A` and :math:`B` are modified on exit if :math:`\mathrm{equed} = \texttt{'Y'}`, and the solution to the equilibrated system is :math:`D_S^{-1}X`. **rcond** : float If no constraints are violated, an estimate of the reciprocal condition number of the matrix :math:`A` (after equilibration if that is performed), computed as :math:`\mathrm{rcond} = 1.0/\left(\left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\right)`. **ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the forward error bound for each computed solution vector, such that :math:`\left\lVert \hat{x}_j-x_j\right\rVert_\infty/\left\lVert x_j\right\rVert_\infty\leq \mathrm{ferr}[j-1]` where :math:`\hat{x}_j` is the :math:`j`\ th column of the computed solution returned in the array :math:`\mathrm{x}` and :math:`x_j` is the corresponding column of the exact solution :math:`X`. The estimate is as reliable as the estimate for :math:`\mathrm{rcond}`, and is almost always a slight overestimate of the true error. **berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the component-wise relative backward error of each computed solution vector :math:`\hat{x}_j` (i.e., the smallest relative change in any element of :math:`A` or :math:`B` that makes :math:`\hat{x}_j` an exact solution). .. _f07fb-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{fact}`. Constraint: :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\texttt{'N'}` or :math:`\texttt{'E'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\mathrm{nrhs}`. Constraint: :math:`\mathrm{nrhs}\geq 0`. (`errno` :math:`-9`) On entry, error in parameter :math:`\mathrm{equed}`. Constraint: :math:`\mathrm{equed} = \texttt{'N'}` or :math:`\texttt{'Y'}`. (`errno` :math:`-10`) On entry, error in parameter :math:`\mathrm{s}`. (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq \mathrm{n}\right)`) The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is not positive definite, so the factorization could not be completed, and the solution has not been computed. :math:`\mathrm{rcond} = 0.0` is returned. **Warns** **NagAlgorithmicWarning** (`errno` :math:`\mathrm{n}+1`) :math:`U` (or :math:`L`) is nonsingular, but :math:`\mathrm{rcond}` is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of :math:`\mathrm{rcond}` would suggest. .. _f07fb-py2-py-notes: **Notes** ``dposvx`` performs the following steps: (1) If :math:`\mathrm{fact} = \texttt{'E'}`, real diagonal scaling factors, :math:`D_S`, are computed to equilibrate the system: .. math:: \left(D_SAD_S\right)\left(D_S^{-1}X\right) = D_SB\text{.} Whether or not the system will be equilibrated depends on the scaling of the matrix :math:`A`, but if equilibration is used, :math:`A` is overwritten by :math:`D_SAD_S` and :math:`B\times D_SB`. (#) If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, the Cholesky decomposition is used to factor the matrix :math:`A` (after equilibration if :math:`\mathrm{fact} = \texttt{'E'}`) as :math:`A = U^\mathrm{T}U` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LL^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` is an upper triangular matrix and :math:`L` is a lower triangular matrix. (#) If the leading :math:`i\times i` principal minor of :math:`A` is not positive definite, then the function returns with :math:`\textit{errno} = i`. Otherwise, the factored form of :math:`A` is used to estimate the condition number of the matrix :math:`A`. If the reciprocal of the condition number is less than machine precision, :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1 is returned as a warning, but the function still goes on to solve for :math:`X` and compute error bounds as described below. (#) The system of equations is solved for :math:`X` using the factored form of :math:`A`. (#) Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for it. (#) If equilibration was used, the matrix :math:`X` is premultiplied by :math:`D_S` so that it solves the original system before equilibration. .. _f07fb-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def dsposv(uplo, n, nrhs, a, b): r""" ``dsposv`` uses the Cholesky factorization .. math:: A = U^\mathrm{T}U\quad \text{ or }\quad A = LL^\mathrm{T} to compute the solution to a real system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` symmetric positive definite matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices. .. _f07fc-py2-py-doc: For full information please refer to the NAG Library document for f07fc https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07fcf.html .. _f07fc-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies whether the upper or lower triangular part of :math:`A` is stored. :math:`\mathrm{uplo} = \texttt{'U'}` The upper triangular part of :math:`A` is stored. :math:`\mathrm{uplo} = \texttt{'L'}` The lower triangular part of :math:`A` is stored. **n** : int :math:`n`, the number of linear equations, i.e., the order of the matrix :math:`A`. **nrhs** : int :math:`r`, the number of right-hand sides, i.e., the number of columns of the matrix :math:`B`. **a** : float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` The :math:`n\times n` symmetric positive definite matrix :math:`A`. **b** : float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` The right-hand side matrix :math:`B`. **Returns** **a** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` If iterative refinement has been successfully used (no exception or warning is raised and :math:`\mathrm{itera}\geq 0`, see :math:`\mathrm{itera}`), then :math:`\mathrm{a}` is unchanged. If full precision factorization has been used (no exception or warning is raised and :math:`\mathrm{itera} < 0`, see :math:`\mathrm{itera}`), then the array :math:`A` contains the factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{T}U` or :math:`A = LL^\mathrm{T}`. **x** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`. **itera** : int Information on the progress of the interative refinement process. :math:`\mathrm{itera} < 0` Iterative refinement has failed for one of the reasons given below, full precision factorization has been performed instead. .. rst-class:: nag-rules-none nag-align-left +-----------+------------------------------------------------------------------------------------------+ |:math:`-1` |The function fell back to full precision for implementation - or machine-specific reasons.| +-----------+------------------------------------------------------------------------------------------+ |:math:`-2` |Narrowing the precision induced an overflow, the function fell back to full precision. | +-----------+------------------------------------------------------------------------------------------+ |:math:`-3` |An intermediate reduced precision factorization failed. | +-----------+------------------------------------------------------------------------------------------+ |:math:`-31`|The maximum permitted number of iterations was exceeded. | +-----------+------------------------------------------------------------------------------------------+ :math:`\mathrm{itera} > 0` Iterative refinement has been sucessfully used. :math:`\mathrm{itera}` returns the number of iterations. .. _f07fc-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{nrhs}`. Constraint: :math:`\mathrm{nrhs}\geq 0`. (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq \mathrm{n}\right)`) The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is not positive definite, so the factorization could not be completed, and the solution has not been computed. .. _f07fc-py2-py-notes: **Notes** `No equivalent traditional C interface for this routine exists in the NAG Library.` ``dsposv`` first attempts to factorize the matrix in reduced precision and use this factorization within an iterative refinement procedure to produce a solution with full precision normwise backward error quality (see below). If the approach fails the method switches to a full precision factorization and solve. The iterative refinement can be more efficient than the corresponding direct full precision algorithm. Since the strategy implemented by ``dsposv`` must perform iterative refinement on each right-hand side, any efficiency gains will reduce as the number of right-hand sides increases. Conversely, as the matrix size increases the cost of these iterative refinements become less significant relative to the cost of factorization. Thus, any efficiency gains will be greatest for a very small number of right-hand sides and for large matrix sizes. The cut-off values for the number of right-hand sides and matrix size, for which the iterative refinement strategy performs better, depends on the relative performance of the reduced and full precision factorization and back-substitution. ``dsposv`` always attempts the iterative refinement strategy first; you are advised to compare the performance of ``dsposv`` with that of its full precision counterpart :meth:`dposv` to determine whether this strategy is worthwhile for your particular problem dimensions. The iterative refinement process is stopped if :math:`\mathrm{itera} > 30` where :math:`\mathrm{itera}` is the number of iterations carried out thus far. The process is also stopped if for all right-hand sides we have .. math:: \left\lVert \textit{resid}\right\rVert < \sqrt{\mathrm{n}}\left\lVert x\right\rVert \left\lVert A\right\rVert \epsilon \text{,} where :math:`\left\lVert \textit{resid}\right\rVert` is the :math:`\infty`-norm of the residual, :math:`\left\lVert x\right\rVert` is the :math:`\infty`-norm of the solution, :math:`\left\lVert A\right\rVert` is the :math:`\infty`-norm of the matrix :math:`A` and :math:`\epsilon` is the machine precision returned by :meth:`machine.precision <naginterfaces.library.machine.precision>`. .. _f07fc-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def dpotrf(uplo, a): r""" ``dpotrf`` computes the Cholesky factorization of a real symmetric positive definite matrix. .. _f07fd-py2-py-doc: For full information please refer to the NAG Library document for f07fd https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07fdf.html .. _f07fd-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies whether the upper or lower triangular part of :math:`A` is stored and how :math:`A` is to be factorized. :math:`\mathrm{uplo} = \texttt{'U'}` The upper triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`U^\mathrm{T}U`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` The lower triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`LL^\mathrm{T}`, where :math:`L` is lower triangular. **a** : float, array-like, shape :math:`\left(n, n\right)` The :math:`n\times n` symmetric positive definite matrix :math:`A`. **Returns** **a** : float, ndarray, shape :math:`\left(n, n\right)` The upper or lower triangle of :math:`A` is overwritten by the Cholesky factor :math:`U` or :math:`L` as specified by :math:`\mathrm{uplo}`. .. _f07fd-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`i > 0`) The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` is not positive definite and the factorization could not be completed. Hence :math:`A` itself is not positive definite. This may indicate an error in forming the matrix :math:`A`. To factorize a symmetric matrix which is not positive definite, call :meth:`dsytrf` instead. .. _f07fd-py2-py-notes: **Notes** ``dpotrf`` forms the Cholesky factorization of a real symmetric positive definite matrix :math:`A` either as :math:`A = U^\mathrm{T}U` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LL^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` is an upper triangular matrix and :math:`L` is lower triangular. .. _f07fd-py2-py-references: **References** Demmel, J W, 1989, `On floating-point errors in Cholesky`, LAPACK Working Note No. 14, University of Tennessee, Knoxville, https://www.netlib.org/lapack/lawnspdf/lawn14.pdf Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def dpotrs(uplo, a, b): r""" ``dpotrs`` solves a real symmetric positive definite system of linear equations with multiple right-hand sides, .. math:: AX = B\text{,} where :math:`A` has been factorized by :meth:`dpotrf`. .. _f07fe-py2-py-doc: For full information please refer to the NAG Library document for f07fe https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07fef.html .. _f07fe-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies how :math:`A` has been factorized. :math:`\mathrm{uplo} = \texttt{'U'}` :math:`A = U^\mathrm{T}U`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` :math:`A = LL^\mathrm{T}`, where :math:`L` is lower triangular. **a** : float, array-like, shape :math:`\left(n, n\right)` The Cholesky factor of :math:`A`, as returned by :meth:`dpotrf`. **b** : float, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **b** : float, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`. .. _f07fe-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. .. _f07fe-py2-py-notes: **Notes** ``dpotrs`` is used to solve a real symmetric positive definite system of linear equations :math:`AX = B`, this function must be preceded by a call to :meth:`dpotrf` which computes the Cholesky factorization of :math:`A`. The solution :math:`X` is computed by forward and backward substitution. If :math:`\mathrm{uplo} = \texttt{'U'}`, :math:`A = U^\mathrm{T}U`, where :math:`U` is upper triangular; the solution :math:`X` is computed by solving :math:`U^\mathrm{T}Y = B` and then :math:`UX = Y`. If :math:`\mathrm{uplo} = \texttt{'L'}`, :math:`A = LL^\mathrm{T}`, where :math:`L` is lower triangular; the solution :math:`X` is computed by solving :math:`LY = B` and then :math:`L^\mathrm{T}X = Y`. .. _f07fe-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def dpoequ(n, a): r""" ``dpoequ`` computes a diagonal scaling matrix :math:`S` intended to equilibrate a real :math:`n\times n` symmetric positive definite matrix :math:`A` and reduce its condition number. .. _f07ff-py2-py-doc: For full information please refer to the NAG Library document for f07ff https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07fff.html .. _f07ff-py2-py-parameters: **Parameters** **n** : int :math:`n`, the order of the matrix :math:`A`. **a** : float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` The matrix :math:`A` whose scaling factors are to be computed. Only the diagonal elements of the array :math:`\mathrm{a}` are referenced. **Returns** **s** : float, ndarray, shape :math:`\left(\mathrm{n}\right)` If no exception or warning is raised, :math:`\mathrm{s}` contains the diagonal elements of the scaling matrix :math:`S`. **scond** : float If no exception or warning is raised, :math:`\mathrm{scond}` contains the ratio of the smallest value of :math:`\mathrm{s}` to the largest value of :math:`\mathrm{s}`. If :math:`\mathrm{scond}\geq 0.1` and :math:`\mathrm{amax}` is neither too large nor too small, it is not worth scaling by :math:`S`. **amax** : float :math:`\mathrm{max}\left\lvert a_{{ij}}\right\rvert`. If :math:`\mathrm{amax}` is very close to overflow or underflow, the matrix :math:`A` should be scaled. .. _f07ff-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`i > 0`) The :math:`\langle\mathit{\boldsymbol{value}}\rangle`\ th diagonal element of :math:`A` is not positive (and hence :math:`A` cannot be positive definite). .. _f07ff-py2-py-notes: **Notes** ``dpoequ`` computes a diagonal scaling matrix :math:`S` chosen so that .. math:: s_j = 1/\sqrt{a_{{jj}}}\text{.} This means that the matrix :math:`B` given by .. math:: B = SAS\text{,} has diagonal elements equal to unity. This in turn means that the condition number of :math:`B`, :math:`\kappa_2\left(B\right)`, is within a factor :math:`n` of the matrix of smallest possible condition number over all possible choices of diagonal scalings (see Corollary 7.6 of Higham (2002)). .. _f07ff-py2-py-references: **References** Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def dpocon(uplo, n, a, anorm): r""" ``dpocon`` estimates the condition number of a real symmetric positive definite matrix :math:`A`, where :math:`A` has been factorized by :meth:`dpotrf`. .. _f07fg-py2-py-doc: For full information please refer to the NAG Library document for f07fg https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07fgf.html .. _f07fg-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies how :math:`A` has been factorized. :math:`\mathrm{uplo} = \texttt{'U'}` :math:`A = U^\mathrm{T}U`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` :math:`A = LL^\mathrm{T}`, where :math:`L` is lower triangular. **n** : int :math:`n`, the order of the matrix :math:`A`. **a** : float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` The Cholesky factor of :math:`A`, as returned by :meth:`dpotrf`. **anorm** : float The :math:`1`-norm of the **original** matrix :math:`A`, which may be computed by calling :meth:`blas.dlansy <naginterfaces.library.blas.dlansy>` with its argument :math:`{\textit{norm}} = \texttt{'1'}`. :math:`\mathrm{anorm}` must be computed either **before** calling :meth:`dpotrf` or else from a **copy** of the original matrix :math:`A`. **Returns** **rcond** : float An estimate of the reciprocal of the condition number of :math:`A`. :math:`\mathrm{rcond}` is set to zero if exact singularity is detected or the estimate underflows. If :math:`\mathrm{rcond}` is less than machine precision, :math:`A` is singular to working precision. .. _f07fg-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-5`) On entry, error in parameter :math:`\mathrm{anorm}`. Constraint: :math:`\mathrm{anorm}\geq 0.0`. .. _f07fg-py2-py-notes: **Notes** ``dpocon`` estimates the condition number (in the :math:`1`-norm) of a real symmetric positive definite matrix :math:`A`: .. math:: \kappa_1\left(A\right) = \left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\text{.} Since :math:`A` is symmetric, :math:`\kappa_1\left(A\right) = \kappa_{\infty }\left(A\right) = \left\lVert A\right\rVert_\infty\left\lVert A^{-1}\right\rVert_\infty`. Because :math:`\kappa_1\left(A\right)` is infinite if :math:`A` is singular, the function actually returns an estimate of the **reciprocal** of :math:`\kappa_1\left(A\right)`. The function should be preceded by a call to :meth:`blas.dlansy <naginterfaces.library.blas.dlansy>` to compute :math:`\left\lVert A\right\rVert_1` and a call to :meth:`dpotrf` to compute the Cholesky factorization of :math:`A`. The function then uses Higham's implementation of Hager's method (see Higham (1988)) to estimate :math:`\left\lVert A^{-1}\right\rVert_1`. .. _f07fg-py2-py-references: **References** Higham, N J, 1988, `FORTRAN codes for estimating the one-norm of a real or complex matrix, with applications to condition estimation`, ACM Trans. Math. Software (14), 381--396 """ raise NotImplementedError
[docs]def dporfs(uplo, n, a, af, b, x): r""" ``dporfs`` returns error bounds for the solution of a real symmetric positive definite system of linear equations with multiple right-hand sides, :math:`AX = B`. It improves the solution by iterative refinement, in order to reduce the backward error as much as possible. .. _f07fh-py2-py-doc: For full information please refer to the NAG Library document for f07fh https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07fhf.html .. _f07fh-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies whether the upper or lower triangular part of :math:`A` is stored and how :math:`A` is to be factorized. :math:`\mathrm{uplo} = \texttt{'U'}` The upper triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`U^\mathrm{T}U`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` The lower triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`LL^\mathrm{T}`, where :math:`L` is lower triangular. **n** : int :math:`n`, the order of the matrix :math:`A`. **a** : float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` The :math:`n\times n` original symmetric positive definite matrix :math:`A` as supplied to :meth:`dpotrf`. **af** : float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` The Cholesky factor of :math:`A`, as returned by :meth:`dpotrf`. **b** : float, array-like, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **x** : float, array-like, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`, as returned by :meth:`dpotrs`. **Returns** **x** : float, ndarray, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The improved solution matrix :math:`X`. **ferr** : float, ndarray, shape :math:`\left(\textit{nrhs}\right)` :math:`\mathrm{ferr}[\textit{j}-1]` contains an estimated error bound for the :math:`\textit{j}`\ th solution vector, that is, the :math:`\textit{j}`\ th column of :math:`X`, for :math:`\textit{j} = 1,2,\ldots,r`. **berr** : float, ndarray, shape :math:`\left(\textit{nrhs}\right)` :math:`\mathrm{berr}[\textit{j}-1]` contains the component-wise backward error bound :math:`\beta` for the :math:`\textit{j}`\ th solution vector, that is, the :math:`\textit{j}`\ th column of :math:`X`, for :math:`\textit{j} = 1,2,\ldots,r`. .. _f07fh-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. .. _f07fh-py2-py-notes: **Notes** ``dporfs`` returns the backward errors and estimated bounds on the forward errors for the solution of a real symmetric positive definite system of linear equations with multiple right-hand sides :math:`AX = B`. The function handles each right-hand side vector (stored as a column of the matrix :math:`B`) independently, so we describe the function of ``dporfs`` in terms of a single right-hand side :math:`b` and solution :math:`x`. Given a computed solution :math:`x`, the function computes the `component-wise backward error` :math:`\beta`. This is the size of the smallest relative perturbation in each element of :math:`A` and :math:`b` such that :math:`x` is the exact solution of a perturbed system .. math:: \begin{array}{c}\left(A+\delta A\right)x = b+\delta b\\\left\lvert \delta a_{{ij}}\right\rvert \leq \beta \left\lvert a_{{ij}}\right\rvert \quad \text{ and }\quad \left\lvert \delta b_i\right\rvert \leq \beta \left\lvert b_i\right\rvert \text{.} \end{array} Then the function estimates a bound for the `component-wise forward error` in the computed solution, defined by: .. math:: \mathrm{max}_i\left\lvert x_i-\hat{x}_i\right\rvert /\mathrm{max}_i\left\lvert x_i\right\rvert where :math:`\hat{x}` is the true solution. For details of the method, see `the F07 Introduction <https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07intro.html>`__. .. _f07fh-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def dpotri(uplo, a): r""" ``dpotri`` computes the inverse of a real symmetric positive definite matrix :math:`A`, where :math:`A` has been factorized by :meth:`dpotrf`. .. _f07fj-py2-py-doc: For full information please refer to the NAG Library document for f07fj https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07fjf.html .. _f07fj-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies how :math:`A` has been factorized. :math:`\mathrm{uplo} = \texttt{'U'}` :math:`A = U^\mathrm{T}U`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` :math:`A = LL^\mathrm{T}`, where :math:`L` is lower triangular. **a** : float, array-like, shape :math:`\left(n, n\right)` The upper triangular matrix :math:`U` if :math:`\mathrm{uplo} = \texttt{'U'}` or the lower triangular matrix :math:`L` if :math:`\mathrm{uplo} = \texttt{'L'}`, as returned by :meth:`dpotrf`. **Returns** **a** : float, ndarray, shape :math:`\left(n, n\right)` :math:`U` is overwritten by the upper triangle of :math:`A^{-1}` if :math:`\mathrm{uplo} = \texttt{'U'}`; :math:`L` is overwritten by the lower triangle of :math:`A^{-1}` if :math:`\mathrm{uplo} = \texttt{'L'}`. .. _f07fj-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Diagonal element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the Cholesky factor is zero; the Cholesky factor is singular and the inverse of :math:`A` cannot be computed. .. _f07fj-py2-py-notes: **Notes** ``dpotri`` is used to compute the inverse of a real symmetric positive definite matrix :math:`A`, the function must be preceded by a call to :meth:`dpotrf`, which computes the Cholesky factorization of :math:`A`. If :math:`\mathrm{uplo} = \texttt{'U'}`, :math:`A = U^\mathrm{T}U` and :math:`A^{-1}` is computed by first inverting :math:`U` and then forming :math:`\left(U^{-1}\right)U^{-\mathrm{T}}`. If :math:`\mathrm{uplo} = \texttt{'L'}`, :math:`A = LL^\mathrm{T}` and :math:`A^{-1}` is computed by first inverting :math:`L` and then forming :math:`L^{-\mathrm{T}}\left(L^{-1}\right)`. .. _f07fj-py2-py-references: **References** Du Croz, J J and Higham, N J, 1992, `Stability of methods for matrix inversion`, IMA J. Numer. Anal. (12), 1--19 """ raise NotImplementedError
[docs]def zposv(uplo, a, b): r""" ``zposv`` computes the solution to a complex system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` Hermitian positive definite matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices. .. _f07fn-py2-py-doc: For full information please refer to the NAG Library document for f07fn https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07fnf.html .. _f07fn-py2-py-parameters: **Parameters** **uplo** : str, length 1 If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored. If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored. **a** : complex, array-like, shape :math:`\left(n, n\right)` The :math:`n\times n` Hermitian matrix :math:`A`. **b** : complex, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **a** : complex, ndarray, shape :math:`\left(n, n\right)` If no exception or warning is raised, the factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{H}U` or :math:`A = LL^\mathrm{H}`. **b** : complex, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`. .. _f07fn-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. (`errno` :math:`i > 0`) The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is not positive definite, so the factorization could not be completed, and the solution has not been computed. .. _f07fn-py2-py-notes: **Notes** ``zposv`` uses the Cholesky decomposition to factor :math:`A` as :math:`A = U^\mathrm{H}U` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LL^\mathrm{H}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` is an upper triangular matrix and :math:`L` is a lower triangular matrix. The factored form of :math:`A` is then used to solve the system of equations :math:`AX = B`. .. _f07fn-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def zposvx(fact, uplo, n, nrhs, a, af, equed, s, b): r""" ``zposvx`` uses the Cholesky factorization .. math:: A = U^\mathrm{H}U\quad \text{ or }\quad A = LL^\mathrm{H} to compute the solution to a complex system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` Hermitian positive definite matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices. Error bounds on the solution and a condition estimate are also provided. .. _f07fp-py2-py-doc: For full information please refer to the NAG Library document for f07fp https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07fpf.html .. _f07fp-py2-py-parameters: **Parameters** **fact** : str, length 1 Specifies whether or not the factorized form of the matrix :math:`A` is supplied on entry, and if not, whether the matrix :math:`A` should be equilibrated before it is factorized. :math:`\mathrm{fact} = \texttt{'F'}` :math:`\mathrm{af}` contains the factorized form of :math:`A`. If :math:`\mathrm{equed} = \texttt{'Y'}`, the matrix :math:`A` has been equilibrated with scaling factors given by :math:`\mathrm{s}`. :math:`\mathrm{a}` and :math:`\mathrm{af}` will not be modified. :math:`\mathrm{fact} = \texttt{'N'}` The matrix :math:`A` will be copied to :math:`\mathrm{af}` and factorized. :math:`\mathrm{fact} = \texttt{'E'}` The matrix :math:`A` will be equilibrated if necessary, then copied to :math:`\mathrm{af}` and factorized. **uplo** : str, length 1 If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored. If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored. **n** : int :math:`n`, the number of linear equations, i.e., the order of the matrix :math:`A`. **nrhs** : int :math:`r`, the number of right-hand sides, i.e., the number of columns of the matrix :math:`B`. **a** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` The :math:`n\times n` Hermitian matrix :math:`A`. If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{a}` must have been equilibrated by the scaling factor in :math:`\mathrm{s}` as :math:`D_SAD_S`. **af** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{af}` contains the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{H}U` or :math:`A = LL^\mathrm{H}`, in the same storage format as :math:`\mathrm{a}`. If :math:`\mathrm{equed} \neq \texttt{'N'}`, :math:`\mathrm{af}` is the factorized form of the equilibrated matrix :math:`D_SAD_S`. **equed** : str, length 1 If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{equed}` need not be set. If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` must specify the form of the equilibration that was performed as follows: if :math:`\mathrm{equed} = \texttt{'N'}`, no equilibration; if :math:`\mathrm{equed} = \texttt{'Y'}`, equilibration was performed, i.e., :math:`A` has been replaced by :math:`D_SAD_S`. **s** : float, array-like, shape :math:`\left(\mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{s}` need not be set. If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{s}` must contain the scale factors, :math:`D_S`, for :math:`A`; each element of :math:`\mathrm{s}` must be positive. **b** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **a** : complex, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'F'}` or :math:`\texttt{'N'}`, or if :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{a}` is not modified. If :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{a}` is overwritten by :math:`D_SAD_S`. **af** : complex, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{af}` returns the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{H}U` or :math:`A = LL^\mathrm{H}` of the original matrix :math:`A`. If :math:`\mathrm{fact} = \texttt{'E'}`, :math:`\mathrm{af}` returns the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{H}U` or :math:`A = LL^\mathrm{H}` of the equilibrated matrix :math:`A` (see the description of :math:`\mathrm{a}` for the form of the equilibrated matrix). **equed** : str, length 1 If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` is unchanged from entry. Otherwise, if no constraints are violated, :math:`\mathrm{equed}` specifies the form of the equilibration that was performed as specified above. **s** : float, ndarray, shape :math:`\left(\mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{s}` is unchanged from entry. Otherwise, if no constraints are violated and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{s}` contains the scale factors, :math:`D_S`, for :math:`A`; each element of :math:`\mathrm{s}` is positive. **b** : complex, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` If :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{b}` is not modified. If :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{b}` is overwritten by :math:`D_SB`. **x** : complex, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, the :math:`n\times r` solution matrix :math:`X` to the original system of equations. Note that the arrays :math:`A` and :math:`B` are modified on exit if :math:`\mathrm{equed} = \texttt{'Y'}`, and the solution to the equilibrated system is :math:`D_S^{-1}X`. **rcond** : float If no constraints are violated, an estimate of the reciprocal condition number of the matrix :math:`A` (after equilibration if that is performed), computed as :math:`\mathrm{rcond} = 1.0/\left(\left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\right)`. **ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the forward error bound for each computed solution vector, such that :math:`\left\lVert \hat{x}_j-x_j\right\rVert_\infty/\left\lVert x_j\right\rVert_\infty\leq \mathrm{ferr}[j-1]` where :math:`\hat{x}_j` is the :math:`j`\ th column of the computed solution returned in the array :math:`\mathrm{x}` and :math:`x_j` is the corresponding column of the exact solution :math:`X`. The estimate is as reliable as the estimate for :math:`\mathrm{rcond}`, and is almost always a slight overestimate of the true error. **berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the component-wise relative backward error of each computed solution vector :math:`\hat{x}_j` (i.e., the smallest relative change in any element of :math:`A` or :math:`B` that makes :math:`\hat{x}_j` an exact solution). .. _f07fp-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{fact}`. Constraint: :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\texttt{'N'}` or :math:`\texttt{'E'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\mathrm{nrhs}`. Constraint: :math:`\mathrm{nrhs}\geq 0`. (`errno` :math:`-9`) On entry, error in parameter :math:`\mathrm{equed}`. Constraint: :math:`\mathrm{equed} = \texttt{'N'}` or :math:`\texttt{'Y'}`. (`errno` :math:`-10`) On entry, error in parameter :math:`\mathrm{s}`. (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq \mathrm{n}\right)`) The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is not positive definite, so the factorization could not be completed, and the solution has not been computed. :math:`\mathrm{rcond} = 0.0` is returned. **Warns** **NagAlgorithmicWarning** (`errno` :math:`\mathrm{n}+1`) :math:`U` (or :math:`L`) is nonsingular, but :math:`\mathrm{rcond}` is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of :math:`\mathrm{rcond}` would suggest. .. _f07fp-py2-py-notes: **Notes** ``zposvx`` performs the following steps: (1) If :math:`\mathrm{fact} = \texttt{'E'}`, real diagonal scaling factors, :math:`D_S`, are computed to equilibrate the system: .. math:: \left(D_SAD_S\right)\left(D_S^{-1}X\right) = D_SB\text{.} Whether or not the system will be equilibrated depends on the scaling of the matrix :math:`A`, but if equilibration is used, :math:`A` is overwritten by :math:`D_SAD_S` and :math:`B\times D_SB`. (#) If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, the Cholesky decomposition is used to factor the matrix :math:`A` (after equilibration if :math:`\mathrm{fact} = \texttt{'E'}`) as :math:`A = U^\mathrm{H}U` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LL^\mathrm{H}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` is an upper triangular matrix and :math:`L` is a lower triangular matrix. (#) If the leading :math:`i\times i` principal minor of :math:`A` is not positive definite, then the function returns with :math:`\textit{errno} = i`. Otherwise, the factored form of :math:`A` is used to estimate the condition number of the matrix :math:`A`. If the reciprocal of the condition number is less than machine precision, :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1 is returned as a warning, but the function still goes on to solve for :math:`X` and compute error bounds as described below. (#) The system of equations is solved for :math:`X` using the factored form of :math:`A`. (#) Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for it. (#) If equilibration was used, the matrix :math:`X` is premultiplied by :math:`D_S` so that it solves the original system before equilibration. .. _f07fp-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def zcposv(uplo, n, nrhs, a, b): r""" ``zcposv`` uses the Cholesky factorization .. math:: A = U^\mathrm{H}U\quad \text{ or }\quad A = LL^\mathrm{H} to compute the solution to a complex system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` Hermitian positive definite matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices. .. _f07fq-py2-py-doc: For full information please refer to the NAG Library document for f07fq https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07fqf.html .. _f07fq-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies whether the upper or lower triangular part of :math:`A` is stored. :math:`\mathrm{uplo} = \texttt{'U'}` The upper triangular part of :math:`A` is stored. :math:`\mathrm{uplo} = \texttt{'L'}` The lower triangular part of :math:`A` is stored. **n** : int :math:`n`, the number of linear equations, i.e., the order of the matrix :math:`A`. **nrhs** : int :math:`r`, the number of right-hand sides, i.e., the number of columns of the matrix :math:`B`. **a** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` The :math:`n\times n` Hermitian positive definite matrix :math:`A`. **b** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` The right-hand side matrix :math:`B`. **Returns** **a** : complex, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` If iterative refinement has been successfully used (no exception or warning is raised and :math:`\mathrm{itera}\geq 0`, see :math:`\mathrm{itera}`), then :math:`\mathrm{a}` is unchanged. If full precision factorization has been used (no exception or warning is raised and :math:`\mathrm{itera} < 0`, see :math:`\mathrm{itera}`), then the array :math:`A` contains the factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{H}U` or :math:`A = LL^\mathrm{H}`. **x** : complex, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`. **itera** : int Information on the progress of the interative refinement process. :math:`\mathrm{itera} < 0` Iterative refinement has failed for one of the reasons given below, full precision factorization has been performed instead. .. rst-class:: nag-rules-none nag-align-left +-----------+------------------------------------------------------------------------------------------+ |:math:`-1` |The function fell back to full precision for implementation - or machine-specific reasons.| +-----------+------------------------------------------------------------------------------------------+ |:math:`-2` |Narrowing the precision induced an overflow, the function fell back to full precision. | +-----------+------------------------------------------------------------------------------------------+ |:math:`-3` |An intermediate reduced precision factorization failed. | +-----------+------------------------------------------------------------------------------------------+ |:math:`-31`|The maximum permitted number of iterations was exceeded. | +-----------+------------------------------------------------------------------------------------------+ :math:`\mathrm{itera} > 0` Iterative refinement has been sucessfully used. :math:`\mathrm{itera}` returns the number of iterations. .. _f07fq-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{nrhs}`. Constraint: :math:`\mathrm{nrhs}\geq 0`. (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq \mathrm{n}\right)`) The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is not positive definite, so the factorization could not be completed, and the solution has not been computed. .. _f07fq-py2-py-notes: **Notes** `No equivalent traditional C interface for this routine exists in the NAG Library.` ``zcposv`` first attempts to factorize the matrix in reduced precision and use this factorization within an iterative refinement procedure to produce a solution with full precision normwise backward error quality (see below). If the approach fails the method switches to a full precision factorization and solve. The iterative refinement can be more efficient than the corresponding direct full precision algorithm. Since the strategy implemented by ``zcposv`` must perform iterative refinement on each right-hand side, any efficiency gains will reduce as the number of right-hand sides increases. Conversely, as the matrix size increases the cost of these iterative refinements become less significant relative to the cost of factorization. Thus, any efficiency gains will be greatest for a very small number of right-hand sides and for large matrix sizes. The cut-off values for the number of right-hand sides and matrix size, for which the iterative refinement strategy performs better, depends on the relative performance of the reduced and full precision factorization and back-substitution. ``zcposv`` always attempts the iterative refinement strategy first; you are advised to compare the performance of ``zcposv`` with that of its full precision counterpart :meth:`zposv` to determine whether this strategy is worthwhile for your particular problem dimensions. The iterative refinement process is stopped if :math:`\mathrm{itera} > 30` where :math:`\mathrm{itera}` is the number of iterations carried out thus far. The process is also stopped if for all right-hand sides we have .. math:: \left\lVert \textit{resid}\right\rVert < \sqrt{\mathrm{n}}\left\lVert x\right\rVert \left\lVert A\right\rVert \epsilon \text{,} where :math:`\left\lVert \textit{resid}\right\rVert` is the :math:`\infty`-norm of the residual, :math:`\left\lVert x\right\rVert` is the :math:`\infty`-norm of the solution, :math:`\left\lVert A\right\rVert` is the :math:`\infty`-norm of the matrix :math:`A` and :math:`\epsilon` is the machine precision returned by :meth:`machine.precision <naginterfaces.library.machine.precision>`. .. _f07fq-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def zpotrf(uplo, a): r""" ``zpotrf`` computes the Cholesky factorization of a complex Hermitian positive definite matrix. .. _f07fr-py2-py-doc: For full information please refer to the NAG Library document for f07fr https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07frf.html .. _f07fr-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies whether the upper or lower triangular part of :math:`A` is stored and how :math:`A` is to be factorized. :math:`\mathrm{uplo} = \texttt{'U'}` The upper triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`U^\mathrm{H}U`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` The lower triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`LL^\mathrm{H}`, where :math:`L` is lower triangular. **a** : complex, array-like, shape :math:`\left(n, n\right)` The :math:`n\times n` Hermitian positive definite matrix :math:`A`. **Returns** **a** : complex, ndarray, shape :math:`\left(n, n\right)` The upper or lower triangle of :math:`A` is overwritten by the Cholesky factor :math:`U` or :math:`L` as specified by :math:`\mathrm{uplo}`. .. _f07fr-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`i > 0`) The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` is not positive definite and the factorization could not be completed. Hence :math:`A` itself is not positive definite. This may indicate an error in forming the matrix :math:`A`. To factorize a Hermitian matrix which is not positive definite, call :meth:`zhetrf` instead. .. _f07fr-py2-py-notes: **Notes** ``zpotrf`` forms the Cholesky factorization of a complex Hermitian positive definite matrix :math:`A` either as :math:`A = U^\mathrm{H}U` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LL^\mathrm{H}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` is an upper triangular matrix and :math:`L` is lower triangular. .. _f07fr-py2-py-references: **References** Demmel, J W, 1989, `On floating-point errors in Cholesky`, LAPACK Working Note No. 14, University of Tennessee, Knoxville, https://www.netlib.org/lapack/lawnspdf/lawn14.pdf Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def zpotrs(uplo, a, b): r""" ``zpotrs`` solves a complex Hermitian positive definite system of linear equations with multiple right-hand sides, .. math:: AX = B\text{,} where :math:`A` has been factorized by :meth:`zpotrf`. .. _f07fs-py2-py-doc: For full information please refer to the NAG Library document for f07fs https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07fsf.html .. _f07fs-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies how :math:`A` has been factorized. :math:`\mathrm{uplo} = \texttt{'U'}` :math:`A = U^\mathrm{H}U`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` :math:`A = LL^\mathrm{H}`, where :math:`L` is lower triangular. **a** : complex, array-like, shape :math:`\left(n, n\right)` The Cholesky factor of :math:`A`, as returned by :meth:`zpotrf`. **b** : complex, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **b** : complex, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`. .. _f07fs-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. .. _f07fs-py2-py-notes: **Notes** ``zpotrs`` is used to solve a complex Hermitian positive definite system of linear equations :math:`AX = B`, this function must be preceded by a call to :meth:`zpotrf` which computes the Cholesky factorization of :math:`A`. The solution :math:`X` is computed by forward and backward substitution. If :math:`\mathrm{uplo} = \texttt{'U'}`, :math:`A = U^\mathrm{H}U`, where :math:`U` is upper triangular; the solution :math:`X` is computed by solving :math:`U^\mathrm{H}Y = B` and then :math:`UX = Y`. If :math:`\mathrm{uplo} = \texttt{'L'}`, :math:`A = LL^\mathrm{H}`, where :math:`L` is lower triangular; the solution :math:`X` is computed by solving :math:`LY = B` and then :math:`L^\mathrm{H}X = Y`. .. _f07fs-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def zpoequ(n, a): r""" ``zpoequ`` computes a diagonal scaling matrix :math:`S` intended to equilibrate a complex :math:`n\times n` Hermitian positive definite matrix :math:`A` and reduce its condition number. .. _f07ft-py2-py-doc: For full information please refer to the NAG Library document for f07ft https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07ftf.html .. _f07ft-py2-py-parameters: **Parameters** **n** : int :math:`n`, the order of the matrix :math:`A`. **a** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` The matrix :math:`A` whose scaling factors are to be computed. Only the diagonal elements of the array :math:`\mathrm{a}` are referenced. **Returns** **s** : float, ndarray, shape :math:`\left(\mathrm{n}\right)` If no exception or warning is raised, :math:`\mathrm{s}` contains the diagonal elements of the scaling matrix :math:`S`. **scond** : float If no exception or warning is raised, :math:`\mathrm{scond}` contains the ratio of the smallest value of :math:`\mathrm{s}` to the largest value of :math:`\mathrm{s}`. If :math:`\mathrm{scond}\geq 0.1` and :math:`\mathrm{amax}` is neither too large nor too small, it is not worth scaling by :math:`S`. **amax** : float :math:`\mathrm{max}\left\lvert a_{{ij}}\right\rvert`. If :math:`\mathrm{amax}` is very close to overflow or underflow, the matrix :math:`A` should be scaled. .. _f07ft-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`i > 0`) The :math:`\langle\mathit{\boldsymbol{value}}\rangle`\ th diagonal element of :math:`A` is not positive (and hence :math:`A` cannot be positive definite). .. _f07ft-py2-py-notes: **Notes** ``zpoequ`` computes a diagonal scaling matrix :math:`S` chosen so that .. math:: s_j = 1/\sqrt{a_{{jj}}}\text{.} This means that the matrix :math:`B` given by .. math:: B = SAS\text{,} has diagonal elements equal to unity. This in turn means that the condition number of :math:`B`, :math:`\kappa_2\left(B\right)`, is within a factor :math:`n` of the matrix of smallest possible condition number over all possible choices of diagonal scalings (see Corollary 7.6 of Higham (2002)). .. _f07ft-py2-py-references: **References** Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def zpocon(uplo, n, a, anorm): r""" ``zpocon`` estimates the condition number of a complex Hermitian positive definite matrix :math:`A`, where :math:`A` has been factorized by :meth:`zpotrf`. .. _f07fu-py2-py-doc: For full information please refer to the NAG Library document for f07fu https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07fuf.html .. _f07fu-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies how :math:`A` has been factorized. :math:`\mathrm{uplo} = \texttt{'U'}` :math:`A = U^\mathrm{H}U`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` :math:`A = LL^\mathrm{H}`, where :math:`L` is lower triangular. **n** : int :math:`n`, the order of the matrix :math:`A`. **a** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` The Cholesky factor of :math:`A`, as returned by :meth:`zpotrf`. **anorm** : float The :math:`1`-norm of the **original** matrix :math:`A`, which may be computed by calling :meth:`blas.zlanhe <naginterfaces.library.blas.zlanhe>` with its argument :math:`{\textit{norm}} = \texttt{'1'}`. :math:`\mathrm{anorm}` must be computed either **before** calling :meth:`zpotrf` or else from a **copy** of the original matrix :math:`A`. **Returns** **rcond** : float An estimate of the reciprocal of the condition number of :math:`A`. :math:`\mathrm{rcond}` is set to zero if exact singularity is detected or the estimate underflows. If :math:`\mathrm{rcond}` is less than machine precision, :math:`A` is singular to working precision. .. _f07fu-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-5`) On entry, error in parameter :math:`\mathrm{anorm}`. Constraint: :math:`\mathrm{anorm}\geq 0.0`. .. _f07fu-py2-py-notes: **Notes** ``zpocon`` estimates the condition number (in the :math:`1`-norm) of a complex Hermitian positive definite matrix :math:`A`: .. math:: \kappa_1\left(A\right) = \left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\text{.} Since :math:`A` is Hermitian, :math:`\kappa_1\left(A\right) = \kappa_{\infty }\left(A\right) = \left\lVert A\right\rVert_\infty\left\lVert A^{-1}\right\rVert_\infty`. Because :math:`\kappa_1\left(A\right)` is infinite if :math:`A` is singular, the function actually returns an estimate of the **reciprocal** of :math:`\kappa_1\left(A\right)`. The function should be preceded by a call to :meth:`blas.zlanhe <naginterfaces.library.blas.zlanhe>` to compute :math:`\left\lVert A\right\rVert_1` and a call to :meth:`zpotrf` to compute the Cholesky factorization of :math:`A`. The function then uses Higham's implementation of Hager's method (see Higham (1988)) to estimate :math:`\left\lVert A^{-1}\right\rVert_1`. .. _f07fu-py2-py-references: **References** Higham, N J, 1988, `FORTRAN codes for estimating the one-norm of a real or complex matrix, with applications to condition estimation`, ACM Trans. Math. Software (14), 381--396 """ raise NotImplementedError
[docs]def zporfs(uplo, n, a, af, b, x): r""" ``zporfs`` returns error bounds for the solution of a complex Hermitian positive definite system of linear equations with multiple right-hand sides, :math:`AX = B`. It improves the solution by iterative refinement, in order to reduce the backward error as much as possible. .. _f07fv-py2-py-doc: For full information please refer to the NAG Library document for f07fv https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07fvf.html .. _f07fv-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies whether the upper or lower triangular part of :math:`A` is stored and how :math:`A` is to be factorized. :math:`\mathrm{uplo} = \texttt{'U'}` The upper triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`U^\mathrm{H}U`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` The lower triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`LL^\mathrm{H}`, where :math:`L` is lower triangular. **n** : int :math:`n`, the order of the matrix :math:`A`. **a** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` The :math:`n\times n` original Hermitian positive definite matrix :math:`A` as supplied to :meth:`zpotrf`. **af** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` The Cholesky factor of :math:`A`, as returned by :meth:`zpotrf`. **b** : complex, array-like, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **x** : complex, array-like, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`, as returned by :meth:`zpotrs`. **Returns** **x** : complex, ndarray, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The improved solution matrix :math:`X`. **ferr** : float, ndarray, shape :math:`\left(\textit{nrhs}\right)` :math:`\mathrm{ferr}[\textit{j}-1]` contains an estimated error bound for the :math:`\textit{j}`\ th solution vector, that is, the :math:`\textit{j}`\ th column of :math:`X`, for :math:`\textit{j} = 1,2,\ldots,r`. **berr** : float, ndarray, shape :math:`\left(\textit{nrhs}\right)` :math:`\mathrm{berr}[\textit{j}-1]` contains the component-wise backward error bound :math:`\beta` for the :math:`\textit{j}`\ th solution vector, that is, the :math:`\textit{j}`\ th column of :math:`X`, for :math:`\textit{j} = 1,2,\ldots,r`. .. _f07fv-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. .. _f07fv-py2-py-notes: **Notes** ``zporfs`` returns the backward errors and estimated bounds on the forward errors for the solution of a complex Hermitian positive definite system of linear equations with multiple right-hand sides :math:`AX = B`. The function handles each right-hand side vector (stored as a column of the matrix :math:`B`) independently, so we describe the function of ``zporfs`` in terms of a single right-hand side :math:`b` and solution :math:`x`. Given a computed solution :math:`x`, the function computes the `component-wise backward error` :math:`\beta`. This is the size of the smallest relative perturbation in each element of :math:`A` and :math:`b` such that :math:`x` is the exact solution of a perturbed system .. math:: \begin{array}{c}\left(A+\delta A\right)x = b+\delta b\\\left\lvert \delta a_{{ij}}\right\rvert \leq \beta \left\lvert a_{{ij}}\right\rvert \quad \text{ and }\quad \left\lvert \delta b_i\right\rvert \leq \beta \left\lvert b_i\right\rvert \text{.} \end{array} Then the function estimates a bound for the `component-wise forward error` in the computed solution, defined by: .. math:: \mathrm{max}_i\left\lvert x_i-\hat{x}_i\right\rvert /\mathrm{max}_i\left\lvert x_i\right\rvert where :math:`\hat{x}` is the true solution. For details of the method, see `the F07 Introduction <https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07intro.html>`__. .. _f07fv-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def zpotri(uplo, a): r""" ``zpotri`` computes the inverse of a complex Hermitian positive definite matrix :math:`A`, where :math:`A` has been factorized by :meth:`zpotrf`. .. _f07fw-py2-py-doc: For full information please refer to the NAG Library document for f07fw https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07fwf.html .. _f07fw-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies how :math:`A` has been factorized. :math:`\mathrm{uplo} = \texttt{'U'}` :math:`A = U^\mathrm{H}U`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` :math:`A = LL^\mathrm{H}`, where :math:`L` is lower triangular. **a** : complex, array-like, shape :math:`\left(n, n\right)` The upper triangular matrix :math:`U` if :math:`\mathrm{uplo} = \texttt{'U'}` or the lower triangular matrix :math:`L` if :math:`\mathrm{uplo} = \texttt{'L'}`, as returned by :meth:`zpotrf`. **Returns** **a** : complex, ndarray, shape :math:`\left(n, n\right)` :math:`U` is overwritten by the upper triangle of :math:`A^{-1}` if :math:`\mathrm{uplo} = \texttt{'U'}`; :math:`L` is overwritten by the lower triangle of :math:`A^{-1}` if :math:`\mathrm{uplo} = \texttt{'L'}`. .. _f07fw-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Diagonal element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the Cholesky factor is zero; the Cholesky factor is singular and the inverse of :math:`A` cannot be computed. .. _f07fw-py2-py-notes: **Notes** ``zpotri`` is used to compute the inverse of a complex Hermitian positive definite matrix :math:`A`, the function must be preceded by a call to :meth:`zpotrf`, which computes the Cholesky factorization of :math:`A`. If :math:`\mathrm{uplo} = \texttt{'U'}`, :math:`A = U^\mathrm{H}U` and :math:`A^{-1}` is computed by first inverting :math:`U` and then forming :math:`\left(U^{-1}\right)U^{-\mathrm{H}}`. If :math:`\mathrm{uplo} = \texttt{'L'}`, :math:`A = LL^\mathrm{H}` and :math:`A^{-1}` is computed by first inverting :math:`L` and then forming :math:`L^{-\mathrm{H}}\left(L^{-1}\right)`. .. _f07fw-py2-py-references: **References** Du Croz, J J and Higham, N J, 1992, `Stability of methods for matrix inversion`, IMA J. Numer. Anal. (12), 1--19 """ raise NotImplementedError
[docs]def dppsv(uplo, ap, b): r""" ``dppsv`` computes the solution to a real system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` symmetric positive definite matrix stored in packed format and :math:`X` and :math:`B` are :math:`n\times r` matrices. .. _f07ga-py2-py-doc: For full information please refer to the NAG Library document for f07ga https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07gaf.html .. _f07ga-py2-py-parameters: **Parameters** **uplo** : str, length 1 If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored. If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored. **ap** : float, array-like, shape :math:`\left(n\times \left(n+1\right)/2\right)` The :math:`n\times n` symmetric matrix :math:`A`, packed by columns. **b** : float, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **ap** : float, ndarray, shape :math:`\left(n\times \left(n+1\right)/2\right)` If no exception or warning is raised, the factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{T}U` or :math:`A = LL^\mathrm{T}`, in the same storage format as :math:`A`. **b** : float, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`. .. _f07ga-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. (`errno` :math:`i > 0`) The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is not positive definite, so the factorization could not be completed, and the solution has not been computed. .. _f07ga-py2-py-notes: **Notes** ``dppsv`` uses the Cholesky decomposition to factor :math:`A` as :math:`A = U^\mathrm{T}U` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LL^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` is an upper triangular matrix and :math:`L` is a lower triangular matrix. The factored form of :math:`A` is then used to solve the system of equations :math:`AX = B`. .. _f07ga-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def dppsvx(fact, uplo, n, nrhs, ap, afp, equed, s, b): r""" ``dppsvx`` uses the Cholesky factorization .. math:: A = U^\mathrm{T}U\quad \text{ or }\quad A = LL^\mathrm{T} to compute the solution to a real system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` symmetric positive definite matrix stored in packed format and :math:`X` and :math:`B` are :math:`n\times r` matrices. Error bounds on the solution and a condition estimate are also provided. .. _f07gb-py2-py-doc: For full information please refer to the NAG Library document for f07gb https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07gbf.html .. _f07gb-py2-py-parameters: **Parameters** **fact** : str, length 1 Specifies whether or not the factorized form of the matrix :math:`A` is supplied on entry, and if not, whether the matrix :math:`A` should be equilibrated before it is factorized. :math:`\mathrm{fact} = \texttt{'F'}` :math:`\mathrm{afp}` contains the factorized form of :math:`A`. If :math:`\mathrm{equed} = \texttt{'Y'}`, the matrix :math:`A` has been equilibrated with scaling factors given by :math:`\mathrm{s}`. :math:`\mathrm{ap}` and :math:`\mathrm{afp}` will not be modified. :math:`\mathrm{fact} = \texttt{'N'}` The matrix :math:`A` will be copied to :math:`\mathrm{afp}` and factorized. :math:`\mathrm{fact} = \texttt{'E'}` The matrix :math:`A` will be equilibrated if necessary, then copied to :math:`\mathrm{afp}` and factorized. **uplo** : str, length 1 If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored. If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored. **n** : int :math:`n`, the number of linear equations, i.e., the order of the matrix :math:`A`. **nrhs** : int :math:`r`, the number of right-hand sides, i.e., the number of columns of the matrix :math:`B`. **ap** : float, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{ap}` must contain the equilibrated matrix :math:`D_SAD_S`; otherwise, :math:`\mathrm{ap}` must contain the :math:`n\times n` symmetric matrix :math:`A`, packed by columns. **afp** : float, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{afp}` contains the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{T}U` or :math:`A = LL^\mathrm{T}`, in the same storage format as :math:`\mathrm{ap}`. If :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{afp}` is the factorized form of the equilibrated matrix :math:`D_SAD_S`. **equed** : str, length 1 If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{equed}` need not be set. If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` must specify the form of the equilibration that was performed as follows: if :math:`\mathrm{equed} = \texttt{'N'}`, no equilibration; if :math:`\mathrm{equed} = \texttt{'Y'}`, equilibration was performed, i.e., :math:`A` has been replaced by :math:`D_SAD_S`. **s** : float, array-like, shape :math:`\left(\mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{s}` need not be set. If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{s}` must contain the scale factors, :math:`D_S`, for :math:`A`; each element of :math:`\mathrm{s}` must be positive. **b** : float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **ap** : float, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` If :math:`\mathrm{fact} = \texttt{'F'}` or :math:`\texttt{'N'}`, or if :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{ap}` is not modified. If :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{ap}` is overwritten by :math:`D_SAD_S`. **afp** : float, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` If :math:`\mathrm{fact} = \texttt{'N'}` or if :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{afp}` returns the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{T}U` or :math:`A = LL^\mathrm{T}` of the original matrix :math:`A`. If :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{afp}` returns the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{T}U` or :math:`A = LL^\mathrm{T}` of the equilibrated matrix :math:`A` (see the description of :math:`\mathrm{ap}` for the form of the equilibrated matrix). **equed** : str, length 1 If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` is unchanged from entry. Otherwise, if no constraints are violated, :math:`\mathrm{equed}` specifies the form of the equilibration that was performed as specified above. **s** : float, ndarray, shape :math:`\left(\mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{s}` is unchanged from entry. Otherwise, if no constraints are violated and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{s}` contains the scale factors, :math:`D_S`, for :math:`A`; each element of :math:`\mathrm{s}` is positive. **b** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` If :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{b}` is not modified. If :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{b}` is overwritten by :math:`D_SB`. **x** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, the :math:`n\times r` solution matrix :math:`X` to the original system of equations. Note that the arrays :math:`A` and :math:`B` are modified on exit if :math:`\mathrm{equed} = \texttt{'Y'}`, and the solution to the equilibrated system is :math:`D_S^{-1}X`. **rcond** : float If no constraints are violated, an estimate of the reciprocal condition number of the matrix :math:`A` (after equilibration if that is performed), computed as :math:`\mathrm{rcond} = 1.0/\left(\left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\right)`. **ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the forward error bound for each computed solution vector, such that :math:`\left\lVert \hat{x}_j-x_j\right\rVert_\infty/\left\lVert x_j\right\rVert_\infty\leq \mathrm{ferr}[j-1]` where :math:`\hat{x}_j` is the :math:`j`\ th column of the computed solution returned in the array :math:`\mathrm{x}` and :math:`x_j` is the corresponding column of the exact solution :math:`X`. The estimate is as reliable as the estimate for :math:`\mathrm{rcond}`, and is almost always a slight overestimate of the true error. **berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the component-wise relative backward error of each computed solution vector :math:`\hat{x}_j` (i.e., the smallest relative change in any element of :math:`A` or :math:`B` that makes :math:`\hat{x}_j` an exact solution). .. _f07gb-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{fact}`. Constraint: :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\texttt{'N'}` or :math:`\texttt{'E'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\mathrm{nrhs}`. Constraint: :math:`\mathrm{nrhs}\geq 0`. (`errno` :math:`-7`) On entry, error in parameter :math:`\mathrm{equed}`. Constraint: :math:`\mathrm{equed} = \texttt{'N'}` or :math:`\texttt{'Y'}`. (`errno` :math:`-8`) On entry, error in parameter :math:`\mathrm{s}`. (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq \mathrm{n}\right)`) The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is not positive definite, so the factorization could not be completed, and the solution has not been computed. :math:`\mathrm{rcond} = 0.0` is returned. **Warns** **NagAlgorithmicWarning** (`errno` :math:`\mathrm{n}+1`) :math:`U` (or :math:`L`) is nonsingular, but :math:`\mathrm{rcond}` is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of :math:`\mathrm{rcond}` would suggest. .. _f07gb-py2-py-notes: **Notes** ``dppsvx`` performs the following steps: (1) If :math:`\mathrm{fact} = \texttt{'E'}`, real diagonal scaling factors, :math:`D_S`, are computed to equilibrate the system: .. math:: \left(D_SAD_S\right)\left(D_S^{-1}X\right) = D_SB\text{.} Whether or not the system will be equilibrated depends on the scaling of the matrix :math:`A`, but if equilibration is used, :math:`A` is overwritten by :math:`D_SAD_S` and :math:`B\times D_SB`. (#) If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, the Cholesky decomposition is used to factor the matrix :math:`A` (after equilibration if :math:`\mathrm{fact} = \texttt{'E'}`) as :math:`A = U^\mathrm{T}U` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LL^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` is an upper triangular matrix and :math:`L` is a lower triangular matrix. (#) If the leading :math:`i\times i` principal minor of :math:`A` is not positive definite, then the function returns with :math:`\textit{errno} = i`. Otherwise, the factored form of :math:`A` is used to estimate the condition number of the matrix :math:`A`. If the reciprocal of the condition number is less than machine precision, :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1 is returned as a warning, but the function still goes on to solve for :math:`X` and compute error bounds as described below. (#) The system of equations is solved for :math:`X` using the factored form of :math:`A`. (#) Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for it. (#) If equilibration was used, the matrix :math:`X` is premultiplied by :math:`D_S` so that it solves the original system before equilibration. .. _f07gb-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def dpptrf(uplo, n, ap): r""" ``dpptrf`` computes the Cholesky factorization of a real symmetric positive definite matrix, using packed storage. .. _f07gd-py2-py-doc: For full information please refer to the NAG Library document for f07gd https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07gdf.html .. _f07gd-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies whether the upper or lower triangular part of :math:`A` is stored and how :math:`A` is to be factorized. :math:`\mathrm{uplo} = \texttt{'U'}` The upper triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`U^\mathrm{T}U`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` The lower triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`LL^\mathrm{T}`, where :math:`L` is lower triangular. **n** : int :math:`n`, the order of the matrix :math:`A`. **ap** : float, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` The :math:`n\times n` symmetric matrix :math:`A`, packed by columns. **Returns** **ap** : float, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` If no exception or warning is raised, the factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{T}U` or :math:`A = LL^\mathrm{T}`, in the same storage format as :math:`A`. .. _f07gd-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`i > 0`) The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` is not positive definite and the factorization could not be completed. Hence :math:`A` itself is not positive definite. This may indicate an error in forming the matrix :math:`A`. To factorize a symmetric matrix which is not positive definite, call :meth:`dsptrf` instead. .. _f07gd-py2-py-notes: **Notes** ``dpptrf`` forms the Cholesky factorization of a real symmetric positive definite matrix :math:`A` either as :math:`A = U^\mathrm{T}U` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LL^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` is an upper triangular matrix and :math:`L` is lower triangular, using packed storage. .. _f07gd-py2-py-references: **References** Demmel, J W, 1989, `On floating-point errors in Cholesky`, LAPACK Working Note No. 14, University of Tennessee, Knoxville, https://www.netlib.org/lapack/lawnspdf/lawn14.pdf Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def dpptrs(uplo, n, ap, b): r""" ``dpptrs`` solves a real symmetric positive definite system of linear equations with multiple right-hand sides, .. math:: AX = B\text{,} where :math:`A` has been factorized by :meth:`dpptrf`, using packed storage. .. _f07ge-py2-py-doc: For full information please refer to the NAG Library document for f07ge https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07gef.html .. _f07ge-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies how :math:`A` has been factorized. :math:`\mathrm{uplo} = \texttt{'U'}` :math:`A = U^\mathrm{T}U`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` :math:`A = LL^\mathrm{T}`, where :math:`L` is lower triangular. **n** : int :math:`n`, the order of the matrix :math:`A`. **ap** : float, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` The Cholesky factor of :math:`A` stored in packed form, as returned by :meth:`dpptrf`. **b** : float, array-like, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **b** : float, ndarray, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`. .. _f07ge-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. .. _f07ge-py2-py-notes: **Notes** ``dpptrs`` is used to solve a real symmetric positive definite system of linear equations :math:`AX = B`, the function must be preceded by a call to :meth:`dpptrf` which computes the Cholesky factorization of :math:`A`, using packed storage. The solution :math:`X` is computed by forward and backward substitution. If :math:`\mathrm{uplo} = \texttt{'U'}`, :math:`A = U^\mathrm{T}U`, where :math:`U` is upper triangular; the solution :math:`X` is computed by solving :math:`U^\mathrm{T}Y = B` and then :math:`UX = Y`. If :math:`\mathrm{uplo} = \texttt{'L'}`, :math:`A = LL^\mathrm{T}`, where :math:`L` is lower triangular; the solution :math:`X` is computed by solving :math:`LY = B` and then :math:`L^\mathrm{T}X = Y`. .. _f07ge-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def dppequ(uplo, n, ap): r""" ``dppequ`` computes a diagonal scaling matrix :math:`S` intended to equilibrate a real :math:`n\times n` symmetric positive definite matrix :math:`A`, stored in packed format, and reduce its condition number. .. _f07gf-py2-py-doc: For full information please refer to the NAG Library document for f07gf https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07gff.html .. _f07gf-py2-py-parameters: **Parameters** **uplo** : str, length 1 Indicates whether the upper or lower triangular part of :math:`A` is stored in the array :math:`\mathrm{ap}`, as follows: :math:`\mathrm{uplo} = \texttt{'U'}` The upper triangle of :math:`A` is stored. :math:`\mathrm{uplo} = \texttt{'L'}` The lower triangle of :math:`A` is stored. **n** : int :math:`n`, the order of the matrix :math:`A`. **ap** : float, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` The :math:`n\times n` symmetric matrix :math:`A`, packed by columns. Only the elements of :math:`\mathrm{ap}` corresponding to the diagonal elements :math:`A` are referenced. **Returns** **s** : float, ndarray, shape :math:`\left(\mathrm{n}\right)` If no exception or warning is raised, :math:`\mathrm{s}` contains the diagonal elements of the scaling matrix :math:`S`. **scond** : float If no exception or warning is raised, :math:`\mathrm{scond}` contains the ratio of the smallest value of :math:`\mathrm{s}` to the largest value of :math:`\mathrm{s}`. If :math:`\mathrm{scond}\geq 0.1` and :math:`\mathrm{amax}` is neither too large nor too small, it is not worth scaling by :math:`S`. **amax** : float :math:`\mathrm{max}\left\lvert a_{{ij}}\right\rvert`. If :math:`\mathrm{amax}` is very close to overflow or underflow, the matrix :math:`A` should be scaled. .. _f07gf-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`i > 0`) The :math:`\langle\mathit{\boldsymbol{value}}\rangle`\ th diagonal element of :math:`A` is not positive (and hence :math:`A` cannot be positive definite). .. _f07gf-py2-py-notes: **Notes** ``dppequ`` computes a diagonal scaling matrix :math:`S` chosen so that .. math:: s_j = 1/\sqrt{a_{{jj}}}\text{.} This means that the matrix :math:`B` given by .. math:: B = SAS\text{,} has diagonal elements equal to unity. This in turn means that the condition number of :math:`B`, :math:`\kappa_2\left(B\right)`, is within a factor :math:`n` of the matrix of smallest possible condition number over all possible choices of diagonal scalings (see Corollary 7.6 of Higham (2002)). .. _f07gf-py2-py-references: **References** Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def dppcon(uplo, n, ap, anorm): r""" ``dppcon`` estimates the condition number of a real symmetric positive definite matrix :math:`A`, where :math:`A` has been factorized by :meth:`dpptrf`, using packed storage. .. _f07gg-py2-py-doc: For full information please refer to the NAG Library document for f07gg https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07ggf.html .. _f07gg-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies how :math:`A` has been factorized. :math:`\mathrm{uplo} = \texttt{'U'}` :math:`A = U^\mathrm{T}U`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` :math:`A = LL^\mathrm{T}`, where :math:`L` is lower triangular. **n** : int :math:`n`, the order of the matrix :math:`A`. **ap** : float, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` The Cholesky factor of :math:`A` stored in packed form, as returned by :meth:`dpptrf`. **anorm** : float The :math:`1`-norm of the **original** matrix :math:`A`, which may be computed by calling :meth:`blas.dlansp <naginterfaces.library.blas.dlansp>` with its argument :math:`{\textit{norm}} = \texttt{'1'}`. :math:`\mathrm{anorm}` must be computed either **before** calling :meth:`dpptrf` or else from a **copy** of the original matrix :math:`A`. **Returns** **rcond** : float An estimate of the reciprocal of the condition number of :math:`A`. :math:`\mathrm{rcond}` is set to zero if exact singularity is detected or the estimate underflows. If :math:`\mathrm{rcond}` is less than machine precision, :math:`A` is singular to working precision. .. _f07gg-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\mathrm{anorm}`. Constraint: :math:`\mathrm{anorm}\geq 0.0`. .. _f07gg-py2-py-notes: **Notes** ``dppcon`` estimates the condition number (in the :math:`1`-norm) of a real symmetric positive definite matrix :math:`A`: .. math:: \kappa_1\left(A\right) = \left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\text{.} Since :math:`A` is symmetric, :math:`\kappa_1\left(A\right) = \kappa_{\infty }\left(A\right) = \left\lVert A\right\rVert_\infty\left\lVert A^{-1}\right\rVert_\infty`. Because :math:`\kappa_1\left(A\right)` is infinite if :math:`A` is singular, the function actually returns an estimate of the **reciprocal** of :math:`\kappa_1\left(A\right)`. The function should be preceded by a call to :meth:`blas.dlansp <naginterfaces.library.blas.dlansp>` to compute :math:`\left\lVert A\right\rVert_1` and a call to :meth:`dpptrf` to compute the Cholesky factorization of :math:`A`. The function then uses Higham's implementation of Hager's method (see Higham (1988)) to estimate :math:`\left\lVert A^{-1}\right\rVert_1`. .. _f07gg-py2-py-references: **References** Higham, N J, 1988, `FORTRAN codes for estimating the one-norm of a real or complex matrix, with applications to condition estimation`, ACM Trans. Math. Software (14), 381--396 """ raise NotImplementedError
[docs]def dpprfs(uplo, n, ap, afp, b, x): r""" ``dpprfs`` returns error bounds for the solution of a real symmetric positive definite system of linear equations with multiple right-hand sides, :math:`AX = B`, using packed storage. It improves the solution by iterative refinement, in order to reduce the backward error as much as possible. .. _f07gh-py2-py-doc: For full information please refer to the NAG Library document for f07gh https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07ghf.html .. _f07gh-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies whether the upper or lower triangular part of :math:`A` is stored and how :math:`A` is to be factorized. :math:`\mathrm{uplo} = \texttt{'U'}` The upper triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`U^\mathrm{T}U`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` The lower triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`LL^\mathrm{T}`, where :math:`L` is lower triangular. **n** : int :math:`n`, the order of the matrix :math:`A`. **ap** : float, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` The :math:`n\times n` original symmetric positive definite matrix :math:`A` as supplied to :meth:`dpptrf`. **afp** : float, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` The Cholesky factor of :math:`A` stored in packed form, as returned by :meth:`dpptrf`. **b** : float, array-like, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **x** : float, array-like, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`, as returned by :meth:`dpptrs`. **Returns** **x** : float, ndarray, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The improved solution matrix :math:`X`. **ferr** : float, ndarray, shape :math:`\left(\textit{nrhs}\right)` :math:`\mathrm{ferr}[\textit{j}-1]` contains an estimated error bound for the :math:`\textit{j}`\ th solution vector, that is, the :math:`\textit{j}`\ th column of :math:`X`, for :math:`\textit{j} = 1,2,\ldots,r`. **berr** : float, ndarray, shape :math:`\left(\textit{nrhs}\right)` :math:`\mathrm{berr}[\textit{j}-1]` contains the component-wise backward error bound :math:`\beta` for the :math:`\textit{j}`\ th solution vector, that is, the :math:`\textit{j}`\ th column of :math:`X`, for :math:`\textit{j} = 1,2,\ldots,r`. .. _f07gh-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. .. _f07gh-py2-py-notes: **Notes** ``dpprfs`` returns the backward errors and estimated bounds on the forward errors for the solution of a real symmetric positive definite system of linear equations with multiple right-hand sides :math:`AX = B`, using packed storage. The function handles each right-hand side vector (stored as a column of the matrix :math:`B`) independently, so we describe the function of ``dpprfs`` in terms of a single right-hand side :math:`b` and solution :math:`x`. Given a computed solution :math:`x`, the function computes the `component-wise backward error` :math:`\beta`. This is the size of the smallest relative perturbation in each element of :math:`A` and :math:`b` such that :math:`x` is the exact solution of a perturbed system .. math:: \begin{array}{c}\left(A+\delta A\right)x = b+\delta b\\\left\lvert \delta a_{{ij}}\right\rvert \leq \beta \left\lvert a_{{ij}}\right\rvert \quad \text{ and }\quad \left\lvert \delta b_i\right\rvert \leq \beta \left\lvert b_i\right\rvert \text{.} \end{array} Then the function estimates a bound for the `component-wise forward error` in the computed solution, defined by: .. math:: \mathrm{max}_i\left\lvert x_i-\hat{x}_i\right\rvert /\mathrm{max}_i\left\lvert x_i\right\rvert where :math:`\hat{x}` is the true solution. For details of the method, see `the F07 Introduction <https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07intro.html>`__. .. _f07gh-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def dpptri(uplo, n, ap): r""" ``dpptri`` computes the inverse of a real symmetric positive definite matrix :math:`A`, where :math:`A` has been factorized by :meth:`dpptrf`, using packed storage. .. _f07gj-py2-py-doc: For full information please refer to the NAG Library document for f07gj https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07gjf.html .. _f07gj-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies how :math:`A` has been factorized. :math:`\mathrm{uplo} = \texttt{'U'}` :math:`A = U^\mathrm{T}U`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` :math:`A = LL^\mathrm{T}`, where :math:`L` is lower triangular. **n** : int :math:`n`, the order of the matrix :math:`A`. **ap** : float, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` The Cholesky factor of :math:`A` stored in packed form, as returned by :meth:`dpptrf`. **Returns** **ap** : float, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` The factorization is overwritten by the :math:`n\times n` matrix :math:`A^{-1}`. .. _f07gj-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Diagonal element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the Cholesky factor is zero; the Cholesky factor is singular and the inverse of :math:`A` cannot be computed. .. _f07gj-py2-py-notes: **Notes** ``dpptri`` is used to compute the inverse of a real symmetric positive definite matrix :math:`A`, the function must be preceded by a call to :meth:`dpptrf`, which computes the Cholesky factorization of :math:`A`, using packed storage. If :math:`\mathrm{uplo} = \texttt{'U'}`, :math:`A = U^\mathrm{T}U` and :math:`A^{-1}` is computed by first inverting :math:`U` and then forming :math:`\left(U^{-1}\right)U^{-\mathrm{T}}`. If :math:`\mathrm{uplo} = \texttt{'L'}`, :math:`A = LL^\mathrm{T}` and :math:`A^{-1}` is computed by first inverting :math:`L` and then forming :math:`L^{-\mathrm{T}}\left(L^{-1}\right)`. .. _f07gj-py2-py-references: **References** Du Croz, J J and Higham, N J, 1992, `Stability of methods for matrix inversion`, IMA J. Numer. Anal. (12), 1--19 """ raise NotImplementedError
[docs]def zppsv(uplo, ap, b): r""" ``zppsv`` computes the solution to a complex system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` Hermitian positive definite matrix stored in packed format and :math:`X` and :math:`B` are :math:`n\times r` matrices. .. _f07gn-py2-py-doc: For full information please refer to the NAG Library document for f07gn https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07gnf.html .. _f07gn-py2-py-parameters: **Parameters** **uplo** : str, length 1 If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored. If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored. **ap** : complex, array-like, shape :math:`\left(n\times \left(n+1\right)/2\right)` The :math:`n\times n` Hermitian matrix :math:`A`, packed by columns. **b** : complex, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **ap** : complex, ndarray, shape :math:`\left(n\times \left(n+1\right)/2\right)` If no exception or warning is raised, the factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{H}U` or :math:`A = LL^\mathrm{H}`, in the same storage format as :math:`A`. **b** : complex, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`. .. _f07gn-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. (`errno` :math:`i > 0`) The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is not positive definite, so the factorization could not be completed, and the solution has not been computed. .. _f07gn-py2-py-notes: **Notes** ``zppsv`` uses the Cholesky decomposition to factor :math:`A` as :math:`A = U^\mathrm{H}U` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LL^\mathrm{H}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` is an upper triangular matrix and :math:`L` is a lower triangular matrix. The factored form of :math:`A` is then used to solve the system of equations :math:`AX = B`. .. _f07gn-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def zppsvx(fact, uplo, n, nrhs, ap, afp, equed, s, b): r""" ``zppsvx`` uses the Cholesky factorization .. math:: A = U^\mathrm{H}U\quad \text{ or }\quad A = LL^\mathrm{H} to compute the solution to a complex system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` Hermitian positive definite matrix stored in packed format and :math:`X` and :math:`B` are :math:`n\times r` matrices. Error bounds on the solution and a condition estimate are also provided. .. _f07gp-py2-py-doc: For full information please refer to the NAG Library document for f07gp https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07gpf.html .. _f07gp-py2-py-parameters: **Parameters** **fact** : str, length 1 Specifies whether or not the factorized form of the matrix :math:`A` is supplied on entry, and if not, whether the matrix :math:`A` should be equilibrated before it is factorized. :math:`\mathrm{fact} = \texttt{'F'}` :math:`\mathrm{afp}` contains the factorized form of :math:`A`. If :math:`\mathrm{equed} = \texttt{'Y'}`, the matrix :math:`A` has been equilibrated with scaling factors given by :math:`\mathrm{s}`. :math:`\mathrm{ap}` and :math:`\mathrm{afp}` will not be modified. :math:`\mathrm{fact} = \texttt{'N'}` The matrix :math:`A` will be copied to :math:`\mathrm{afp}` and factorized. :math:`\mathrm{fact} = \texttt{'E'}` The matrix :math:`A` will be equilibrated if necessary, then copied to :math:`\mathrm{afp}` and factorized. **uplo** : str, length 1 If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored. If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored. **n** : int :math:`n`, the number of linear equations, i.e., the order of the matrix :math:`A`. **nrhs** : int :math:`r`, the number of right-hand sides, i.e., the number of columns of the matrix :math:`B`. **ap** : complex, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{ap}` must contain the equilibrated matrix :math:`D_SAD_S`; otherwise, :math:`\mathrm{ap}` must contain the :math:`n\times n` Hermitian matrix :math:`A`, packed by columns. **afp** : complex, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{afp}` contains the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{H}U` or :math:`A = LL^\mathrm{H}`, in the same storage format as :math:`\mathrm{ap}`. If :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{afp}` is the factorized form of the equilibrated matrix :math:`D_SAD_S`. **equed** : str, length 1 If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{equed}` need not be set. If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` must specify the form of the equilibration that was performed as follows: if :math:`\mathrm{equed} = \texttt{'N'}`, no equilibration; if :math:`\mathrm{equed} = \texttt{'Y'}`, equilibration was performed, i.e., :math:`A` has been replaced by :math:`D_SAD_S`. **s** : float, array-like, shape :math:`\left(\mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{s}` need not be set. If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{s}` must contain the scale factors, :math:`D_S`, for :math:`A`; each element of :math:`\mathrm{s}` must be positive. **b** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **ap** : complex, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` If :math:`\mathrm{fact} = \texttt{'F'}` or :math:`\texttt{'N'}`, or if :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{ap}` is not modified. If :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{ap}` is overwritten by :math:`D_SAD_S`. **afp** : complex, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` If :math:`\mathrm{fact} = \texttt{'N'}` or if :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{afp}` returns the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{H}U` or :math:`A = LL^\mathrm{H}` of the original matrix :math:`A`. If :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{afp}` returns the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{H}U` or :math:`A = LL^\mathrm{H}` of the equilibrated matrix :math:`A` (see the description of :math:`\mathrm{ap}` for the form of the equilibrated matrix). **equed** : str, length 1 If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` is unchanged from entry. Otherwise, if no constraints are violated, :math:`\mathrm{equed}` specifies the form of the equilibration that was performed as specified above. **s** : float, ndarray, shape :math:`\left(\mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{s}` is unchanged from entry. Otherwise, if no constraints are violated and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{s}` contains the scale factors, :math:`D_S`, for :math:`A`; each element of :math:`\mathrm{s}` is positive. **b** : complex, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` If :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{b}` is not modified. If :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{b}` is overwritten by :math:`D_SB`. **x** : complex, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, the :math:`n\times r` solution matrix :math:`X` to the original system of equations. Note that the arrays :math:`A` and :math:`B` are modified on exit if :math:`\mathrm{equed} = \texttt{'Y'}`, and the solution to the equilibrated system is :math:`D_S^{-1}X`. **rcond** : float If no constraints are violated, an estimate of the reciprocal condition number of the matrix :math:`A` (after equilibration if that is performed), computed as :math:`\mathrm{rcond} = 1.0/\left(\left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\right)`. **ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the forward error bound for each computed solution vector, such that :math:`\left\lVert \hat{x}_j-x_j\right\rVert_\infty/\left\lVert x_j\right\rVert_\infty\leq \mathrm{ferr}[j-1]` where :math:`\hat{x}_j` is the :math:`j`\ th column of the computed solution returned in the array :math:`\mathrm{x}` and :math:`x_j` is the corresponding column of the exact solution :math:`X`. The estimate is as reliable as the estimate for :math:`\mathrm{rcond}`, and is almost always a slight overestimate of the true error. **berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the component-wise relative backward error of each computed solution vector :math:`\hat{x}_j` (i.e., the smallest relative change in any element of :math:`A` or :math:`B` that makes :math:`\hat{x}_j` an exact solution). .. _f07gp-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{fact}`. Constraint: :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\texttt{'N'}` or :math:`\texttt{'E'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\mathrm{nrhs}`. Constraint: :math:`\mathrm{nrhs}\geq 0`. (`errno` :math:`-7`) On entry, error in parameter :math:`\mathrm{equed}`. Constraint: :math:`\mathrm{equed} = \texttt{'N'}` or :math:`\texttt{'Y'}`. (`errno` :math:`-8`) On entry, error in parameter :math:`\mathrm{s}`. (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq \mathrm{n}\right)`) The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is not positive definite, so the factorization could not be completed, and the solution has not been computed. :math:`\mathrm{rcond} = 0.0` is returned. **Warns** **NagAlgorithmicWarning** (`errno` :math:`\mathrm{n}+1`) :math:`U` (or :math:`L`) is nonsingular, but :math:`\mathrm{rcond}` is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of :math:`\mathrm{rcond}` would suggest. .. _f07gp-py2-py-notes: **Notes** ``zppsvx`` performs the following steps: (1) If :math:`\mathrm{fact} = \texttt{'E'}`, real diagonal scaling factors, :math:`D_S`, are computed to equilibrate the system: .. math:: \left(D_SAD_S\right)\left(D_S^{-1}X\right) = D_SB\text{.} Whether or not the system will be equilibrated depends on the scaling of the matrix :math:`A`, but if equilibration is used, :math:`A` is overwritten by :math:`D_SAD_S` and :math:`B\times D_SB`. (#) If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, the Cholesky decomposition is used to factor the matrix :math:`A` (after equilibration if :math:`\mathrm{fact} = \texttt{'E'}`) as :math:`A = U^\mathrm{H}U` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LL^\mathrm{H}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` is an upper triangular matrix and :math:`L` is a lower triangular matrix. (#) If the leading :math:`i\times i` principal minor of :math:`A` is not positive definite, then the function returns with :math:`\textit{errno} = i`. Otherwise, the factored form of :math:`A` is used to estimate the condition number of the matrix :math:`A`. If the reciprocal of the condition number is less than machine precision, :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1 is returned as a warning, but the function still goes on to solve for :math:`X` and compute error bounds as described below. (#) The system of equations is solved for :math:`X` using the factored form of :math:`A`. (#) Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for it. (#) If equilibration was used, the matrix :math:`X` is premultiplied by :math:`D_S` so that it solves the original system before equilibration. .. _f07gp-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def zpptrf(uplo, n, ap): r""" ``zpptrf`` computes the Cholesky factorization of a complex Hermitian positive definite matrix, using packed storage. .. _f07gr-py2-py-doc: For full information please refer to the NAG Library document for f07gr https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07grf.html .. _f07gr-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies whether the upper or lower triangular part of :math:`A` is stored and how :math:`A` is to be factorized. :math:`\mathrm{uplo} = \texttt{'U'}` The upper triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`U^\mathrm{H}U`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` The lower triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`LL^\mathrm{H}`, where :math:`L` is lower triangular. **n** : int :math:`n`, the order of the matrix :math:`A`. **ap** : complex, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` The :math:`n\times n` Hermitian matrix :math:`A`, packed by columns. **Returns** **ap** : complex, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` If no exception or warning is raised, the factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{H}U` or :math:`A = LL^\mathrm{H}`, in the same storage format as :math:`A`. .. _f07gr-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`i > 0`) The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` is not positive definite and the factorization could not be completed. Hence :math:`A` itself is not positive definite. This may indicate an error in forming the matrix :math:`A`. To factorize a Hermitian matrix which is not positive definite, call :meth:`zhptrf` instead. .. _f07gr-py2-py-notes: **Notes** ``zpptrf`` forms the Cholesky factorization of a complex Hermitian positive definite matrix :math:`A` either as :math:`A = U^\mathrm{H}U` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LL^\mathrm{H}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` is an upper triangular matrix and :math:`L` is lower triangular, using packed storage. .. _f07gr-py2-py-references: **References** Demmel, J W, 1989, `On floating-point errors in Cholesky`, LAPACK Working Note No. 14, University of Tennessee, Knoxville, https://www.netlib.org/lapack/lawnspdf/lawn14.pdf Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def zpptrs(uplo, n, ap, b): r""" ``zpptrs`` solves a complex Hermitian positive definite system of linear equations with multiple right-hand sides, .. math:: AX = B\text{,} where :math:`A` has been factorized by :meth:`zpptrf`, using packed storage. .. _f07gs-py2-py-doc: For full information please refer to the NAG Library document for f07gs https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07gsf.html .. _f07gs-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies how :math:`A` has been factorized. :math:`\mathrm{uplo} = \texttt{'U'}` :math:`A = U^\mathrm{H}U`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` :math:`A = LL^\mathrm{H}`, where :math:`L` is lower triangular. **n** : int :math:`n`, the order of the matrix :math:`A`. **ap** : complex, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` The Cholesky factor of :math:`A` stored in packed form, as returned by :meth:`zpptrf`. **b** : complex, array-like, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **b** : complex, ndarray, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`. .. _f07gs-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. .. _f07gs-py2-py-notes: **Notes** ``zpptrs`` is used to solve a complex Hermitian positive definite system of linear equations :math:`AX = B`, the function must be preceded by a call to :meth:`zpptrf` which computes the Cholesky factorization of :math:`A`, using packed storage. The solution :math:`X` is computed by forward and backward substitution. If :math:`\mathrm{uplo} = \texttt{'U'}`, :math:`A = U^\mathrm{H}U`, where :math:`U` is upper triangular; the solution :math:`X` is computed by solving :math:`U^\mathrm{H}Y = B` and then :math:`UX = Y`. If :math:`\mathrm{uplo} = \texttt{'L'}`, :math:`A = LL^\mathrm{H}`, where :math:`L` is lower triangular; the solution :math:`X` is computed by solving :math:`LY = B` and then :math:`L^\mathrm{H}X = Y`. .. _f07gs-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def zppequ(uplo, n, ap): r""" ``zppequ`` computes a diagonal scaling matrix :math:`S` intended to equilibrate a complex :math:`n\times n` Hermitian positive definite matrix :math:`A`, stored in packed format, and reduce its condition number. .. _f07gt-py2-py-doc: For full information please refer to the NAG Library document for f07gt https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07gtf.html .. _f07gt-py2-py-parameters: **Parameters** **uplo** : str, length 1 Indicates whether the upper or lower triangular part of :math:`A` is stored in the array :math:`\mathrm{ap}`, as follows: :math:`\mathrm{uplo} = \texttt{'U'}` The upper triangle of :math:`A` is stored. :math:`\mathrm{uplo} = \texttt{'L'}` The lower triangle of :math:`A` is stored. **n** : int :math:`n`, the order of the matrix :math:`A`. **ap** : complex, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` The :math:`n\times n` Hermitian matrix :math:`A`, packed by columns. Only the elements of :math:`\mathrm{ap}` corresponding to the diagonal elements :math:`A` are referenced. **Returns** **s** : float, ndarray, shape :math:`\left(\mathrm{n}\right)` If no exception or warning is raised, :math:`\mathrm{s}` contains the diagonal elements of the scaling matrix :math:`S`. **scond** : float If no exception or warning is raised, :math:`\mathrm{scond}` contains the ratio of the smallest value of :math:`\mathrm{s}` to the largest value of :math:`\mathrm{s}`. If :math:`\mathrm{scond}\geq 0.1` and :math:`\mathrm{amax}` is neither too large nor too small, it is not worth scaling by :math:`S`. **amax** : float :math:`\mathrm{max}\left\lvert a_{{ij}}\right\rvert`. If :math:`\mathrm{amax}` is very close to overflow or underflow, the matrix :math:`A` should be scaled. .. _f07gt-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`i > 0`) The :math:`\langle\mathit{\boldsymbol{value}}\rangle`\ th diagonal element of :math:`A` is not positive (and hence :math:`A` cannot be positive definite). .. _f07gt-py2-py-notes: **Notes** ``zppequ`` computes a diagonal scaling matrix :math:`S` chosen so that .. math:: s_j = 1/\sqrt{a_{{jj}}}\text{.} This means that the matrix :math:`B` given by .. math:: B = SAS\text{,} has diagonal elements equal to unity. This in turn means that the condition number of :math:`B`, :math:`\kappa_2\left(B\right)`, is within a factor :math:`n` of the matrix of smallest possible condition number over all possible choices of diagonal scalings (see Corollary 7.6 of Higham (2002)). .. _f07gt-py2-py-references: **References** Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def zppcon(uplo, n, ap, anorm): r""" ``zppcon`` estimates the condition number of a complex Hermitian positive definite matrix :math:`A`, where :math:`A` has been factorized by :meth:`zpptrf`, using packed storage. .. _f07gu-py2-py-doc: For full information please refer to the NAG Library document for f07gu https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07guf.html .. _f07gu-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies how :math:`A` has been factorized. :math:`\mathrm{uplo} = \texttt{'U'}` :math:`A = U^\mathrm{H}U`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` :math:`A = LL^\mathrm{H}`, where :math:`L` is lower triangular. **n** : int :math:`n`, the order of the matrix :math:`A`. **ap** : complex, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` The Cholesky factor of :math:`A` stored in packed form, as returned by :meth:`zpptrf`. **anorm** : float The :math:`1`-norm of the **original** matrix :math:`A`, which may be computed by calling :meth:`blas.zlanhp <naginterfaces.library.blas.zlanhp>` with its argument :math:`{\textit{norm}} = \texttt{'1'}`. :math:`\mathrm{anorm}` must be computed either **before** calling :meth:`zpptrf` or else from a **copy** of the original matrix :math:`A`. **Returns** **rcond** : float An estimate of the reciprocal of the condition number of :math:`A`. :math:`\mathrm{rcond}` is set to zero if exact singularity is detected or the estimate underflows. If :math:`\mathrm{rcond}` is less than machine precision, :math:`A` is singular to working precision. .. _f07gu-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\mathrm{anorm}`. Constraint: :math:`\mathrm{anorm}\geq 0.0`. .. _f07gu-py2-py-notes: **Notes** ``zppcon`` estimates the condition number (in the :math:`1`-norm) of a complex Hermitian positive definite matrix :math:`A`: .. math:: \kappa_1\left(A\right) = \left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\text{.} Since :math:`A` is Hermitian, :math:`\kappa_1\left(A\right) = \kappa_{\infty }\left(A\right) = \left\lVert A\right\rVert_\infty\left\lVert A^{-1}\right\rVert_\infty`. Because :math:`\kappa_1\left(A\right)` is infinite if :math:`A` is singular, the function actually returns an estimate of the **reciprocal** of :math:`\kappa_1\left(A\right)`. The function should be preceded by a call to :meth:`blas.zlanhp <naginterfaces.library.blas.zlanhp>` to compute :math:`\left\lVert A\right\rVert_1` and a call to :meth:`zpptrf` to compute the Cholesky factorization of :math:`A`. The function then uses Higham's implementation of Hager's method (see Higham (1988)) to estimate :math:`\left\lVert A^{-1}\right\rVert_1`. .. _f07gu-py2-py-references: **References** Higham, N J, 1988, `FORTRAN codes for estimating the one-norm of a real or complex matrix, with applications to condition estimation`, ACM Trans. Math. Software (14), 381--396 """ raise NotImplementedError
[docs]def zpprfs(uplo, n, ap, afp, b, x): r""" ``zpprfs`` returns error bounds for the solution of a complex Hermitian positive definite system of linear equations with multiple right-hand sides, :math:`AX = B`, using packed storage. It improves the solution by iterative refinement, in order to reduce the backward error as much as possible. .. _f07gv-py2-py-doc: For full information please refer to the NAG Library document for f07gv https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07gvf.html .. _f07gv-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies whether the upper or lower triangular part of :math:`A` is stored and how :math:`A` is to be factorized. :math:`\mathrm{uplo} = \texttt{'U'}` The upper triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`U^\mathrm{H}U`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` The lower triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`LL^\mathrm{H}`, where :math:`L` is lower triangular. **n** : int :math:`n`, the order of the matrix :math:`A`. **ap** : complex, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` The :math:`n\times n` original Hermitian positive definite matrix :math:`A` as supplied to :meth:`zpptrf`. **afp** : complex, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` The Cholesky factor of :math:`A` stored in packed form, as returned by :meth:`zpptrf`. **b** : complex, array-like, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **x** : complex, array-like, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`, as returned by :meth:`zpptrs`. **Returns** **x** : complex, ndarray, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The improved solution matrix :math:`X`. **ferr** : float, ndarray, shape :math:`\left(\textit{nrhs}\right)` :math:`\mathrm{ferr}[\textit{j}-1]` contains an estimated error bound for the :math:`\textit{j}`\ th solution vector, that is, the :math:`\textit{j}`\ th column of :math:`X`, for :math:`\textit{j} = 1,2,\ldots,r`. **berr** : float, ndarray, shape :math:`\left(\textit{nrhs}\right)` :math:`\mathrm{berr}[\textit{j}-1]` contains the component-wise backward error bound :math:`\beta` for the :math:`\textit{j}`\ th solution vector, that is, the :math:`\textit{j}`\ th column of :math:`X`, for :math:`\textit{j} = 1,2,\ldots,r`. .. _f07gv-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. .. _f07gv-py2-py-notes: **Notes** ``zpprfs`` returns the backward errors and estimated bounds on the forward errors for the solution of a complex Hermitian positive definite system of linear equations with multiple right-hand sides :math:`AX = B`, using packed storage. The function handles each right-hand side vector (stored as a column of the matrix :math:`B`) independently, so we describe the function of ``zpprfs`` in terms of a single right-hand side :math:`b` and solution :math:`x`. Given a computed solution :math:`x`, the function computes the `component-wise backward error` :math:`\beta`. This is the size of the smallest relative perturbation in each element of :math:`A` and :math:`b` such that :math:`x` is the exact solution of a perturbed system .. math:: \begin{array}{c}\left(A+\delta A\right)x = b+\delta b\\\left\lvert \delta a_{{ij}}\right\rvert \leq \beta \left\lvert a_{{ij}}\right\rvert \quad \text{ and }\quad \left\lvert \delta b_i\right\rvert \leq \beta \left\lvert b_i\right\rvert \text{.} \end{array} Then the function estimates a bound for the `component-wise forward error` in the computed solution, defined by: .. math:: \mathrm{max}_i\left\lvert x_i-\hat{x}_i\right\rvert /\mathrm{max}_i\left\lvert x_i\right\rvert where :math:`\hat{x}` is the true solution. For details of the method, see `the F07 Introduction <https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07intro.html>`__. .. _f07gv-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def zpptri(uplo, n, ap): r""" ``zpptri`` computes the inverse of a complex Hermitian positive definite matrix :math:`A`, where :math:`A` has been factorized by :meth:`zpptrf`, using packed storage. .. _f07gw-py2-py-doc: For full information please refer to the NAG Library document for f07gw https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07gwf.html .. _f07gw-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies how :math:`A` has been factorized. :math:`\mathrm{uplo} = \texttt{'U'}` :math:`A = U^\mathrm{H}U`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` :math:`A = LL^\mathrm{H}`, where :math:`L` is lower triangular. **n** : int :math:`n`, the order of the matrix :math:`A`. **ap** : complex, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` The Cholesky factor of :math:`A` stored in packed form, as returned by :meth:`zpptrf`. **Returns** **ap** : complex, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` The factorization is overwritten by the :math:`n\times n` matrix :math:`A^{-1}`. .. _f07gw-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Diagonal element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the Cholesky factor is zero; the Cholesky factor is singular and the inverse of :math:`A` cannot be computed. .. _f07gw-py2-py-notes: **Notes** ``zpptri`` is used to compute the inverse of a complex Hermitian positive definite matrix :math:`A`, the function must be preceded by a call to :meth:`zpptrf`, which computes the Cholesky factorization of :math:`A`, using packed storage. If :math:`\mathrm{uplo} = \texttt{'U'}`, :math:`A = U^\mathrm{H}U` and :math:`A^{-1}` is computed by first inverting :math:`U` and then forming :math:`\left(U^{-1}\right)U^{-\mathrm{H}}`. If :math:`\mathrm{uplo} = \texttt{'L'}`, :math:`A = LL^\mathrm{H}` and :math:`A^{-1}` is computed by first inverting :math:`L` and then forming :math:`L^{-\mathrm{H}}\left(L^{-1}\right)`. .. _f07gw-py2-py-references: **References** Du Croz, J J and Higham, N J, 1992, `Stability of methods for matrix inversion`, IMA J. Numer. Anal. (12), 1--19 """ raise NotImplementedError
[docs]def dpbsv(uplo, kd, ab, b): r""" ``dpbsv`` computes the solution to a real system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` symmetric positive definite band matrix of bandwidth :math:`\left(2k_d+1\right)` and :math:`X` and :math:`B` are :math:`n\times r` matrices. .. _f07ha-py2-py-doc: For full information please refer to the NAG Library document for f07ha https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07haf.html .. _f07ha-py2-py-parameters: **Parameters** **uplo** : str, length 1 If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored. If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored. **kd** : int :math:`k_d`, the number of superdiagonals of the matrix :math:`A` if :math:`\mathrm{uplo} = \texttt{'U'}`, or the number of subdiagonals if :math:`\mathrm{uplo} = \texttt{'L'}`. **ab** : float, array-like, shape :math:`\left(\mathrm{kd}+1, n\right)` The upper or lower triangle of the symmetric band matrix :math:`A`. **b** : float, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **ab** : float, ndarray, shape :math:`\left(\mathrm{kd}+1, n\right)` If no exception or warning is raised, the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{T}U` or :math:`A = LL^\mathrm{T}` of the band matrix :math:`A`, in the same storage format as :math:`A`. **b** : float, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`. .. _f07ha-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{kd}`. Constraint: :math:`\mathrm{kd}\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. (`errno` :math:`i > 0`) The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is not positive definite, so the factorization could not be completed, and the solution has not been computed. .. _f07ha-py2-py-notes: **Notes** ``dpbsv`` uses the Cholesky decomposition to factor :math:`A` as :math:`A = U^\mathrm{T}U` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LL^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` is an upper triangular band matrix, and :math:`L` is a lower triangular band matrix, with the same number of superdiagonals or subdiagonals as :math:`A`. The factored form of :math:`A` is then used to solve the system of equations :math:`AX = B`. .. _f07ha-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def dpbsvx(fact, uplo, n, kd, nrhs, ab, afb, equed, s, b): r""" ``dpbsvx`` uses the Cholesky factorization .. math:: A = U^\mathrm{T}U\quad \text{ or }\quad A = LL^\mathrm{T} to compute the solution to a real system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` symmetric positive definite band matrix of bandwidth :math:`\left(2k_d+1\right)` and :math:`X` and :math:`B` are :math:`n\times r` matrices. Error bounds on the solution and a condition estimate are also provided. .. _f07hb-py2-py-doc: For full information please refer to the NAG Library document for f07hb https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07hbf.html .. _f07hb-py2-py-parameters: **Parameters** **fact** : str, length 1 Specifies whether or not the factorized form of the matrix :math:`A` is supplied on entry, and if not, whether the matrix :math:`A` should be equilibrated before it is factorized. :math:`\mathrm{fact} = \texttt{'F'}` :math:`\mathrm{afb}` contains the factorized form of :math:`A`. If :math:`\mathrm{equed} = \texttt{'Y'}`, the matrix :math:`A` has been equilibrated with scaling factors given by :math:`\mathrm{s}`. :math:`\mathrm{ab}` and :math:`\mathrm{afb}` will not be modified. :math:`\mathrm{fact} = \texttt{'N'}` The matrix :math:`A` will be copied to :math:`\mathrm{afb}` and factorized. :math:`\mathrm{fact} = \texttt{'E'}` The matrix :math:`A` will be equilibrated if necessary, then copied to :math:`\mathrm{afb}` and factorized. **uplo** : str, length 1 If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored. If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored. **n** : int :math:`n`, the number of linear equations, i.e., the order of the matrix :math:`A`. **kd** : int :math:`k_d`, the number of superdiagonals of the matrix :math:`A` if :math:`\mathrm{uplo} = \texttt{'U'}`, or the number of subdiagonals if :math:`\mathrm{uplo} = \texttt{'L'}`. **nrhs** : int :math:`r`, the number of right-hand sides, i.e., the number of columns of the matrix :math:`B`. **ab** : float, array-like, shape :math:`\left(\mathrm{kd}+1, \mathrm{n}\right)` The upper or lower triangle of the symmetric band matrix :math:`A`, except if :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, in which case :math:`\mathrm{ab}` must contain the equilibrated matrix :math:`D_SAD_S`. **afb** : float, array-like, shape :math:`\left(\mathrm{kd}+1, \mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{afb}` contains the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{T}U` or :math:`A = LL^\mathrm{T}` of the band matrix :math:`A`, in the same storage format as :math:`A`. If :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{afb}` is the factorized form of the equilibrated matrix :math:`A`. **equed** : str, length 1 If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{equed}` need not be set. If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` must specify the form of the equilibration that was performed as follows: if :math:`\mathrm{equed} = \texttt{'N'}`, no equilibration; if :math:`\mathrm{equed} = \texttt{'Y'}`, equilibration was performed, i.e., :math:`A` has been replaced by :math:`D_SAD_S`. **s** : float, array-like, shape :math:`\left(\mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{s}` need not be set. If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{s}` must contain the scale factors, :math:`D_S`, for :math:`A`; each element of :math:`\mathrm{s}` must be positive. **b** : float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **ab** : float, ndarray, shape :math:`\left(\mathrm{kd}+1, \mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{ab}` is overwritten by :math:`D_SAD_S`. **afb** : float, ndarray, shape :math:`\left(\mathrm{kd}+1, \mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{afb}` returns the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{T}U` or :math:`A = LL^\mathrm{T}`. If :math:`\mathrm{fact} = \texttt{'E'}`, :math:`\mathrm{afb}` returns the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{T}U` or :math:`A = LL^\mathrm{T}` of the equilibrated matrix :math:`A` (see the description of :math:`\mathrm{ab}` for the form of the equilibrated matrix). **equed** : str, length 1 If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` is unchanged from entry. Otherwise, if no constraints are violated, :math:`\mathrm{equed}` specifies the form of the equilibration that was performed as specified above. **s** : float, ndarray, shape :math:`\left(\mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{s}` is unchanged from entry. Otherwise, if no constraints are violated and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{s}` contains the scale factors, :math:`D_S`, for :math:`A`; each element of :math:`\mathrm{s}` is positive. **b** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` If :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{b}` is not modified. If :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{b}` is overwritten by :math:`D_SB`. **x** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, the :math:`n\times r` solution matrix :math:`X` to the original system of equations. Note that the arrays :math:`A` and :math:`B` are modified on exit if :math:`\mathrm{equed} = \texttt{'Y'}`, and the solution to the equilibrated system is :math:`D_S^{-1}X`. **rcond** : float If no constraints are violated, an estimate of the reciprocal condition number of the matrix :math:`A` (after equilibration if that is performed), computed as :math:`\mathrm{rcond} = 1.0/\left(\left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\right)`. **ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the forward error bound for each computed solution vector, such that :math:`\left\lVert \hat{x}_j-x_j\right\rVert_\infty/\left\lVert x_j\right\rVert_\infty\leq \mathrm{ferr}[j-1]` where :math:`\hat{x}_j` is the :math:`j`\ th column of the computed solution returned in the array :math:`\mathrm{x}` and :math:`x_j` is the corresponding column of the exact solution :math:`X`. The estimate is as reliable as the estimate for :math:`\mathrm{rcond}`, and is almost always a slight overestimate of the true error. **berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the component-wise relative backward error of each computed solution vector :math:`\hat{x}_j` (i.e., the smallest relative change in any element of :math:`A` or :math:`B` that makes :math:`\hat{x}_j` an exact solution). .. _f07hb-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{fact}`. Constraint: :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\texttt{'N'}` or :math:`\texttt{'E'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\mathrm{kd}`. Constraint: :math:`\mathrm{kd}\geq 0`. (`errno` :math:`-5`) On entry, error in parameter :math:`\mathrm{nrhs}`. Constraint: :math:`\mathrm{nrhs}\geq 0`. (`errno` :math:`-10`) On entry, error in parameter :math:`\mathrm{equed}`. Constraint: :math:`\mathrm{equed} = \texttt{'N'}` or :math:`\texttt{'Y'}`. (`errno` :math:`-11`) On entry, error in parameter :math:`\mathrm{s}`. (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq \mathrm{n}\right)`) The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is not positive definite, so the factorization could not be completed, and the solution has not been computed. :math:`\mathrm{rcond} = 0.0` is returned. **Warns** **NagAlgorithmicWarning** (`errno` :math:`\mathrm{n}+1`) :math:`U` (or :math:`L`) is nonsingular, but :math:`\mathrm{rcond}` is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of :math:`\mathrm{rcond}` would suggest. .. _f07hb-py2-py-notes: **Notes** ``dpbsvx`` performs the following steps: (1) If :math:`\mathrm{fact} = \texttt{'E'}`, real diagonal scaling factors, :math:`D_S`, are computed to equilibrate the system: .. math:: \left(D_SAD_S\right)\left(D_S^{-1}X\right) = D_SB\text{.} Whether or not the system will be equilibrated depends on the scaling of the matrix :math:`A`, but if equilibration is used, :math:`A` is overwritten by :math:`D_SAD_S` and :math:`B\times D_SB`. (#) If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, the Cholesky decomposition is used to factor the matrix :math:`A` (after equilibration if :math:`\mathrm{fact} = \texttt{'E'}`) as :math:`A = U^\mathrm{T}U` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LL^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` is an upper triangular matrix and :math:`L` is a lower triangular matrix. (#) If the leading :math:`i\times i` principal minor of :math:`A` is not positive definite, then the function returns with :math:`\textit{errno} = i`. Otherwise, the factored form of :math:`A` is used to estimate the condition number of the matrix :math:`A`. If the reciprocal of the condition number is less than machine precision, :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1 is returned as a warning, but the function still goes on to solve for :math:`X` and compute error bounds as described below. (#) The system of equations is solved for :math:`X` using the factored form of :math:`A`. (#) Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for it. (#) If equilibration was used, the matrix :math:`X` is premultiplied by :math:`D_S` so that it solves the original system before equilibration. .. _f07hb-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def dpbtrf(uplo, kd, ab): r""" ``dpbtrf`` computes the Cholesky factorization of a real symmetric positive definite band matrix. .. _f07hd-py2-py-doc: For full information please refer to the NAG Library document for f07hd https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07hdf.html .. _f07hd-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies whether the upper or lower triangular part of :math:`A` is stored and how :math:`A` is to be factorized. :math:`\mathrm{uplo} = \texttt{'U'}` The upper triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`U^\mathrm{T}U`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` The lower triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`LL^\mathrm{T}`, where :math:`L` is lower triangular. **kd** : int :math:`k_d`, the number of superdiagonals or subdiagonals of the matrix :math:`A`. **ab** : float, array-like, shape :math:`\left(\mathrm{kd}+1, n\right)` The :math:`n\times n` symmetric positive definite band matrix :math:`A`. **Returns** **ab** : float, ndarray, shape :math:`\left(\mathrm{kd}+1, n\right)` The upper or lower triangle of :math:`A` is overwritten by the Cholesky factor :math:`U` or :math:`L` as specified by :math:`\mathrm{uplo}`, using the same storage format as described above. .. _f07hd-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{kd}`. Constraint: :math:`\mathrm{kd}\geq 0`. (`errno` :math:`i > 0`) The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` is not positive definite and the factorization could not be completed. Hence :math:`A` itself is not positive definite. This may indicate an error in forming the matrix :math:`A`. There is no function specifically designed to factorize a symmetric band matrix which is not positive definite; the matrix must be treated either as a nonsymmetric band matrix, by calling :meth:`dgbtrf` or as a full symmetric matrix, by calling :meth:`dsytrf`. .. _f07hd-py2-py-notes: **Notes** ``dpbtrf`` forms the Cholesky factorization of a real symmetric positive definite band matrix :math:`A` either as :math:`A = U^\mathrm{T}U` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LL^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` (or :math:`L`) is an upper (or lower) triangular band matrix with the same number of superdiagonals (or subdiagonals) as :math:`A`. .. _f07hd-py2-py-references: **References** Demmel, J W, 1989, `On floating-point errors in Cholesky`, LAPACK Working Note No. 14, University of Tennessee, Knoxville, https://www.netlib.org/lapack/lawnspdf/lawn14.pdf Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def dpbtrs(uplo, kd, ab, b): r""" ``dpbtrs`` solves a real symmetric positive definite band system of linear equations with multiple right-hand sides, .. math:: AX = B\text{,} where :math:`A` has been factorized by :meth:`dpbtrf`. .. _f07he-py2-py-doc: For full information please refer to the NAG Library document for f07he https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07hef.html .. _f07he-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies how :math:`A` has been factorized. :math:`\mathrm{uplo} = \texttt{'U'}` :math:`A = U^\mathrm{T}U`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` :math:`A = LL^\mathrm{T}`, where :math:`L` is lower triangular. **kd** : int :math:`k_d`, the number of superdiagonals or subdiagonals of the matrix :math:`A`. **ab** : float, array-like, shape :math:`\left(\mathrm{kd}+1, n\right)` The Cholesky factor of :math:`A`, as returned by :meth:`dpbtrf`. **b** : float, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **b** : float, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`. .. _f07he-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{kd}`. Constraint: :math:`\mathrm{kd}\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. .. _f07he-py2-py-notes: **Notes** ``dpbtrs`` is used to solve a real symmetric positive definite band system of linear equations :math:`AX = B`, the function must be preceded by a call to :meth:`dpbtrf` which computes the Cholesky factorization of :math:`A`. The solution :math:`X` is computed by forward and backward substitution. If :math:`\mathrm{uplo} = \texttt{'U'}`, :math:`A = U^\mathrm{T}U`, where :math:`U` is upper triangular; the solution :math:`X` is computed by solving :math:`U^\mathrm{T}Y = B` and then :math:`UX = Y`. If :math:`\mathrm{uplo} = \texttt{'L'}`, :math:`A = LL^\mathrm{T}`, where :math:`L` is lower triangular; the solution :math:`X` is computed by solving :math:`LY = B` and then :math:`L^\mathrm{T}X = Y`. .. _f07he-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def dpbequ(uplo, n, kd, ab): r""" ``dpbequ`` computes a diagonal scaling matrix :math:`S` intended to equilibrate a real :math:`n\times n` symmetric positive definite band matrix :math:`A`, with bandwidth :math:`\left(2k_d+1\right)`, and reduce its condition number. .. _f07hf-py2-py-doc: For full information please refer to the NAG Library document for f07hf https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07hff.html .. _f07hf-py2-py-parameters: **Parameters** **uplo** : str, length 1 Indicates whether the upper or lower triangular part of :math:`A` is stored in the array :math:`\mathrm{ab}`, as follows: :math:`\mathrm{uplo} = \texttt{'U'}` The upper triangle of :math:`A` is stored. :math:`\mathrm{uplo} = \texttt{'L'}` The lower triangle of :math:`A` is stored. **n** : int :math:`n`, the order of the matrix :math:`A`. **kd** : int :math:`k_d`, the number of superdiagonals of the matrix :math:`A` if :math:`\mathrm{uplo} = \texttt{'U'}`, or the number of subdiagonals if :math:`\mathrm{uplo} = \texttt{'L'}`. **ab** : float, array-like, shape :math:`\left(\mathrm{kd}+1, \mathrm{n}\right)` The upper or lower triangle of the symmetric positive definite band matrix :math:`A` whose scaling factors are to be computed. Only the elements of the array :math:`\mathrm{ab}` corresponding to the diagonal elements of :math:`A` are referenced. (Row :math:`\left(k_d+1\right)` of :math:`\mathrm{ab}` when :math:`\mathrm{uplo} = \texttt{'U'}`, row :math:`1` of :math:`\mathrm{ab}` when :math:`\mathrm{uplo} = \texttt{'L'}`.) **Returns** **s** : float, ndarray, shape :math:`\left(\mathrm{n}\right)` If no exception or warning is raised, :math:`\mathrm{s}` contains the diagonal elements of the scaling matrix :math:`S`. **scond** : float If no exception or warning is raised, :math:`\mathrm{scond}` contains the ratio of the smallest value of :math:`\mathrm{s}` to the largest value of :math:`\mathrm{s}`. If :math:`\mathrm{scond}\geq 0.1` and :math:`\mathrm{amax}` is neither too large nor too small, it is not worth scaling by :math:`S`. **amax** : float :math:`\mathrm{max}\left\lvert a_{{ij}}\right\rvert`. If :math:`\mathrm{amax}` is very close to overflow or underflow, the matrix :math:`A` should be scaled. .. _f07hf-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{kd}`. Constraint: :math:`\mathrm{kd}\geq 0`. (`errno` :math:`i > 0`) The :math:`\langle\mathit{\boldsymbol{value}}\rangle`\ th diagonal element of :math:`A` is not positive (and hence :math:`A` cannot be positive definite). .. _f07hf-py2-py-notes: **Notes** ``dpbequ`` computes a diagonal scaling matrix :math:`S` chosen so that .. math:: s_j = 1/\sqrt{a_{{jj}}}\text{.} This means that the matrix :math:`B` given by .. math:: B = SAS\text{,} has diagonal elements equal to unity. This in turn means that the condition number of :math:`B`, :math:`\kappa_2\left(B\right)`, is within a factor :math:`n` of the matrix of smallest possible condition number over all possible choices of diagonal scalings (see Corollary 7.6 of Higham (2002)). .. _f07hf-py2-py-references: **References** Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def dpbcon(uplo, kd, ab, anorm): r""" ``dpbcon`` estimates the condition number of a real symmetric positive definite band matrix :math:`A`, where :math:`A` has been factorized by :meth:`dpbtrf`. .. _f07hg-py2-py-doc: For full information please refer to the NAG Library document for f07hg https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07hgf.html .. _f07hg-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies how :math:`A` has been factorized. :math:`\mathrm{uplo} = \texttt{'U'}` :math:`A = U^\mathrm{T}U`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` :math:`A = LL^\mathrm{T}`, where :math:`L` is lower triangular. **kd** : int :math:`k_d`, the number of superdiagonals or subdiagonals of the matrix :math:`A`. **ab** : float, array-like, shape :math:`\left(\mathrm{kd}+1, n\right)` The Cholesky factor of :math:`A`, as returned by :meth:`dpbtrf`. **anorm** : float The :math:`1`-norm of the **original** matrix :math:`A`, which may be computed by calling :meth:`blas.dlansb <naginterfaces.library.blas.dlansb>` with its argument :math:`{\textit{norm}} = \texttt{'1'}`. :math:`\mathrm{anorm}` must be computed either **before** calling :meth:`dpbtrf` or else from a **copy** of the original matrix :math:`A`. **Returns** **rcond** : float An estimate of the reciprocal of the condition number of :math:`A`. :math:`\mathrm{rcond}` is set to zero if exact singularity is detected or the estimate underflows. If :math:`\mathrm{rcond}` is less than machine precision, :math:`A` is singular to working precision. .. _f07hg-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{kd}`. Constraint: :math:`\mathrm{kd}\geq 0`. (`errno` :math:`-6`) On entry, error in parameter :math:`\mathrm{anorm}`. Constraint: :math:`\mathrm{anorm}\geq 0.0`. .. _f07hg-py2-py-notes: **Notes** ``dpbcon`` estimates the condition number (in the :math:`1`-norm) of a real symmetric positive definite band matrix :math:`A`: .. math:: \kappa_1\left(A\right) = \left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\text{.} Since :math:`A` is symmetric, :math:`\kappa_1\left(A\right) = \kappa_{\infty }\left(A\right) = \left\lVert A\right\rVert_\infty\left\lVert A^{-1}\right\rVert_\infty`. Because :math:`\kappa_1\left(A\right)` is infinite if :math:`A` is singular, the function actually returns an estimate of the **reciprocal** of :math:`\kappa_1\left(A\right)`. The function should be preceded by a call to :meth:`blas.dlansb <naginterfaces.library.blas.dlansb>` to compute :math:`\left\lVert A\right\rVert_1` and a call to :meth:`dpbtrf` to compute the Cholesky factorization of :math:`A`. The function then uses Higham's implementation of Hager's method (see Higham (1988)) to estimate :math:`\left\lVert A^{-1}\right\rVert_1`. .. _f07hg-py2-py-references: **References** Higham, N J, 1988, `FORTRAN codes for estimating the one-norm of a real or complex matrix, with applications to condition estimation`, ACM Trans. Math. Software (14), 381--396 """ raise NotImplementedError
[docs]def dpbrfs(uplo, kd, nrhs, ab, afb, b, x): r""" ``dpbrfs`` returns error bounds for the solution of a real symmetric positive definite band system of linear equations with multiple right-hand sides, :math:`AX = B`. It improves the solution by iterative refinement, in order to reduce the backward error as much as possible. .. _f07hh-py2-py-doc: For full information please refer to the NAG Library document for f07hh https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07hhf.html .. _f07hh-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies whether the upper or lower triangular part of :math:`A` is stored and how :math:`A` is to be factorized. :math:`\mathrm{uplo} = \texttt{'U'}` The upper triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`U^\mathrm{T}U`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` The lower triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`LL^\mathrm{T}`, where :math:`L` is lower triangular. **kd** : int :math:`k_d`, the number of superdiagonals or subdiagonals of the matrix :math:`A`. **nrhs** : int :math:`r`, the number of right-hand sides. **ab** : float, array-like, shape :math:`\left(\mathrm{kd}+1, n\right)` The :math:`n\times n` original symmetric positive definite band matrix :math:`A` as supplied to :meth:`dpbtrf`. **afb** : float, array-like, shape :math:`\left(\mathrm{kd}+1, n\right)` The Cholesky factor of :math:`A`, as returned by :meth:`dpbtrf`. **b** : float, array-like, shape :math:`\left(n, \mathrm{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **x** : float, array-like, shape :math:`\left(n, \mathrm{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`, as returned by :meth:`dpbtrs`. **Returns** **x** : float, ndarray, shape :math:`\left(n, \mathrm{nrhs}\right)` The improved solution matrix :math:`X`. **ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` :math:`\mathrm{ferr}[\textit{j}-1]` contains an estimated error bound for the :math:`\textit{j}`\ th solution vector, that is, the :math:`\textit{j}`\ th column of :math:`X`, for :math:`\textit{j} = 1,2,\ldots,r`. **berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` :math:`\mathrm{berr}[\textit{j}-1]` contains the component-wise backward error bound :math:`\beta` for the :math:`\textit{j}`\ th solution vector, that is, the :math:`\textit{j}`\ th column of :math:`X`, for :math:`\textit{j} = 1,2,\ldots,r`. .. _f07hh-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{kd}`. Constraint: :math:`\mathrm{kd}\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\mathrm{nrhs}`. Constraint: :math:`\mathrm{nrhs}\geq 0`. .. _f07hh-py2-py-notes: **Notes** ``dpbrfs`` returns the backward errors and estimated bounds on the forward errors for the solution of a real symmetric positive definite band system of linear equations with multiple right-hand sides :math:`AX = B`. The function handles each right-hand side vector (stored as a column of the matrix :math:`B`) independently, so we describe the function of ``dpbrfs`` in terms of a single right-hand side :math:`b` and solution :math:`x`. Given a computed solution :math:`x`, the function computes the `component-wise backward error` :math:`\beta`. This is the size of the smallest relative perturbation in each element of :math:`A` and :math:`b` such that :math:`x` is the exact solution of a perturbed system .. math:: \begin{array}{c}\left(A+\delta A\right)x = b+\delta b\\\left\lvert \delta a_{{ij}}\right\rvert \leq \beta \left\lvert a_{{ij}}\right\rvert \quad \text{ and }\quad \left\lvert \delta b_i\right\rvert \leq \beta \left\lvert b_i\right\rvert \text{.} \end{array} Then the function estimates a bound for the `component-wise forward error` in the computed solution, defined by: .. math:: \mathrm{max}_i\left\lvert x_i-\hat{x}_i\right\rvert /\mathrm{max}_i\left\lvert x_i\right\rvert where :math:`\hat{x}` is the true solution. For details of the method, see `the F07 Introduction <https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07intro.html>`__. .. _f07hh-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def zpbsv(uplo, kd, ab, b): r""" ``zpbsv`` computes the solution to a complex system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` Hermitian positive definite band matrix of bandwidth :math:`\left(2k_d+1\right)` and :math:`X` and :math:`B` are :math:`n\times r` matrices. .. _f07hn-py2-py-doc: For full information please refer to the NAG Library document for f07hn https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07hnf.html .. _f07hn-py2-py-parameters: **Parameters** **uplo** : str, length 1 If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored. If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored. **kd** : int :math:`k_d`, the number of superdiagonals of the matrix :math:`A` if :math:`\mathrm{uplo} = \texttt{'U'}`, or the number of subdiagonals if :math:`\mathrm{uplo} = \texttt{'L'}`. **ab** : complex, array-like, shape :math:`\left(\mathrm{kd}+1, n\right)` The upper or lower triangle of the Hermitian band matrix :math:`A`. **b** : complex, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **ab** : complex, ndarray, shape :math:`\left(\mathrm{kd}+1, n\right)` If no exception or warning is raised, the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{H}U` or :math:`A = LL^\mathrm{H}` of the band matrix :math:`A`, in the same storage format as :math:`A`. **b** : complex, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`. .. _f07hn-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{kd}`. Constraint: :math:`\mathrm{kd}\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. (`errno` :math:`i > 0`) The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is not positive definite, so the factorization could not be completed, and the solution has not been computed. .. _f07hn-py2-py-notes: **Notes** ``zpbsv`` uses the Cholesky decomposition to factor :math:`A` as :math:`A = U^\mathrm{H}U` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LL^\mathrm{H}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` is an upper triangular band matrix, and :math:`L` is a lower triangular band matrix, with the same number of superdiagonals or subdiagonals as :math:`A`. The factored form of :math:`A` is then used to solve the system of equations :math:`AX = B`. .. _f07hn-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def zpbsvx(fact, uplo, n, kd, nrhs, ab, afb, equed, s, b): r""" ``zpbsvx`` uses the Cholesky factorization .. math:: A = U^\mathrm{H}U\quad \text{ or }\quad A = LL^\mathrm{H} to compute the solution to a complex system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` Hermitian positive definite band matrix of bandwidth :math:`\left(2k_d+1\right)` and :math:`X` and :math:`B` are :math:`n\times r` matrices. Error bounds on the solution and a condition estimate are also provided. .. _f07hp-py2-py-doc: For full information please refer to the NAG Library document for f07hp https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07hpf.html .. _f07hp-py2-py-parameters: **Parameters** **fact** : str, length 1 Specifies whether or not the factorized form of the matrix :math:`A` is supplied on entry, and if not, whether the matrix :math:`A` should be equilibrated before it is factorized. :math:`\mathrm{fact} = \texttt{'F'}` :math:`\mathrm{afb}` contains the factorized form of :math:`A`. If :math:`\mathrm{equed} = \texttt{'Y'}`, the matrix :math:`A` has been equilibrated with scaling factors given by :math:`\mathrm{s}`. :math:`\mathrm{ab}` and :math:`\mathrm{afb}` will not be modified. :math:`\mathrm{fact} = \texttt{'N'}` The matrix :math:`A` will be copied to :math:`\mathrm{afb}` and factorized. :math:`\mathrm{fact} = \texttt{'E'}` The matrix :math:`A` will be equilibrated if necessary, then copied to :math:`\mathrm{afb}` and factorized. **uplo** : str, length 1 If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored. If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored. **n** : int :math:`n`, the number of linear equations, i.e., the order of the matrix :math:`A`. **kd** : int :math:`k_d`, the number of superdiagonals of the matrix :math:`A` if :math:`\mathrm{uplo} = \texttt{'U'}`, or the number of subdiagonals if :math:`\mathrm{uplo} = \texttt{'L'}`. **nrhs** : int :math:`r`, the number of right-hand sides, i.e., the number of columns of the matrix :math:`B`. **ab** : complex, array-like, shape :math:`\left(\mathrm{kd}+1, \mathrm{n}\right)` The upper or lower triangle of the Hermitian band matrix :math:`A`, except if :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, in which case :math:`\mathrm{ab}` must contain the equilibrated matrix :math:`D_SAD_S`. **afb** : complex, array-like, shape :math:`\left(\mathrm{kd}+1, \mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{afb}` contains the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{H}U` or :math:`A = LL^\mathrm{H}` of the band matrix :math:`A`, in the same storage format as :math:`A`. If :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{afb}` is the factorized form of the equilibrated matrix :math:`A`. **equed** : str, length 1 If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{equed}` need not be set. If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` must specify the form of the equilibration that was performed as follows: if :math:`\mathrm{equed} = \texttt{'N'}`, no equilibration; if :math:`\mathrm{equed} = \texttt{'Y'}`, equilibration was performed, i.e., :math:`A` has been replaced by :math:`D_SAD_S`. **s** : float, array-like, shape :math:`\left(\mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{s}` need not be set. If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{s}` must contain the scale factors, :math:`D_S`, for :math:`A`; each element of :math:`\mathrm{s}` must be positive. **b** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **ab** : complex, ndarray, shape :math:`\left(\mathrm{kd}+1, \mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{ab}` is overwritten by :math:`D_SAD_S`. **afb** : complex, ndarray, shape :math:`\left(\mathrm{kd}+1, \mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{afb}` returns the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{H}U` or :math:`A = LL^\mathrm{H}`. If :math:`\mathrm{fact} = \texttt{'E'}`, :math:`\mathrm{afb}` returns the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{H}U` or :math:`A = LL^\mathrm{H}` of the equilibrated matrix :math:`A` (see the description of :math:`\mathrm{ab}` for the form of the equilibrated matrix). **equed** : str, length 1 If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` is unchanged from entry. Otherwise, if no constraints are violated, :math:`\mathrm{equed}` specifies the form of the equilibration that was performed as specified above. **s** : float, ndarray, shape :math:`\left(\mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{s}` is unchanged from entry. Otherwise, if no constraints are violated and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{s}` contains the scale factors, :math:`D_S`, for :math:`A`; each element of :math:`\mathrm{s}` is positive. **b** : complex, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` If :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{b}` is not modified. If :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{b}` is overwritten by :math:`D_SB`. **x** : complex, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, the :math:`n\times r` solution matrix :math:`X` to the original system of equations. Note that the arrays :math:`A` and :math:`B` are modified on exit if :math:`\mathrm{equed} = \texttt{'Y'}`, and the solution to the equilibrated system is :math:`D_S^{-1}X`. **rcond** : float If no constraints are violated, an estimate of the reciprocal condition number of the matrix :math:`A` (after equilibration if that is performed), computed as :math:`\mathrm{rcond} = 1.0/\left(\left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\right)`. **ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the forward error bound for each computed solution vector, such that :math:`\left\lVert \hat{x}_j-x_j\right\rVert_\infty/\left\lVert x_j\right\rVert_\infty\leq \mathrm{ferr}[j-1]` where :math:`\hat{x}_j` is the :math:`j`\ th column of the computed solution returned in the array :math:`\mathrm{x}` and :math:`x_j` is the corresponding column of the exact solution :math:`X`. The estimate is as reliable as the estimate for :math:`\mathrm{rcond}`, and is almost always a slight overestimate of the true error. **berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the component-wise relative backward error of each computed solution vector :math:`\hat{x}_j` (i.e., the smallest relative change in any element of :math:`A` or :math:`B` that makes :math:`\hat{x}_j` an exact solution). .. _f07hp-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{fact}`. Constraint: :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\texttt{'N'}` or :math:`\texttt{'E'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\mathrm{kd}`. Constraint: :math:`\mathrm{kd}\geq 0`. (`errno` :math:`-5`) On entry, error in parameter :math:`\mathrm{nrhs}`. Constraint: :math:`\mathrm{nrhs}\geq 0`. (`errno` :math:`-10`) On entry, error in parameter :math:`\mathrm{equed}`. Constraint: :math:`\mathrm{equed} = \texttt{'N'}` or :math:`\texttt{'Y'}`. (`errno` :math:`-11`) On entry, error in parameter :math:`\mathrm{s}`. (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq \mathrm{n}\right)`) The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is not positive definite, so the factorization could not be completed, and the solution has not been computed. :math:`\mathrm{rcond} = 0.0` is returned. **Warns** **NagAlgorithmicWarning** (`errno` :math:`\mathrm{n}+1`) :math:`U` (or :math:`L`) is nonsingular, but :math:`\mathrm{rcond}` is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of :math:`\mathrm{rcond}` would suggest. .. _f07hp-py2-py-notes: **Notes** ``zpbsvx`` performs the following steps: (1) If :math:`\mathrm{fact} = \texttt{'E'}`, real diagonal scaling factors, :math:`D_S`, are computed to equilibrate the system: .. math:: \left(D_SAD_S\right)\left(D_S^{-1}X\right) = D_SB\text{.} Whether or not the system will be equilibrated depends on the scaling of the matrix :math:`A`, but if equilibration is used, :math:`A` is overwritten by :math:`D_SAD_S` and :math:`B\times D_SB`. (#) If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, the Cholesky decomposition is used to factor the matrix :math:`A` (after equilibration if :math:`\mathrm{fact} = \texttt{'E'}`) as :math:`A = U^\mathrm{H}U` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LL^\mathrm{H}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` is an upper triangular matrix and :math:`L` is a lower triangular matrix. (#) If the leading :math:`i\times i` principal minor of :math:`A` is not positive definite, then the function returns with :math:`\textit{errno} = i`. Otherwise, the factored form of :math:`A` is used to estimate the condition number of the matrix :math:`A`. If the reciprocal of the condition number is less than machine precision, :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1 is returned as a warning, but the function still goes on to solve for :math:`X` and compute error bounds as described below. (#) The system of equations is solved for :math:`X` using the factored form of :math:`A`. (#) Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for it. (#) If equilibration was used, the matrix :math:`X` is premultiplied by :math:`D_S` so that it solves the original system before equilibration. .. _f07hp-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def zpbtrf(uplo, kd, ab): r""" ``zpbtrf`` computes the Cholesky factorization of a complex Hermitian positive definite band matrix. .. _f07hr-py2-py-doc: For full information please refer to the NAG Library document for f07hr https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07hrf.html .. _f07hr-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies whether the upper or lower triangular part of :math:`A` is stored and how :math:`A` is to be factorized. :math:`\mathrm{uplo} = \texttt{'U'}` The upper triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`U^\mathrm{H}U`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` The lower triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`LL^\mathrm{H}`, where :math:`L` is lower triangular. **kd** : int :math:`k_d`, the number of superdiagonals or subdiagonals of the matrix :math:`A`. **ab** : complex, array-like, shape :math:`\left(\mathrm{kd}+1, n\right)` The :math:`n\times n` Hermitian positive definite band matrix :math:`A`. **Returns** **ab** : complex, ndarray, shape :math:`\left(\mathrm{kd}+1, n\right)` The upper or lower triangle of :math:`A` is overwritten by the Cholesky factor :math:`U` or :math:`L` as specified by :math:`\mathrm{uplo}`, using the same storage format as described above. .. _f07hr-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{kd}`. Constraint: :math:`\mathrm{kd}\geq 0`. (`errno` :math:`i > 0`) The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` is not positive definite and the factorization could not be completed. Hence :math:`A` itself is not positive definite. This may indicate an error in forming the matrix :math:`A`. There is no function specifically designed to factorize a Hermitian band matrix which is not positive definite; the matrix must be treated either as a nonsymmetric band matrix, by calling :meth:`zgbtrf` or as a full Hermitian matrix, by calling :meth:`zhetrf`. .. _f07hr-py2-py-notes: **Notes** ``zpbtrf`` forms the Cholesky factorization of a complex Hermitian positive definite band matrix :math:`A` either as :math:`A = U^\mathrm{H}U` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LL^\mathrm{H}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` (or :math:`L`) is an upper (or lower) triangular band matrix with the same number of superdiagonals (or subdiagonals) as :math:`A`. .. _f07hr-py2-py-references: **References** Demmel, J W, 1989, `On floating-point errors in Cholesky`, LAPACK Working Note No. 14, University of Tennessee, Knoxville, https://www.netlib.org/lapack/lawnspdf/lawn14.pdf Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def zpbtrs(uplo, kd, ab, b): r""" ``zpbtrs`` solves a complex Hermitian positive definite band system of linear equations with multiple right-hand sides, .. math:: AX = B\text{,} where :math:`A` has been factorized by :meth:`zpbtrf`. .. _f07hs-py2-py-doc: For full information please refer to the NAG Library document for f07hs https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07hsf.html .. _f07hs-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies how :math:`A` has been factorized. :math:`\mathrm{uplo} = \texttt{'U'}` :math:`A = U^\mathrm{H}U`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` :math:`A = LL^\mathrm{H}`, where :math:`L` is lower triangular. **kd** : int :math:`k_d`, the number of superdiagonals or subdiagonals of the matrix :math:`A`. **ab** : complex, array-like, shape :math:`\left(\mathrm{kd}+1, n\right)` The Cholesky factor of :math:`A`, as returned by :meth:`zpbtrf`. **b** : complex, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **b** : complex, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`. .. _f07hs-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{kd}`. Constraint: :math:`\mathrm{kd}\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. .. _f07hs-py2-py-notes: **Notes** ``zpbtrs`` is used to solve a complex Hermitian positive definite band system of linear equations :math:`AX = B`, the function must be preceded by a call to :meth:`zpbtrf` which computes the Cholesky factorization of :math:`A`. The solution :math:`X` is computed by forward and backward substitution. If :math:`\mathrm{uplo} = \texttt{'U'}`, :math:`A = U^\mathrm{H}U`, where :math:`U` is upper triangular; the solution :math:`X` is computed by solving :math:`U^\mathrm{H}Y = B` and then :math:`UX = Y`. If :math:`\mathrm{uplo} = \texttt{'L'}`, :math:`A = LL^\mathrm{H}`, where :math:`L` is lower triangular; the solution :math:`X` is computed by solving :math:`LY = B` and then :math:`L^\mathrm{H}X = Y`. .. _f07hs-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def zpbequ(uplo, n, kd, ab): r""" ``zpbequ`` computes a diagonal scaling matrix :math:`S` intended to equilibrate a complex :math:`n\times n` Hermitian positive definite band matrix :math:`A`, with bandwidth :math:`\left(2k_d+1\right)`, and reduce its condition number. .. _f07ht-py2-py-doc: For full information please refer to the NAG Library document for f07ht https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07htf.html .. _f07ht-py2-py-parameters: **Parameters** **uplo** : str, length 1 Indicates whether the upper or lower triangular part of :math:`A` is stored in the array :math:`\mathrm{ab}`, as follows: :math:`\mathrm{uplo} = \texttt{'U'}` The upper triangle of :math:`A` is stored. :math:`\mathrm{uplo} = \texttt{'L'}` The lower triangle of :math:`A` is stored. **n** : int :math:`n`, the order of the matrix :math:`A`. **kd** : int :math:`k_d`, the number of superdiagonals of the matrix :math:`A` if :math:`\mathrm{uplo} = \texttt{'U'}`, or the number of subdiagonals if :math:`\mathrm{uplo} = \texttt{'L'}`. **ab** : complex, array-like, shape :math:`\left(\mathrm{kd}+1, \mathrm{n}\right)` The upper or lower triangle of the Hermitian positive definite band matrix :math:`A` whose scaling factors are to be computed. Only the elements of the array :math:`\mathrm{ab}` corresponding to the diagonal elements of :math:`A` are referenced. (Row :math:`\left(k_d+1\right)` of :math:`\mathrm{ab}` when :math:`\mathrm{uplo} = \texttt{'U'}`, row :math:`1` of :math:`\mathrm{ab}` when :math:`\mathrm{uplo} = \texttt{'L'}`.) **Returns** **s** : float, ndarray, shape :math:`\left(\mathrm{n}\right)` If no exception or warning is raised, :math:`\mathrm{s}` contains the diagonal elements of the scaling matrix :math:`S`. **scond** : float If no exception or warning is raised, :math:`\mathrm{scond}` contains the ratio of the smallest value of :math:`\mathrm{s}` to the largest value of :math:`\mathrm{s}`. If :math:`\mathrm{scond}\geq 0.1` and :math:`\mathrm{amax}` is neither too large nor too small, it is not worth scaling by :math:`S`. **amax** : float :math:`\mathrm{max}\left\lvert a_{{ij}}\right\rvert`. If :math:`\mathrm{amax}` is very close to overflow or underflow, the matrix :math:`A` should be scaled. .. _f07ht-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{kd}`. Constraint: :math:`\mathrm{kd}\geq 0`. (`errno` :math:`i > 0`) The :math:`\langle\mathit{\boldsymbol{value}}\rangle`\ th diagonal element of :math:`A` is not positive (and hence :math:`A` cannot be positive definite). .. _f07ht-py2-py-notes: **Notes** ``zpbequ`` computes a diagonal scaling matrix :math:`S` chosen so that .. math:: s_j = 1/\sqrt{a_{{jj}}}\text{.} This means that the matrix :math:`B` given by .. math:: B = SAS\text{,} has diagonal elements equal to unity. This in turn means that the condition number of :math:`B`, :math:`\kappa_2\left(B\right)`, is within a factor :math:`n` of the matrix of smallest possible condition number over all possible choices of diagonal scalings (see Corollary 7.6 of Higham (2002)). .. _f07ht-py2-py-references: **References** Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def zpbcon(uplo, kd, ab, anorm): r""" ``zpbcon`` estimates the condition number of a complex Hermitian positive definite band matrix :math:`A`, where :math:`A` has been factorized by :meth:`zpbtrf`. .. _f07hu-py2-py-doc: For full information please refer to the NAG Library document for f07hu https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07huf.html .. _f07hu-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies how :math:`A` has been factorized. :math:`\mathrm{uplo} = \texttt{'U'}` :math:`A = U^\mathrm{H}U`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` :math:`A = LL^\mathrm{H}`, where :math:`L` is lower triangular. **kd** : int :math:`k_d`, the number of superdiagonals or subdiagonals of the matrix :math:`A`. **ab** : complex, array-like, shape :math:`\left(\mathrm{kd}+1, n\right)` The Cholesky factor of :math:`A`, as returned by :meth:`zpbtrf`. **anorm** : float The :math:`1`-norm of the **original** matrix :math:`A`, which may be computed by calling :meth:`blas.zlanhb <naginterfaces.library.blas.zlanhb>` with its argument :math:`{\textit{norm}} = \texttt{'1'}`. :math:`\mathrm{anorm}` must be computed either **before** calling :meth:`zpbtrf` or else from a **copy** of the original matrix :math:`A`. **Returns** **rcond** : float An estimate of the reciprocal of the condition number of :math:`A`. :math:`\mathrm{rcond}` is set to zero if exact singularity is detected or the estimate underflows. If :math:`\mathrm{rcond}` is less than machine precision, :math:`A` is singular to working precision. .. _f07hu-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{kd}`. Constraint: :math:`\mathrm{kd}\geq 0`. (`errno` :math:`-6`) On entry, error in parameter :math:`\mathrm{anorm}`. Constraint: :math:`\mathrm{anorm}\geq 0.0`. .. _f07hu-py2-py-notes: **Notes** ``zpbcon`` estimates the condition number (in the :math:`1`-norm) of a complex Hermitian positive definite band matrix :math:`A`: .. math:: \kappa_1\left(A\right) = \left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\text{.} Since :math:`A` is Hermitian, :math:`\kappa_1\left(A\right) = \kappa_{\infty }\left(A\right) = \left\lVert A\right\rVert_\infty\left\lVert A^{-1}\right\rVert_\infty`. Because :math:`\kappa_1\left(A\right)` is infinite if :math:`A` is singular, the function actually returns an estimate of the **reciprocal** of :math:`\kappa_1\left(A\right)`. The function should be preceded by a call to :meth:`blas.zlanhb <naginterfaces.library.blas.zlanhb>` to compute :math:`\left\lVert A\right\rVert_1` and a call to :meth:`zpbtrf` to compute the Cholesky factorization of :math:`A`. The function then uses Higham's implementation of Hager's method (see Higham (1988)) to estimate :math:`\left\lVert A^{-1}\right\rVert_1`. .. _f07hu-py2-py-references: **References** Higham, N J, 1988, `FORTRAN codes for estimating the one-norm of a real or complex matrix, with applications to condition estimation`, ACM Trans. Math. Software (14), 381--396 """ raise NotImplementedError
[docs]def zpbrfs(uplo, kd, nrhs, ab, afb, b, x): r""" ``zpbrfs`` returns error bounds for the solution of a complex Hermitian positive definite band system of linear equations with multiple right-hand sides, :math:`AX = B`. It improves the solution by iterative refinement, in order to reduce the backward error as much as possible. .. _f07hv-py2-py-doc: For full information please refer to the NAG Library document for f07hv https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07hvf.html .. _f07hv-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies whether the upper or lower triangular part of :math:`A` is stored and how :math:`A` is to be factorized. :math:`\mathrm{uplo} = \texttt{'U'}` The upper triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`U^\mathrm{H}U`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` The lower triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`LL^\mathrm{H}`, where :math:`L` is lower triangular. **kd** : int :math:`k_d`, the number of superdiagonals or subdiagonals of the matrix :math:`A`. **nrhs** : int :math:`r`, the number of right-hand sides. **ab** : complex, array-like, shape :math:`\left(\mathrm{kd}+1, n\right)` The :math:`n\times n` original Hermitian positive definite band matrix :math:`A` as supplied to :meth:`zpbtrf`. **afb** : complex, array-like, shape :math:`\left(\mathrm{kd}+1, n\right)` The Cholesky factor of :math:`A`, as returned by :meth:`zpbtrf`. **b** : complex, array-like, shape :math:`\left(n, \mathrm{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **x** : complex, array-like, shape :math:`\left(n, \mathrm{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`, as returned by :meth:`zpbtrs`. **Returns** **x** : complex, ndarray, shape :math:`\left(n, \mathrm{nrhs}\right)` The improved solution matrix :math:`X`. **ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` :math:`\mathrm{ferr}[\textit{j}-1]` contains an estimated error bound for the :math:`\textit{j}`\ th solution vector, that is, the :math:`\textit{j}`\ th column of :math:`X`, for :math:`\textit{j} = 1,2,\ldots,r`. **berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` :math:`\mathrm{berr}[\textit{j}-1]` contains the component-wise backward error bound :math:`\beta` for the :math:`\textit{j}`\ th solution vector, that is, the :math:`\textit{j}`\ th column of :math:`X`, for :math:`\textit{j} = 1,2,\ldots,r`. .. _f07hv-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{kd}`. Constraint: :math:`\mathrm{kd}\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\mathrm{nrhs}`. Constraint: :math:`\mathrm{nrhs}\geq 0`. .. _f07hv-py2-py-notes: **Notes** ``zpbrfs`` returns the backward errors and estimated bounds on the forward errors for the solution of a complex Hermitian positive definite band system of linear equations with multiple right-hand sides :math:`AX = B`. The function handles each right-hand side vector (stored as a column of the matrix :math:`B`) independently, so we describe the function of ``zpbrfs`` in terms of a single right-hand side :math:`b` and solution :math:`x`. Given a computed solution :math:`x`, the function computes the `component-wise backward error` :math:`\beta`. This is the size of the smallest relative perturbation in each element of :math:`A` and :math:`b` such that :math:`x` is the exact solution of a perturbed system .. math:: \begin{array}{c}\left(A+\delta A\right)x = b+\delta b\\\left\lvert \delta a_{{ij}}\right\rvert \leq \beta \left\lvert a_{{ij}}\right\rvert \quad \text{ and }\quad \left\lvert \delta b_i\right\rvert \leq \beta \left\lvert b_i\right\rvert \text{.} \end{array} Then the function estimates a bound for the `component-wise forward error` in the computed solution, defined by: .. math:: \mathrm{max}_i\left\lvert x_i-\hat{x}_i\right\rvert /\mathrm{max}_i\left\lvert x_i\right\rvert where :math:`\hat{x}` is the true solution. For details of the method, see `the F07 Introduction <https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07intro.html>`__. .. _f07hv-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def dptsv(d, e, b): r""" ``dptsv`` computes the solution to a real system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` symmetric positive definite tridiagonal matrix, and :math:`X` and :math:`B` are :math:`n\times r` matrices. .. _f07ja-py2-py-doc: For full information please refer to the NAG Library document for f07ja https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07jaf.html .. _f07ja-py2-py-parameters: **Parameters** **d** : float, array-like, shape :math:`\left(n\right)` The :math:`n` diagonal elements of the tridiagonal matrix :math:`A`. **e** : float, array-like, shape :math:`\left(n-1\right)` The :math:`\left(n-1\right)` subdiagonal elements of the tridiagonal matrix :math:`A`. **b** : float, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **d** : float, ndarray, shape :math:`\left(n\right)` The :math:`n` diagonal elements of the diagonal matrix :math:`D` from the factorization :math:`A = LDL^\mathrm{T}`. **e** : float, ndarray, shape :math:`\left(n-1\right)` The :math:`\left(n-1\right)` subdiagonal elements of the unit bidiagonal factor :math:`L` from the :math:`LDL^\mathrm{T}` factorization of :math:`A`. (:math:`\mathrm{e}` can also be regarded as the superdiagonal of the unit bidiagonal factor :math:`U` from the :math:`U^\mathrm{T}DU` factorization of :math:`A`.) **b** : float, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`. .. _f07ja-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. (`errno` :math:`i > 0`) The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` is not positive definite, and the solution has not been computed. The factorization has not been completed unless :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`. .. _f07ja-py2-py-notes: **Notes** ``dptsv`` factors :math:`A` as :math:`A = LDL^\mathrm{T}`. The factored form of :math:`A` is then used to solve the system of equations. .. _f07ja-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def dptsvx(fact, nrhs, d, e, df, ef, b): r""" ``dptsvx`` uses the factorization .. math:: A = LDL^\mathrm{T} to compute the solution to a real system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` symmetric positive definite tridiagonal matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices. Error bounds on the solution and a condition estimate are also provided. .. _f07jb-py2-py-doc: For full information please refer to the NAG Library document for f07jb https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07jbf.html .. _f07jb-py2-py-parameters: **Parameters** **fact** : str, length 1 Specifies whether or not the factorized form of the matrix :math:`A` has been supplied. :math:`\mathrm{fact} = \texttt{'F'}` :math:`\mathrm{df}` and :math:`\mathrm{ef}` contain the factorized form of the matrix :math:`A`. :math:`\mathrm{df}` and :math:`\mathrm{ef}` will not be modified. :math:`\mathrm{fact} = \texttt{'N'}` The matrix :math:`A` will be copied to :math:`\mathrm{df}` and :math:`\mathrm{ef}` and factorized. **nrhs** : int :math:`r`, the number of right-hand sides, i.e., the number of columns of the matrix :math:`B`. **d** : float, array-like, shape :math:`\left(n\right)` The :math:`n` diagonal elements of the tridiagonal matrix :math:`A`. **e** : float, array-like, shape :math:`\left(n-1\right)` The :math:`\left(n-1\right)` subdiagonal elements of the tridiagonal matrix :math:`A`. **df** : float, array-like, shape :math:`\left(n\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{df}` must contain the :math:`n` diagonal elements of the diagonal matrix :math:`D` from the :math:`LDL^\mathrm{T}` factorization of :math:`A`. **ef** : float, array-like, shape :math:`\left(n-1\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{ef}` must contain the :math:`\left(n-1\right)` subdiagonal elements of the unit bidiagonal factor :math:`L` from the :math:`LDL^\mathrm{T}` factorization of :math:`A`. **b** : float, array-like, shape :math:`\left(n, \mathrm{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **df** : float, ndarray, shape :math:`\left(n\right)` If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{df}` contains the :math:`n` diagonal elements of the diagonal matrix :math:`D` from the :math:`LDL^\mathrm{T}` factorization of :math:`A`. **ef** : float, ndarray, shape :math:`\left(n-1\right)` If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{ef}` contains the :math:`\left(n-1\right)` subdiagonal elements of the unit bidiagonal factor :math:`L` from the :math:`LDL^\mathrm{T}` factorization of :math:`A`. **x** : float, ndarray, shape :math:`\left(n, \mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, the :math:`n\times r` solution matrix :math:`X`. **rcond** : float The reciprocal condition number of the matrix :math:`A`. If :math:`\mathrm{rcond}` is less than the machine precision (in particular, if :math:`\mathrm{rcond} = 0.0`), the matrix is singular to working precision. This condition is indicated by a return code of :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1. **ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` The forward error bound for each solution vector :math:`\hat{x}_j` (the :math:`j`\ th column of the solution matrix :math:`X`). If :math:`x_j` is the true solution corresponding to :math:`\hat{x}_j`, :math:`\mathrm{ferr}[j-1]` is an estimated upper bound for the magnitude of the largest element in (:math:`\hat{x}_j-x_j`) divided by the magnitude of the largest element in :math:`\hat{x}_j`. **berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` The component-wise relative backward error of each solution vector :math:`\hat{x}_j` (i.e., the smallest relative change in any element of :math:`A` or :math:`B` that makes :math:`\hat{x}_j` an exact solution). .. _f07jb-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{fact}`. Constraint: :math:`\mathrm{fact} = \texttt{'F'}` or :math:`\texttt{'N'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{nrhs}`. Constraint: :math:`\mathrm{nrhs}\geq 0`. (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq n\right)`) The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is not positive definite, so the factorization could not be completed, and the solution has not been computed. :math:`\mathrm{rcond} = 0.0` is returned. **Warns** **NagAlgorithmicWarning** (`errno` :math:`n+1`) :math:`D` is nonsingular, but :math:`\mathrm{rcond}` is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of :math:`\mathrm{rcond}` would suggest. .. _f07jb-py2-py-notes: **Notes** ``dptsvx`` performs the following steps: (1) If :math:`\mathrm{fact} = \texttt{'N'}`, the matrix :math:`A` is factorized as :math:`A = LDL^\mathrm{T}`, where :math:`L` is a unit lower bidiagonal matrix and :math:`D` is diagonal. The factorization can also be regarded as having the form :math:`A = U^\mathrm{T}DU`. (#) If the leading :math:`i\times i` principal minor is not positive definite, then the function returns with :math:`\textit{errno} = i`. Otherwise, the factored form of :math:`A` is used to estimate the condition number of the matrix :math:`A`. If the reciprocal of the condition number is less than machine precision, :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1 is returned as a warning, but the function still goes on to solve for :math:`X` and compute error bounds as described below. (#) The system of equations is solved for :math:`X` using the factored form of :math:`A`. (#) Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for it. .. _f07jb-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def dpttrf(d, e): r""" ``dpttrf`` computes the modified Cholesky factorization of a real :math:`n\times n` symmetric positive definite tridiagonal matrix :math:`A`. .. _f07jd-py2-py-doc: For full information please refer to the NAG Library document for f07jd https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07jdf.html .. _f07jd-py2-py-parameters: **Parameters** **d** : float, array-like, shape :math:`\left(n\right)` Must contain the :math:`n` diagonal elements of the matrix :math:`A`. **e** : float, array-like, shape :math:`\left(n-1\right)` Must contain the :math:`\left(n-1\right)` subdiagonal elements of the matrix :math:`A`. **Returns** **d** : float, ndarray, shape :math:`\left(n\right)` Is overwritten by the :math:`n` diagonal elements of the diagonal matrix :math:`D` from the :math:`LDL^\mathrm{T}` factorization of :math:`A`. **e** : float, ndarray, shape :math:`\left(n-1\right)` Is overwritten by the :math:`\left(n-1\right)` subdiagonal elements of the lower bidiagonal matrix :math:`L`. (:math:`\mathrm{e}` can also be regarded as containing the :math:`\left(n-1\right)` superdiagonal elements of the upper bidiagonal matrix :math:`U`.) .. _f07jd-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`\left(i > 0\right)\text{ and }\left(i < n\right)`) The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` is not positive definite, the factorization could not be completed. (`errno` :math:`\left(i > 0\right)\text{ and }(n)`) The leading minor of order :math:`n` is not positive definite, the factorization was completed, but :math:`\mathrm{d}[n-1]\leq 0`. .. _f07jd-py2-py-notes: **Notes** ``dpttrf`` factorizes the matrix :math:`A` as .. math:: A = LDL^\mathrm{T}\text{,} where :math:`L` is a unit lower bidiagonal matrix and :math:`D` is a diagonal matrix with positive diagonal elements. The factorization may also be regarded as having the form :math:`U^\mathrm{T}DU`, where :math:`U` is a unit upper bidiagonal matrix. """ raise NotImplementedError
[docs]def dpttrs(d, e, b): r""" ``dpttrs`` computes the solution to a real system of linear equations :math:`AX = B`, where :math:`A` is an :math:`n\times n` symmetric positive definite tridiagonal matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices, using the :math:`LDL^\mathrm{T}` factorization returned by :meth:`dpttrf`. .. _f07je-py2-py-doc: For full information please refer to the NAG Library document for f07je https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07jef.html .. _f07je-py2-py-parameters: **Parameters** **d** : float, array-like, shape :math:`\left(n\right)` Must contain the :math:`n` diagonal elements of the diagonal matrix :math:`D` from the :math:`LDL^\mathrm{T}` factorization of :math:`A`. **e** : float, array-like, shape :math:`\left(n-1\right)` Must contain the :math:`\left(n-1\right)` subdiagonal elements of the unit lower bidiagonal matrix :math:`L`. (:math:`\mathrm{e}` can also be regarded as the superdiagonal of the unit upper bidiagonal matrix :math:`U` from the :math:`U^\mathrm{T}DU` factorization of :math:`A`.) **b** : float, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` matrix of right-hand sides :math:`B`. **Returns** **b** : float, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`. .. _f07je-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. .. _f07je-py2-py-notes: **Notes** ``dpttrs`` should be preceded by a call to :meth:`dpttrf`, which computes a modified Cholesky factorization of the matrix :math:`A` as .. math:: A = LDL^\mathrm{T}\text{,} where :math:`L` is a unit lower bidiagonal matrix and :math:`D` is a diagonal matrix, with positive diagonal elements. ``dpttrs`` then utilizes the factorization to solve the required equations. Note that the factorization may also be regarded as having the form :math:`U^\mathrm{T}DU`, where :math:`U` is a unit upper bidiagonal matrix. .. _f07je-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug """ raise NotImplementedError
[docs]def dptcon(n, d, e, anorm): r""" ``dptcon`` computes the reciprocal condition number of a real :math:`n\times n` symmetric positive definite tridiagonal matrix :math:`A`, using the :math:`LDL^\mathrm{T}` factorization returned by :meth:`dpttrf`. .. _f07jg-py2-py-doc: For full information please refer to the NAG Library document for f07jg https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07jgf.html .. _f07jg-py2-py-parameters: **Parameters** **n** : int :math:`n`, the order of the matrix :math:`A`. **d** : float, array-like, shape :math:`\left(\mathrm{n}\right)` Must contain the :math:`n` diagonal elements of the diagonal matrix :math:`D` from the :math:`LDL^\mathrm{T}` factorization of :math:`A`. **e** : float, array-like, shape :math:`\left(\mathrm{n}-1\right)` Must contain the :math:`\left(n-1\right)` subdiagonal elements of the unit lower bidiagonal matrix :math:`L`. (:math:`\mathrm{e}` can also be regarded as the superdiagonal of the unit upper bidiagonal matrix :math:`U` from the :math:`U^\mathrm{T}DU` factorization of :math:`A`.) **anorm** : float The :math:`1`-norm of the **original** matrix :math:`A`, which may be computed by calling :meth:`blas.dlanst <naginterfaces.library.blas.dlanst>` with its argument :math:`{\textit{norm}} = \texttt{'1'}`. :math:`\mathrm{anorm}` must be computed either **before** calling :meth:`dpttrf` or else from a **copy** of the original matrix :math:`A`. **Returns** **rcond** : float The reciprocal condition number, :math:`1/\kappa_1\left(A\right) = 1/\left(\left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\right)`. .. _f07jg-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\mathrm{anorm}`. Constraint: :math:`\mathrm{anorm}\geq 0.0`. .. _f07jg-py2-py-notes: **Notes** ``dptcon`` should be preceded by a call to :meth:`dpttrf`, which computes a modified Cholesky factorization of the matrix :math:`A` as .. math:: A = LDL^\mathrm{T}\text{,} where :math:`L` is a unit lower bidiagonal matrix and :math:`D` is a diagonal matrix, with positive diagonal elements. ``dptcon`` then utilizes the factorization to compute :math:`\left\lVert A^{-1}\right\rVert_1` by a direct method, from which the reciprocal of the condition number of :math:`A`, :math:`1/\kappa \left(A\right)` is computed as .. math:: 1/\kappa_1\left(A\right) = 1/\left(\left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\right)\text{.} :math:`1/\kappa \left(A\right)` is returned, rather than :math:`\kappa \left(A\right)`, since when :math:`A` is singular :math:`\kappa \left(A\right)` is infinite. .. _f07jg-py2-py-references: **References** Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def dptrfs(nrhs, d, e, df, ef, b, x): r""" ``dptrfs`` computes error bounds and refines the solution to a real system of linear equations :math:`AX = B`, where :math:`A` is an :math:`n\times n` symmetric positive definite tridiagonal matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices, using the modified Cholesky factorization returned by :meth:`dpttrf` and an initial solution returned by :meth:`dpttrs`. Iterative refinement is used to reduce the backward error as much as possible. .. _f07jh-py2-py-doc: For full information please refer to the NAG Library document for f07jh https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07jhf.html .. _f07jh-py2-py-parameters: **Parameters** **nrhs** : int :math:`r`, the number of right-hand sides, i.e., the number of columns of the matrix :math:`B`. **d** : float, array-like, shape :math:`\left(n\right)` Must contain the :math:`n` diagonal elements of the matrix of :math:`A`. **e** : float, array-like, shape :math:`\left(n-1\right)` Must contain the :math:`\left(n-1\right)` subdiagonal elements of the matrix :math:`A`. **df** : float, array-like, shape :math:`\left(n\right)` Must contain the :math:`n` diagonal elements of the diagonal matrix :math:`D` from the :math:`LDL^\mathrm{T}` factorization of :math:`A`. **ef** : float, array-like, shape :math:`\left(n\right)` Must contain the :math:`\left(n-1\right)` subdiagonal elements of the unit bidiagonal matrix :math:`L` from the :math:`LDL^\mathrm{T}` factorization of :math:`A`. **b** : float, array-like, shape :math:`\left(n, \mathrm{nrhs}\right)` The :math:`n\times r` matrix of right-hand sides :math:`B`. **x** : float, array-like, shape :math:`\left(n, \mathrm{nrhs}\right)` The :math:`n\times r` initial solution matrix :math:`X`. **Returns** **x** : float, ndarray, shape :math:`\left(n, \mathrm{nrhs}\right)` The :math:`n\times r` refined solution matrix :math:`X`. **ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` Estimate of the forward error bound for each computed solution vector, such that :math:`\left\lVert \hat{x}_j-x_j\right\rVert_\infty/\left\lVert \hat{x}_j\right\rVert_\infty\leq \mathrm{ferr}[j-1]`, where :math:`\hat{x}_j` is the :math:`j`\ th column of the computed solution returned in the array :math:`\mathrm{x}` and :math:`x_j` is the corresponding column of the exact solution :math:`X`. The estimate is almost always a slight overestimate of the true error. **berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` Estimate of the component-wise relative backward error of each computed solution vector :math:`\hat{x}_j` (i.e., the smallest relative change in any element of :math:`A` or :math:`B` that makes :math:`\hat{x}_j` an exact solution). .. _f07jh-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{nrhs}`. Constraint: :math:`\mathrm{nrhs}\geq 0`. .. _f07jh-py2-py-notes: **Notes** ``dptrfs`` should normally be preceded by calls to :meth:`dpttrf` and :meth:`dpttrs`. :meth:`dpttrf` computes a modified Cholesky factorization of the matrix :math:`A` as .. math:: A = LDL^\mathrm{T}\text{,} where :math:`L` is a unit lower bidiagonal matrix and :math:`D` is a diagonal matrix, with positive diagonal elements. :meth:`dpttrs` then utilizes the factorization to compute a solution, :math:`\hat{X}`, to the required equations. Letting :math:`\hat{x}` denote a column of :math:`\hat{X}`, ``dptrfs`` computes a `component-wise backward error`, :math:`\beta`, the smallest relative perturbation in each element of :math:`A` and :math:`b` such that :math:`\hat{x}` is the exact solution of a perturbed system .. math:: \left(A+E\right)\hat{x} = b+f\text{, with }\quad \left\lvert e_{{ij}}\right\rvert \leq \beta \left\lvert a_{{ij}}\right\rvert \text{, and }\quad \left\lvert f_j\right\rvert \leq \beta \left\lvert b_j\right\rvert \text{.} The function also estimates a bound for the `component-wise forward error` in the computed solution defined by :math:`\mathrm{max}\left\lvert x_i-\hat{x_i}\right\rvert /\mathrm{max}\left\lvert \hat{x_i}\right\rvert`, where :math:`x` is the corresponding column of the exact solution, :math:`X`. Note that the modified Cholesky factorization of :math:`A` can also be expressed as .. math:: A = U^\mathrm{T}DU\text{,} where :math:`U` is unit upper bidiagonal. .. _f07jh-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug """ raise NotImplementedError
[docs]def zptsv(d, e, b): r""" ``zptsv`` computes the solution to a complex system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` Hermitian positive definite tridiagonal matrix, and :math:`X` and :math:`B` are :math:`n\times r` matrices. .. _f07jn-py2-py-doc: For full information please refer to the NAG Library document for f07jn https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07jnf.html .. _f07jn-py2-py-parameters: **Parameters** **d** : float, array-like, shape :math:`\left(n\right)` The :math:`n` diagonal elements of the tridiagonal matrix :math:`A`. **e** : complex, array-like, shape :math:`\left(n-1\right)` The :math:`\left(n-1\right)` subdiagonal elements of the tridiagonal matrix :math:`A`. **b** : complex, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **d** : float, ndarray, shape :math:`\left(n\right)` The :math:`n` diagonal elements of the diagonal matrix :math:`D` from the factorization :math:`A = LDL^\mathrm{H}`. **e** : complex, ndarray, shape :math:`\left(n-1\right)` The :math:`\left(n-1\right)` subdiagonal elements of the unit bidiagonal factor :math:`L` from the :math:`LDL^\mathrm{H}` factorization of :math:`A`. (:math:`\mathrm{e}` can also be regarded as the superdiagonal of the unit bidiagonal factor :math:`U` from the :math:`U^\mathrm{H}DU` factorization of :math:`A`.) **b** : complex, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`. .. _f07jn-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. (`errno` :math:`i > 0`) The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` is not positive definite, and the solution has not been computed. The factorization has not been completed unless :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`. .. _f07jn-py2-py-notes: **Notes** ``zptsv`` factors :math:`A` as :math:`A = LDL^\mathrm{H}`. The factored form of :math:`A` is then used to solve the system of equations. .. _f07jn-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def zptsvx(fact, n, nrhs, d, e, df, ef, b): r""" ``zptsvx`` uses the factorization .. math:: A = LDL^\mathrm{H} to compute the solution to a complex system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` Hermitian positive definite tridiagonal matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices. Error bounds on the solution and a condition estimate are also provided. .. _f07jp-py2-py-doc: For full information please refer to the NAG Library document for f07jp https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07jpf.html .. _f07jp-py2-py-parameters: **Parameters** **fact** : str, length 1 Specifies whether or not the factorized form of the matrix :math:`A` has been supplied. :math:`\mathrm{fact} = \texttt{'F'}` :math:`\mathrm{df}` and :math:`\mathrm{ef}` contain the factorized form of the matrix :math:`A`. :math:`\mathrm{df}` and :math:`\mathrm{ef}` will not be modified. :math:`\mathrm{fact} = \texttt{'N'}` The matrix :math:`A` will be copied to :math:`\mathrm{df}` and :math:`\mathrm{ef}` and factorized. **n** : int :math:`n`, the order of the matrix :math:`A`. **nrhs** : int :math:`r`, the number of right-hand sides, i.e., the number of columns of the matrix :math:`B`. **d** : float, array-like, shape :math:`\left(\mathrm{n}\right)` The :math:`n` diagonal elements of the tridiagonal matrix :math:`A`. **e** : complex, array-like, shape :math:`\left(\mathrm{n}-1\right)` The :math:`\left(n-1\right)` subdiagonal elements of the tridiagonal matrix :math:`A`. **df** : float, array-like, shape :math:`\left(\mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{df}` must contain the :math:`n` diagonal elements of the diagonal matrix :math:`D` from the :math:`LDL^\mathrm{H}` factorization of :math:`A`. **ef** : complex, array-like, shape :math:`\left(\mathrm{n}-1\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{ef}` must contain the :math:`\left(n-1\right)` subdiagonal elements of the unit bidiagonal factor :math:`L` from the :math:`LDL^\mathrm{H}` factorization of :math:`A`. **b** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **df** : float, ndarray, shape :math:`\left(\mathrm{n}\right)` If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{df}` contains the :math:`n` diagonal elements of the diagonal matrix :math:`D` from the :math:`LDL^\mathrm{H}` factorization of :math:`A`. **ef** : complex, ndarray, shape :math:`\left(\mathrm{n}-1\right)` If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{ef}` contains the :math:`\left(n-1\right)` subdiagonal elements of the unit bidiagonal factor :math:`L` from the :math:`LDL^\mathrm{H}` factorization of :math:`A`. **x** : complex, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, the :math:`n\times r` solution matrix :math:`X`. **rcond** : float The reciprocal condition number of the matrix :math:`A`. If :math:`\mathrm{rcond}` is less than the machine precision (in particular, if :math:`\mathrm{rcond} = 0.0`), the matrix is singular to working precision. This condition is indicated by a return code of :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1. **ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` The forward error bound for each solution vector :math:`\hat{x}_j` (the :math:`j`\ th column of the solution matrix :math:`X`). If :math:`x_j` is the true solution corresponding to :math:`\hat{x}_j`, :math:`\mathrm{ferr}[j-1]` is an estimated upper bound for the magnitude of the largest element in (:math:`\hat{x}_j-x_j`) divided by the magnitude of the largest element in :math:`\hat{x}_j`. **berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` The component-wise relative backward error of each solution vector :math:`\hat{x}_j` (i.e., the smallest relative change in any element of :math:`A` or :math:`B` that makes :math:`\hat{x}_j` an exact solution). .. _f07jp-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{fact}`. Constraint: :math:`\mathrm{fact} = \texttt{'F'}` or :math:`\texttt{'N'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{nrhs}`. Constraint: :math:`\mathrm{nrhs}\geq 0`. (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq \mathrm{n}\right)`) The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is not positive definite, so the factorization could not be completed, and the solution has not been computed. :math:`\mathrm{rcond} = 0.0` is returned. **Warns** **NagAlgorithmicWarning** (`errno` :math:`\mathrm{n}+1`) :math:`D` is nonsingular, but :math:`\mathrm{rcond}` is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of :math:`\mathrm{rcond}` would suggest. .. _f07jp-py2-py-notes: **Notes** ``zptsvx`` performs the following steps: (1) If :math:`\mathrm{fact} = \texttt{'N'}`, the matrix :math:`A` is factorized as :math:`A = LDL^\mathrm{H}`, where :math:`L` is a unit lower bidiagonal matrix and :math:`D` is diagonal. The factorization can also be regarded as having the form :math:`A = U^\mathrm{H}DU`. (#) If the leading :math:`i\times i` principal minor is not positive definite, then the function returns with :math:`\textit{errno} = i`. Otherwise, the factored form of :math:`A` is used to estimate the condition number of the matrix :math:`A`. If the reciprocal of the condition number is less than machine precision, :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1 is returned as a warning, but the function still goes on to solve for :math:`X` and compute error bounds as described below. (#) The system of equations is solved for :math:`X` using the factored form of :math:`A`. (#) Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for it. .. _f07jp-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def zpttrf(d, e): r""" ``zpttrf`` computes the modified Cholesky factorization of a complex :math:`n\times n` Hermitian positive definite tridiagonal matrix :math:`A`. .. _f07jr-py2-py-doc: For full information please refer to the NAG Library document for f07jr https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07jrf.html .. _f07jr-py2-py-parameters: **Parameters** **d** : float, array-like, shape :math:`\left(n\right)` Must contain the :math:`n` diagonal elements of the matrix :math:`A`. **e** : complex, array-like, shape :math:`\left(n-1\right)` Must contain the :math:`\left(n-1\right)` subdiagonal elements of the matrix :math:`A`. **Returns** **d** : float, ndarray, shape :math:`\left(n\right)` Is overwritten by the :math:`n` diagonal elements of the diagonal matrix :math:`D` from the :math:`LDL^\mathrm{H}` factorization of :math:`A`. **e** : complex, ndarray, shape :math:`\left(n-1\right)` Is overwritten by the :math:`\left(n-1\right)` subdiagonal elements of the lower bidiagonal matrix :math:`L`. (:math:`\mathrm{e}` can also be regarded as containing the :math:`\left(n-1\right)` superdiagonal elements of the upper bidiagonal matrix :math:`U`.) .. _f07jr-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`\left(i > 0\right)\text{ and }\left(i < n\right)`) The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` is not positive definite, the factorization could not be completed. (`errno` :math:`\left(i > 0\right)\text{ and }(n)`) The leading minor of order :math:`n` is not positive definite, the factorization was completed, but :math:`\mathrm{d}[n-1]\leq 0`. .. _f07jr-py2-py-notes: **Notes** ``zpttrf`` factorizes the matrix :math:`A` as .. math:: A = LDL^\mathrm{H}\text{,} where :math:`L` is a unit lower bidiagonal matrix and :math:`D` is a diagonal matrix with positive diagonal elements. The factorization may also be regarded as having the form :math:`U^\mathrm{H}DU`, where :math:`U` is a unit upper bidiagonal matrix. """ raise NotImplementedError
[docs]def zpttrs(uplo, d, e, b): r""" ``zpttrs`` computes the solution to a complex system of linear equations :math:`AX = B`, where :math:`A` is an :math:`n\times n` Hermitian positive definite tridiagonal matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices, using the :math:`LDL^\mathrm{H}` factorization returned by :meth:`zpttrf`. .. _f07js-py2-py-doc: For full information please refer to the NAG Library document for f07js https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07jsf.html .. _f07js-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies the form of the factorization as follows: :math:`\mathrm{uplo} = \texttt{'U'}` :math:`A = U^\mathrm{H}DU`. :math:`\mathrm{uplo} = \texttt{'L'}` :math:`A = LDL^\mathrm{H}`. **d** : float, array-like, shape :math:`\left(n\right)` Must contain the :math:`n` diagonal elements of the diagonal matrix :math:`D` from the :math:`LDL^\mathrm{H}` or :math:`U^\mathrm{H}DU` factorization of :math:`A`. **e** : complex, array-like, shape :math:`\left(n-1\right)` If :math:`\mathrm{uplo} = \texttt{'U'}`, :math:`\mathrm{e}` must contain the :math:`\left(n-1\right)` superdiagonal elements of the unit upper bidiagonal matrix :math:`U` from the :math:`U^\mathrm{H}DU` factorization of :math:`A`. If :math:`\mathrm{uplo} = \texttt{'L'}`, :math:`\mathrm{e}` must contain the :math:`\left(n-1\right)` subdiagonal elements of the unit lower bidiagonal matrix :math:`L` from the :math:`LDL^\mathrm{H}` factorization of :math:`A`. **b** : complex, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` matrix of right-hand sides :math:`B`. **Returns** **b** : complex, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`. .. _f07js-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. .. _f07js-py2-py-notes: **Notes** ``zpttrs`` should be preceded by a call to :meth:`zpttrf`, which computes a modified Cholesky factorization of the matrix :math:`A` as .. math:: A = LDL^\mathrm{H}\text{,} where :math:`L` is a unit lower bidiagonal matrix and :math:`D` is a diagonal matrix, with positive diagonal elements. ``zpttrs`` then utilizes the factorization to solve the required equations. Note that the factorization may also be regarded as having the form :math:`U^\mathrm{H}DU`, where :math:`U` is a unit upper bidiagonal matrix. .. _f07js-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug """ raise NotImplementedError
[docs]def zptcon(n, d, e, anorm): r""" ``zptcon`` computes the reciprocal condition number of a complex :math:`n\times n` Hermitian positive definite tridiagonal matrix :math:`A`, using the :math:`LDL^\mathrm{H}` factorization returned by :meth:`zpttrf`. .. _f07ju-py2-py-doc: For full information please refer to the NAG Library document for f07ju https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07juf.html .. _f07ju-py2-py-parameters: **Parameters** **n** : int :math:`n`, the order of the matrix :math:`A`. **d** : float, array-like, shape :math:`\left(\mathrm{n}\right)` Must contain the :math:`n` diagonal elements of the diagonal matrix :math:`D` from the :math:`LDL^\mathrm{H}` factorization of :math:`A`. **e** : complex, array-like, shape :math:`\left(\mathrm{n}-1\right)` Must contain the :math:`\left(n-1\right)` subdiagonal elements of the unit lower bidiagonal matrix :math:`L`. (:math:`\mathrm{e}` can also be regarded as the superdiagonal of the unit upper bidiagonal matrix :math:`U` from the :math:`U^\mathrm{H}DU` factorization of :math:`A`.) **anorm** : float The :math:`1`-norm of the **original** matrix :math:`A`, which may be computed by calling :meth:`blas.zlanht <naginterfaces.library.blas.zlanht>` with its argument :math:`{\textit{norm}} = \texttt{'1'}`. :math:`\mathrm{anorm}` must be computed either **before** calling :meth:`zpttrf` or else from a **copy** of the original matrix :math:`A`. **Returns** **rcond** : float The reciprocal condition number, :math:`1/\kappa_1\left(A\right) = 1/\left(\left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\right)`. .. _f07ju-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\mathrm{anorm}`. Constraint: :math:`\mathrm{anorm}\geq 0.0`. .. _f07ju-py2-py-notes: **Notes** ``zptcon`` should be preceded by a call to :meth:`zpttrf`, which computes a modified Cholesky factorization of the matrix :math:`A` as .. math:: A = LDL^\mathrm{H}\text{,} where :math:`L` is a unit lower bidiagonal matrix and :math:`D` is a diagonal matrix, with positive diagonal elements. ``zptcon`` then utilizes the factorization to compute :math:`\left\lVert A^{-1}\right\rVert_1` by a direct method, from which the reciprocal of the condition number of :math:`A`, :math:`1/\kappa \left(A\right)` is computed as .. math:: 1/\kappa_1\left(A\right) = 1/\left(\left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\right)\text{.} :math:`1/\kappa \left(A\right)` is returned, rather than :math:`\kappa \left(A\right)`, since when :math:`A` is singular :math:`\kappa \left(A\right)` is infinite. .. _f07ju-py2-py-references: **References** Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def zptrfs(uplo, n, nrhs, d, e, df, ef, b, x): r""" ``zptrfs`` computes error bounds and refines the solution to a complex system of linear equations :math:`AX = B`, where :math:`A` is an :math:`n\times n` Hermitian positive definite tridiagonal matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices, using the modified Cholesky factorization returned by :meth:`zpttrf` and an initial solution returned by :meth:`zpttrs`. Iterative refinement is used to reduce the backward error as much as possible. .. _f07jv-py2-py-doc: For full information please refer to the NAG Library document for f07jv https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07jvf.html .. _f07jv-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies the form of the factorization as follows: :math:`\mathrm{uplo} = \texttt{'U'}` :math:`A = U^\mathrm{H}DU`. :math:`\mathrm{uplo} = \texttt{'L'}` :math:`A = LDL^\mathrm{H}`. **n** : int :math:`n`, the order of the matrix :math:`A`. **nrhs** : int :math:`r`, the number of right-hand sides, i.e., the number of columns of the matrix :math:`B`. **d** : float, array-like, shape :math:`\left(\mathrm{n}\right)` Must contain the :math:`n` diagonal elements of the matrix of :math:`A`. **e** : complex, array-like, shape :math:`\left(\mathrm{n}-1\right)` If :math:`\mathrm{uplo} = \texttt{'U'}`, :math:`\mathrm{e}` must contain the :math:`\left(n-1\right)` superdiagonal elements of the matrix :math:`A`. If :math:`\mathrm{uplo} = \texttt{'L'}`, :math:`\mathrm{e}` must contain the :math:`\left(n-1\right)` subdiagonal elements of the matrix :math:`A`. **df** : float, array-like, shape :math:`\left(\mathrm{n}\right)` Must contain the :math:`n` diagonal elements of the diagonal matrix :math:`D` from the :math:`LDL^\mathrm{T}` factorization of :math:`A`. **ef** : complex, array-like, shape :math:`\left(\mathrm{n}-1\right)` If :math:`\mathrm{uplo} = \texttt{'U'}`, :math:`\mathrm{ef}` must contain the :math:`\left(n-1\right)` superdiagonal elements of the unit upper bidiagonal matrix :math:`U` from the :math:`U^\mathrm{H}DU` factorization of :math:`A`. If :math:`\mathrm{uplo} = \texttt{'L'}`, :math:`\mathrm{ef}` must contain the :math:`\left(n-1\right)` subdiagonal elements of the unit lower bidiagonal matrix :math:`L` from the :math:`LDL^\mathrm{H}` factorization of :math:`A`. **b** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` The :math:`n\times r` matrix of right-hand sides :math:`B`. **x** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` The :math:`n\times r` initial solution matrix :math:`X`. **Returns** **x** : complex, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)` The :math:`n\times r` refined solution matrix :math:`X`. **ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` Estimate of the forward error bound for each computed solution vector, such that :math:`\left\lVert \hat{x}_j-x_j\right\rVert_\infty/\left\lVert \hat{x}_j\right\rVert_\infty\leq \mathrm{ferr}[j-1]`, where :math:`\hat{x}_j` is the :math:`j`\ th column of the computed solution returned in the array :math:`\mathrm{x}` and :math:`x_j` is the corresponding column of the exact solution :math:`X`. The estimate is almost always a slight overestimate of the true error. **berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` Estimate of the component-wise relative backward error of each computed solution vector :math:`\hat{x}_j` (i.e., the smallest relative change in any element of :math:`A` or :math:`B` that makes :math:`\hat{x}_j` an exact solution). .. _f07jv-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\mathrm{nrhs}`. Constraint: :math:`\mathrm{nrhs}\geq 0`. .. _f07jv-py2-py-notes: **Notes** ``zptrfs`` should normally be preceded by calls to :meth:`zpttrf` and :meth:`zpttrs`. :meth:`zpttrf` computes a modified Cholesky factorization of the matrix :math:`A` as .. math:: A = LDL^\mathrm{H}\text{,} where :math:`L` is a unit lower bidiagonal matrix and :math:`D` is a diagonal matrix, with positive diagonal elements. :meth:`zpttrs` then utilizes the factorization to compute a solution, :math:`\hat{X}`, to the required equations. Letting :math:`\hat{x}` denote a column of :math:`\hat{X}`, ``zptrfs`` computes a `component-wise backward error`, :math:`\beta`, the smallest relative perturbation in each element of :math:`A` and :math:`b` such that :math:`\hat{x}` is the exact solution of a perturbed system .. math:: \left(A+E\right)\hat{x} = b+f\text{, with }\quad \left\lvert e_{{ij}}\right\rvert \leq \beta \left\lvert a_{{ij}}\right\rvert \text{, and }\quad \left\lvert f_j\right\rvert \leq \beta \left\lvert b_j\right\rvert \text{.} The function also estimates a bound for the `component-wise forward error` in the computed solution defined by :math:`\mathrm{max}\left\lvert x_i-\hat{x_i}\right\rvert /\mathrm{max}\left\lvert \hat{x_i}\right\rvert`, where :math:`x` is the corresponding column of the exact solution, :math:`X`. Note that the modified Cholesky factorization of :math:`A` can also be expressed as .. math:: A = U^\mathrm{H}DU\text{,} where :math:`U` is unit upper bidiagonal. .. _f07jv-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug """ raise NotImplementedError
[docs]def dpstrf(uplo, n, a, tol=-1): r""" ``dpstrf`` computes the Cholesky factorization with complete pivoting of a real symmetric positive semidefinite matrix. .. _f07kd-py2-py-doc: For full information please refer to the NAG Library document for f07kd https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07kdf.html .. _f07kd-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies whether the upper or lower triangular part of :math:`A` is stored and how :math:`A` is to be factorized. :math:`\mathrm{uplo} = \texttt{'U'}` The upper triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`U^\mathrm{T}U`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` The lower triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`LL^\mathrm{T}`, where :math:`L` is lower triangular. **n** : int :math:`n`, the order of the matrix :math:`A`. **a** : float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` The :math:`n\times n` symmetric positive semidefinite matrix :math:`A`. **tol** : float, optional User defined tolerance. If :math:`\mathrm{tol} < 0`, :math:`n\times \text{max}_{{k = 1,n}}\left\lvert A_{{kk}}\right\rvert \times \text{machine precision}` will be used. The algorithm terminates at the :math:`r`\ th step if the :math:`\left(r+1\right)`\ th step pivot :math:`\text{} < \mathrm{tol}`. **Returns** **a** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` If :math:`\mathrm{uplo} = \texttt{'U'}`, the first :math:`\mathrm{rank}` rows of the upper triangle of :math:`A` are overwritten with the nonzero elements of the Cholesky factor :math:`U`, and the remaining rows of the triangle are destroyed. If :math:`\mathrm{uplo} = \texttt{'L'}`, the first :math:`\mathrm{rank}` columns of the lower triangle of :math:`A` are overwritten with the nonzero elements of the Cholesky factor :math:`L`, and the remaining columns of the triangle are destroyed. **piv** : int, ndarray, shape :math:`\left(\mathrm{n}\right)` :math:`\mathrm{piv}` is such that the nonzero entries of :math:`P` are :math:`P\left({\mathrm{piv}[\textit{k}-1]}, \textit{k}\right) = 1`, for :math:`\textit{k} = 1,2,\ldots,n`. **rank** : int The computed rank of :math:`A` given by the number of steps the algorithm completed. .. _f07kd-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`1`) The matrix :math:`A` is not positive definite. It is either positive semidefinite with computed rank as returned in :math:`\mathrm{rank}` and less than :math:`n`, or it may be indefinite, see `Further Comments <https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07kdf.html#fcomments>`__. .. _f07kd-py2-py-notes: **Notes** ``dpstrf`` forms the Cholesky factorization of a real symmetric positive semidefinite matrix :math:`A` either as :math:`P^\mathrm{T}AP = U^\mathrm{T}U` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`P^\mathrm{T}AP = LL^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`P` is a permutation matrix, :math:`U` is an upper triangular matrix and :math:`L` is lower triangular. This algorithm does not attempt to check that :math:`A` is positive semidefinite. .. _f07kd-py2-py-references: **References** Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia Lucas, C, 2004, `LAPACK-style codes for Level 2 and 3 pivoted Cholesky factorizations`, LAPACK Working Note No. 161. Technical Report CS-04-522, Department of Computer Science, University of Tennessee, 107 Ayres Hall, Knoxville, TN 37996-1301, USA, https://www.netlib.org/lapack/lawnspdf/lawn161.pdf """ raise NotImplementedError
[docs]def zpstrf(uplo, n, a, tol=-1): r""" ``zpstrf`` computes the Cholesky factorization with complete pivoting of a complex Hermitian positive semidefinite matrix. .. _f07kr-py2-py-doc: For full information please refer to the NAG Library document for f07kr https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07krf.html .. _f07kr-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies whether the upper or lower triangular part of :math:`A` is stored and how :math:`A` is to be factorized. :math:`\mathrm{uplo} = \texttt{'U'}` The upper triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`U^\mathrm{H}U`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` The lower triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`LL^\mathrm{H}`, where :math:`L` is lower triangular. **n** : int :math:`n`, the order of the matrix :math:`A`. **a** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` The :math:`n\times n` Hermitian positive semidefinite matrix :math:`A`. **tol** : float, optional User defined tolerance. If :math:`\mathrm{tol} < 0`, :math:`n\times \text{max}_{{k = 1,n}}\left\lvert A_{{kk}}\right\rvert \times \text{machine precision}` will be used. The algorithm terminates at the :math:`r`\ th step if the :math:`\left(r+1\right)`\ th step pivot :math:`\text{} < \mathrm{tol}`. **Returns** **a** : complex, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` If :math:`\mathrm{uplo} = \texttt{'U'}`, the first :math:`\mathrm{rank}` rows of the upper triangle of :math:`A` are overwritten with the nonzero elements of the Cholesky factor :math:`U`, and the remaining rows of the triangle are destroyed. If :math:`\mathrm{uplo} = \texttt{'L'}`, the first :math:`\mathrm{rank}` columns of the lower triangle of :math:`A` are overwritten with the nonzero elements of the Cholesky factor :math:`L`, and the remaining columns of the triangle are destroyed. **piv** : int, ndarray, shape :math:`\left(\mathrm{n}\right)` :math:`\mathrm{piv}` is such that the nonzero entries of :math:`P` are :math:`P\left({\mathrm{piv}[\textit{k}-1]}, \textit{k}\right) = 1`, for :math:`\textit{k} = 1,2,\ldots,n`. **rank** : int The computed rank of :math:`A` given by the number of steps the algorithm completed. .. _f07kr-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`1`) The matrix :math:`A` is not positive definite. It is either positive semidefinite with computed rank as returned in :math:`\mathrm{rank}` and less than :math:`n`, or it may be indefinite, see `Further Comments <https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07krf.html#fcomments>`__. .. _f07kr-py2-py-notes: **Notes** ``zpstrf`` forms the Cholesky factorization of a complex Hermitian positive semidefinite matrix :math:`A` either as :math:`P^\mathrm{T}AP = U^\mathrm{H}U` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`P^\mathrm{T}AP = LL^\mathrm{H}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`P` is a permutation matrix, :math:`U` is an upper triangular matrix and :math:`L` is lower triangular. This algorithm does not attempt to check that :math:`A` is positive semidefinite. .. _f07kr-py2-py-references: **References** Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia Lucas, C, 2004, `LAPACK-style codes for Level 2 and 3 pivoted Cholesky factorizations`, LAPACK Working Note No. 161. Technical Report CS-04-522, Department of Computer Science, University of Tennessee, 107 Ayres Hall, Knoxville, TN 37996-1301, USA, https://www.netlib.org/lapack/lawnspdf/lawn161.pdf """ raise NotImplementedError
[docs]def dsysv(uplo, a, b): r""" ``dsysv`` computes the solution to a real system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` symmetric matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices. .. _f07ma-py2-py-doc: For full information please refer to the NAG Library document for f07ma https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07maf.html .. _f07ma-py2-py-parameters: **Parameters** **uplo** : str, length 1 If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored. If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored. **a** : float, array-like, shape :math:`\left(n, n\right)` The :math:`n\times n` symmetric matrix :math:`A`. **b** : float, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **a** : float, ndarray, shape :math:`\left(n, n\right)` If no exception or warning is raised, the block diagonal matrix :math:`D` and the multipliers used to obtain the factor :math:`U` or :math:`L` from the factorization :math:`A = UDU^\mathrm{T}` or :math:`A = LDL^\mathrm{T}` as computed by :meth:`dsytrf`. **ipiv** : int, ndarray, shape :math:`\left(n\right)` Details of the interchanges and the block structure of :math:`D`. More precisely, if :math:`\mathrm{ipiv}[i-1] = k > 0`, :math:`d_{{ii}}` is a :math:`1\times 1` pivot block and the :math:`i`\ th row and column of :math:`A` were interchanged with the :math:`k`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'U'}` and :math:`\mathrm{ipiv}[i-2] = \mathrm{ipiv}[i-1] = -l < 0`, :math:`\begin{pmatrix}d_{{i-1,i-1}}&\bar{d}_{{i,i-1}}\\\bar{d}_{{i,i-1}}&d_{{ii}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i-1\right)`\ th row and column of :math:`A` were interchanged with the :math:`l`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'L'}` and :math:`\mathrm{ipiv}[i-1] = \mathrm{ipiv}[i] = -m < 0`, :math:`\begin{pmatrix}d_{{ii}}&d_{{i+1,i}}\\d_{{i+1,i}}&d_{{i+1,i+1}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i+1\right)`\ th row and column of :math:`A` were interchanged with the :math:`m`\ th row and column. **b** : float, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`. .. _f07ma-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the block diagonal matrix :math:`D` is exactly singular, so the solution could not be computed. .. _f07ma-py2-py-notes: **Notes** ``dsysv`` uses the diagonal pivoting method to factor :math:`A` as :math:`A = UDU^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LDL^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` (or :math:`L`) is a product of permutation and unit upper (lower) triangular matrices, and :math:`D` is symmetric and block diagonal with :math:`1\times 1` and :math:`2\times 2` diagonal blocks. The factored form of :math:`A` is then used to solve the system of equations :math:`AX = B`. Note that, in general, different permutations (pivot sequences) and diagonal block structures are obtained for :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}` .. _f07ma-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def dsysvx(fact, uplo, a, af, ipiv, b): r""" ``dsysvx`` uses the diagonal pivoting factorization to compute the solution to a real system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` symmetric matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices. Error bounds on the solution and a condition estimate are also provided. .. _f07mb-py2-py-doc: For full information please refer to the NAG Library document for f07mb https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07mbf.html .. _f07mb-py2-py-parameters: **Parameters** **fact** : str, length 1 Specifies whether or not the factorized form of the matrix :math:`A` has been supplied. :math:`\mathrm{fact} = \texttt{'F'}` :math:`\mathrm{af}` and :math:`\mathrm{ipiv}` contain the factorized form of the matrix :math:`A`. :math:`\mathrm{af}` and :math:`\mathrm{ipiv}` will not be modified. :math:`\mathrm{fact} = \texttt{'N'}` The matrix :math:`A` will be copied to :math:`\mathrm{af}` and factorized. **uplo** : str, length 1 If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored. If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored. **a** : float, array-like, shape :math:`\left(n, n\right)` The :math:`n\times n` symmetric matrix :math:`A`. **af** : float, array-like, shape :math:`\left(n, n\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{af}` contains the block diagonal matrix :math:`D` and the multipliers used to obtain the factor :math:`U` or :math:`L` from the factorization :math:`\mathrm{a} = UDU^\mathrm{T}` or :math:`\mathrm{a} = LDL^\mathrm{T}` as computed by :meth:`dsytrf`. **ipiv** : int, array-like, shape :math:`\left(n\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{ipiv}` contains details of the interchanges and the block structure of :math:`D`, as determined by :meth:`dsytrf`. if :math:`\mathrm{ipiv}[i-1] = k > 0`, :math:`d_{{ii}}` is a :math:`1\times 1` pivot block and the :math:`i`\ th row and column of :math:`A` were interchanged with the :math:`k`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'U'}` and :math:`\mathrm{ipiv}[i-2] = \mathrm{ipiv}[i-1] = -l < 0`, :math:`\begin{pmatrix}d_{{i-1,i-1}}&\bar{d}_{{i,i-1}}\\\bar{d}_{{i,i-1}}&d_{{ii}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i-1\right)`\ th row and column of :math:`A` were interchanged with the :math:`l`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'L'}` and :math:`\mathrm{ipiv}[i-1] = \mathrm{ipiv}[i] = -m < 0`, :math:`\begin{pmatrix}d_{{ii}}&d_{{i+1,i}}\\d_{{i+1,i}}&d_{{i+1,i+1}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i+1\right)`\ th row and column of :math:`A` were interchanged with the :math:`m`\ th row and column. **b** : float, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **af** : float, ndarray, shape :math:`\left(n, n\right)` If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{af}` returns the block diagonal matrix :math:`D` and the multipliers used to obtain the factor :math:`U` or :math:`L` from the factorization :math:`\mathrm{a} = UDU^\mathrm{T}` or :math:`\mathrm{a} = LDL^\mathrm{T}`. **ipiv** : int, ndarray, shape :math:`\left(n\right)` If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{ipiv}` contains details of the interchanges and the block structure of :math:`D`, as determined by :meth:`dsytrf`, as described above. **x** : float, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, the :math:`n\times r` solution matrix :math:`X`. **rcond** : float The estimate of the reciprocal condition number of the matrix :math:`A`. If :math:`\mathrm{rcond} = 0.0`, the matrix may be exactly singular. This condition is indicated by :math:`\mathrm{errno}` in 1 ... :math:`\mathrm{n}`. Otherwise, if :math:`\mathrm{rcond}` is less than the machine precision, the matrix is singular to working precision. This condition is indicated by :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1. **ferr** : float, ndarray, shape :math:`\left(\textit{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the forward error bound for each computed solution vector, such that :math:`\left\lVert \hat{x}_j-x_j\right\rVert_\infty/\left\lVert x_j\right\rVert_\infty\leq \mathrm{ferr}[j-1]` where :math:`\hat{x}_j` is the :math:`j`\ th column of the computed solution returned in the array :math:`\mathrm{x}` and :math:`x_j` is the corresponding column of the exact solution :math:`X`. The estimate is as reliable as the estimate for :math:`\mathrm{rcond}`, and is almost always a slight overestimate of the true error. **berr** : float, ndarray, shape :math:`\left(\textit{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the component-wise relative backward error of each computed solution vector :math:`\hat{x}_j` (i.e., the smallest relative change in any element of :math:`A` or :math:`B` that makes :math:`\hat{x}_j` an exact solution). .. _f07mb-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{fact}`. Constraint: :math:`\mathrm{fact} = \texttt{'F'}` or :math:`\texttt{'N'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq n\right)`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`D` is exactly singular, so the solution and error bounds could not be computed. :math:`\mathrm{rcond} = 0.0` is returned. (`errno` :math:`n+1`) :math:`D` is nonsingular, but :math:`\mathrm{rcond}` is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of :math:`\mathrm{rcond}` would suggest. .. _f07mb-py2-py-notes: **Notes** ``dsysvx`` performs the following steps: (1) If :math:`\mathrm{fact} = \texttt{'N'}`, the diagonal pivoting method is used to factor :math:`A`. The form of the factorization is :math:`A = UDU^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LDL^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` (or :math:`L`) is a product of permutation and unit upper (lower) triangular matrices, and :math:`D` is symmetric and block diagonal with :math:`1\times 1` and :math:`2\times 2` diagonal blocks. (#) If some :math:`d_{{ii}} = 0`, so that :math:`D` is exactly singular, then the function returns with :math:`\textit{errno} = i`. Otherwise, the factored form of :math:`A` is used to estimate the condition number of the matrix :math:`A`. If the reciprocal of the condition number is less than machine precision, :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1 is returned as a warning, but the function still goes on to solve for :math:`X` and compute error bounds as described below. (#) The system of equations is solved for :math:`X` using the factored form of :math:`A`. (#) Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for it. .. _f07mb-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def dsytrf(uplo, a): r""" ``dsytrf`` computes the Bunch--Kaufman factorization of a real symmetric indefinite matrix. .. _f07md-py2-py-doc: For full information please refer to the NAG Library document for f07md https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07mdf.html .. _f07md-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies whether the upper or lower triangular part of :math:`A` is stored and how :math:`A` is to be factorized. :math:`\mathrm{uplo} = \texttt{'U'}` The upper triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`PUDU^\mathrm{T}P^\mathrm{T}`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` The lower triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`PLDL^\mathrm{T}P^\mathrm{T}`, where :math:`L` is lower triangular. **a** : float, array-like, shape :math:`\left(n, n\right)` The :math:`n\times n` symmetric indefinite matrix :math:`A`. **Returns** **a** : float, ndarray, shape :math:`\left(n, n\right)` The upper or lower triangle of :math:`A` is overwritten by details of the block diagonal matrix :math:`D` and the multipliers used to obtain the factor :math:`U` or :math:`L` as specified by :math:`\mathrm{uplo}`. **ipiv** : int, ndarray, shape :math:`\left(n\right)` Details of the interchanges and the block structure of :math:`D`. More precisely, if :math:`\mathrm{ipiv}[i-1] = k > 0`, :math:`d_{{ii}}` is a :math:`1\times 1` pivot block and the :math:`i`\ th row and column of :math:`A` were interchanged with the :math:`k`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'U'}` and :math:`\mathrm{ipiv}[i-2] = \mathrm{ipiv}[i-1] = -l < 0`, :math:`\begin{pmatrix}d_{{i-1,i-1}}&\bar{d}_{{i,i-1}}\\\bar{d}_{{i,i-1}}&d_{{ii}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i-1\right)`\ th row and column of :math:`A` were interchanged with the :math:`l`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'L'}` and :math:`\mathrm{ipiv}[i-1] = \mathrm{ipiv}[i] = -m < 0`, :math:`\begin{pmatrix}d_{{ii}}&d_{{i+1,i}}\\d_{{i+1,i}}&d_{{i+1,i+1}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i+1\right)`\ th row and column of :math:`A` were interchanged with the :math:`m`\ th row and column. .. _f07md-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the block diagonal matrix :math:`D` is exactly singular, and division by zero will occur if it is used to solve a system of equations. .. _f07md-py2-py-notes: **Notes** ``dsytrf`` factorizes a real symmetric matrix :math:`A`, using the Bunch--Kaufman diagonal pivoting method. :math:`A` is factorized as either :math:`A = PUDU^\mathrm{T}P^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = PLDL^\mathrm{T}P^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`P` is a permutation matrix, :math:`U` (or :math:`L`) is a unit upper (or lower) triangular matrix and :math:`D` is a symmetric block diagonal matrix with :math:`1\times 1` and :math:`2\times 2` diagonal blocks; :math:`U` (or :math:`L`) has :math:`2\times 2` unit diagonal blocks corresponding to the :math:`2\times 2` blocks of :math:`D`. Row and column interchanges are performed to ensure numerical stability while preserving symmetry. This method is suitable for symmetric matrices which are not known to be positive definite. If :math:`A` is in fact positive definite, no interchanges are performed and no :math:`2\times 2` blocks occur in :math:`D`. .. _f07md-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def dsytrs(uplo, a, ipiv, b): r""" ``dsytrs`` solves a real symmetric indefinite system of linear equations with multiple right-hand sides, .. math:: AX = B\text{,} where :math:`A` has been factorized by :meth:`dsytrf`. .. _f07me-py2-py-doc: For full information please refer to the NAG Library document for f07me https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07mef.html .. _f07me-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies how :math:`A` has been factorized. :math:`\mathrm{uplo} = \texttt{'U'}` :math:`A = PUDU^\mathrm{T}P^\mathrm{T}`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` :math:`A = PLDL^\mathrm{T}P^\mathrm{T}`, where :math:`L` is lower triangular. **a** : float, array-like, shape :math:`\left(n, n\right)` Details of the factorization of :math:`A`, as returned by :meth:`dsytrf`. **ipiv** : int, array-like, shape :math:`\left(n\right)` Details of the interchanges and the block structure of :math:`D`, as returned by :meth:`dsytrf`. **b** : float, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **b** : float, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`. .. _f07me-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. .. _f07me-py2-py-notes: **Notes** ``dsytrs`` is used to solve a real symmetric indefinite system of linear equations :math:`AX = B`, this function must be preceded by a call to :meth:`dsytrf` which computes the Bunch--Kaufman factorization of :math:`A`. If :math:`\mathrm{uplo} = \texttt{'U'}`, :math:`A = PUDU^\mathrm{T}P^\mathrm{T}`, where :math:`P` is a permutation matrix, :math:`U` is an upper triangular matrix and :math:`D` is a symmetric block diagonal matrix with :math:`1\times 1` and :math:`2\times 2` blocks; the solution :math:`X` is computed by solving :math:`PUDY = B` and then :math:`U^\mathrm{T}P^\mathrm{T}X = Y`. If :math:`\mathrm{uplo} = \texttt{'L'}`, :math:`A = PLDL^\mathrm{T}P^\mathrm{T}`, where :math:`L` is a lower triangular matrix; the solution :math:`X` is computed by solving :math:`PLDY = B` and then :math:`L^\mathrm{T}P^\mathrm{T}X = Y`. .. _f07me-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def dsycon(uplo, n, a, ipiv, anorm): r""" ``dsycon`` estimates the condition number of a real symmetric indefinite matrix :math:`A`, where :math:`A` has been factorized by :meth:`dsytrf`. .. _f07mg-py2-py-doc: For full information please refer to the NAG Library document for f07mg https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07mgf.html .. _f07mg-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies how :math:`A` has been factorized. :math:`\mathrm{uplo} = \texttt{'U'}` :math:`A = PUDU^\mathrm{T}P^\mathrm{T}`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` :math:`A = PLDL^\mathrm{T}P^\mathrm{T}`, where :math:`L` is lower triangular. **n** : int :math:`n`, the order of the matrix :math:`A`. **a** : float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` Details of the factorization of :math:`A`, as returned by :meth:`dsytrf`. **ipiv** : int, array-like, shape :math:`\left(\mathrm{n}\right)` Details of the interchanges and the block structure of :math:`D`, as returned by :meth:`dsytrf`. **anorm** : float The :math:`1`-norm of the **original** matrix :math:`A`, which may be computed by calling :meth:`blas.dlansy <naginterfaces.library.blas.dlansy>` with its argument :math:`{\textit{norm}} = \texttt{'1'}`. :math:`\mathrm{anorm}` must be computed either **before** calling :meth:`dsytrf` or else from a **copy** of the original matrix :math:`A`. **Returns** **rcond** : float An estimate of the reciprocal of the condition number of :math:`A`. :math:`\mathrm{rcond}` is set to zero if exact singularity is detected or the estimate underflows. If :math:`\mathrm{rcond}` is less than machine precision, :math:`A` is singular to working precision. .. _f07mg-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-6`) On entry, error in parameter :math:`\mathrm{anorm}`. Constraint: :math:`\mathrm{anorm}\geq 0.0`. .. _f07mg-py2-py-notes: **Notes** ``dsycon`` estimates the condition number (in the :math:`1`-norm) of a real symmetric indefinite matrix :math:`A`: .. math:: \kappa_1\left(A\right) = \left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\text{.} Since :math:`A` is symmetric, :math:`\kappa_1\left(A\right) = \kappa_{\infty }\left(A\right) = \left\lVert A\right\rVert_\infty\left\lVert A^{-1}\right\rVert_\infty`. Because :math:`\kappa_1\left(A\right)` is infinite if :math:`A` is singular, the function actually returns an estimate of the **reciprocal** of :math:`\kappa_1\left(A\right)`. The function should be preceded by a call to :meth:`blas.dlansy <naginterfaces.library.blas.dlansy>` to compute :math:`\left\lVert A\right\rVert_1` and a call to :meth:`dsytrf` to compute the Bunch--Kaufman factorization of :math:`A`. The function then uses Higham's implementation of Hager's method (see Higham (1988)) to estimate :math:`\left\lVert A^{-1}\right\rVert_1`. .. _f07mg-py2-py-references: **References** Higham, N J, 1988, `FORTRAN codes for estimating the one-norm of a real or complex matrix, with applications to condition estimation`, ACM Trans. Math. Software (14), 381--396 """ raise NotImplementedError
[docs]def dsyrfs(uplo, n, a, af, ipiv, b, x): r""" ``dsyrfs`` returns error bounds for the solution of a real symmetric indefinite system of linear equations with multiple right-hand sides, :math:`AX = B`. It improves the solution by iterative refinement, in order to reduce the backward error as much as possible. .. _f07mh-py2-py-doc: For full information please refer to the NAG Library document for f07mh https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07mhf.html .. _f07mh-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies whether the upper or lower triangular part of :math:`A` is stored and how :math:`A` is to be factorized. :math:`\mathrm{uplo} = \texttt{'U'}` The upper triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`PUDU^\mathrm{T}P^\mathrm{T}`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` The lower triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`PLDL^\mathrm{T}P^\mathrm{T}`, where :math:`L` is lower triangular. **n** : int :math:`n`, the order of the matrix :math:`A`. **a** : float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` The :math:`n\times n` original symmetric matrix :math:`A` as supplied to :meth:`dsytrf`. **af** : float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` Details of the factorization of :math:`A`, as returned by :meth:`dsytrf`. **ipiv** : int, array-like, shape :math:`\left(\mathrm{n}\right)` Details of the interchanges and the block structure of :math:`D`, as returned by :meth:`dsytrf`. **b** : float, array-like, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **x** : float, array-like, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`, as returned by :meth:`dsytrs`. **Returns** **x** : float, ndarray, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The improved solution matrix :math:`X`. **ferr** : float, ndarray, shape :math:`\left(\textit{nrhs}\right)` :math:`\mathrm{ferr}[\textit{j}-1]` contains an estimated error bound for the :math:`\textit{j}`\ th solution vector, that is, the :math:`\textit{j}`\ th column of :math:`X`, for :math:`\textit{j} = 1,2,\ldots,r`. **berr** : float, ndarray, shape :math:`\left(\textit{nrhs}\right)` :math:`\mathrm{berr}[\textit{j}-1]` contains the component-wise backward error bound :math:`\beta` for the :math:`\textit{j}`\ th solution vector, that is, the :math:`\textit{j}`\ th column of :math:`X`, for :math:`\textit{j} = 1,2,\ldots,r`. .. _f07mh-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. .. _f07mh-py2-py-notes: **Notes** ``dsyrfs`` returns the backward errors and estimated bounds on the forward errors for the solution of a real symmetric indefinite system of linear equations with multiple right-hand sides :math:`AX = B`. The function handles each right-hand side vector (stored as a column of the matrix :math:`B`) independently, so we describe the function of ``dsyrfs`` in terms of a single right-hand side :math:`b` and solution :math:`x`. Given a computed solution :math:`x`, the function computes the `component-wise backward error` :math:`\beta`. This is the size of the smallest relative perturbation in each element of :math:`A` and :math:`b` such that :math:`x` is the exact solution of a perturbed system .. math:: \begin{array}{c}\left(A+\delta A\right)x = b+\delta b\\\left\lvert \delta a_{{ij}}\right\rvert \leq \beta \left\lvert a_{{ij}}\right\rvert \quad \text{ and }\quad \left\lvert \delta b_i\right\rvert \leq \beta \left\lvert b_i\right\rvert \text{.} \end{array} Then the function estimates a bound for the `component-wise forward error` in the computed solution, defined by: .. math:: \mathrm{max}_i\left\lvert x_i-\hat{x}_i\right\rvert /\mathrm{max}_i\left\lvert x_i\right\rvert where :math:`\hat{x}` is the true solution. For details of the method, see `the F07 Introduction <https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07intro.html>`__. .. _f07mh-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def dsytri(uplo, n, a, ipiv): r""" ``dsytri`` computes the inverse of a real symmetric indefinite matrix :math:`A`, where :math:`A` has been factorized by :meth:`dsytrf`. .. _f07mj-py2-py-doc: For full information please refer to the NAG Library document for f07mj https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07mjf.html .. _f07mj-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies how :math:`A` has been factorized. :math:`\mathrm{uplo} = \texttt{'U'}` :math:`A = PUDU^\mathrm{T}P^\mathrm{T}`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` :math:`A = PLDL^\mathrm{T}P^\mathrm{T}`, where :math:`L` is lower triangular. **n** : int :math:`n`, the order of the matrix :math:`A`. **a** : float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` Details of the factorization of :math:`A`, as returned by :meth:`dsytrf`. **ipiv** : int, array-like, shape :math:`\left(\mathrm{n}\right)` Details of the interchanges and the block structure of :math:`D`, as returned by :meth:`dsytrf`. **Returns** **a** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` The factorization is overwritten by the :math:`n\times n` symmetric matrix :math:`A^{-1}`. If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A^{-1}` is stored in the upper triangular part of the array. If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A^{-1}` is stored in the lower triangular part of the array. .. _f07mj-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. :math:`D` is singular and the inverse of :math:`A` cannot be computed. .. _f07mj-py2-py-notes: **Notes** ``dsytri`` is used to compute the inverse of a real symmetric indefinite matrix :math:`A`, the function must be preceded by a call to :meth:`dsytrf`, which computes the Bunch--Kaufman factorization of :math:`A`. If :math:`\mathrm{uplo} = \texttt{'U'}`, :math:`A = PUDU^\mathrm{T}P^\mathrm{T}` and :math:`A^{-1}` is computed by solving :math:`U^\mathrm{T}P^\mathrm{T}XPU = D^{-1}` for :math:`X`. If :math:`\mathrm{uplo} = \texttt{'L'}`, :math:`A = PLDL^\mathrm{T}P^\mathrm{T}` and :math:`A^{-1}` is computed by solving :math:`L^\mathrm{T}P^\mathrm{T}XPL = D^{-1}` for :math:`X`. .. _f07mj-py2-py-references: **References** Du Croz, J J and Higham, N J, 1992, `Stability of methods for matrix inversion`, IMA J. Numer. Anal. (12), 1--19 """ raise NotImplementedError
[docs]def zhesv(uplo, a, b): r""" ``zhesv`` computes the solution to a complex system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` Hermitian matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices. .. _f07mn-py2-py-doc: For full information please refer to the NAG Library document for f07mn https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07mnf.html .. _f07mn-py2-py-parameters: **Parameters** **uplo** : str, length 1 If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored. If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored. **a** : complex, array-like, shape :math:`\left(n, n\right)` The :math:`n\times n` Hermitian matrix :math:`A`. **b** : complex, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **a** : complex, ndarray, shape :math:`\left(n, n\right)` If no exception or warning is raised, the block diagonal matrix :math:`D` and the multipliers used to obtain the factor :math:`U` or :math:`L` from the factorization :math:`A = UDU^\mathrm{H}` or :math:`A = LDL^\mathrm{H}` as computed by :meth:`zhetrf`. **ipiv** : int, ndarray, shape :math:`\left(n\right)` Details of the interchanges and the block structure of :math:`D`. More precisely, if :math:`\mathrm{ipiv}[i-1] = k > 0`, :math:`d_{{ii}}` is a :math:`1\times 1` pivot block and the :math:`i`\ th row and column of :math:`A` were interchanged with the :math:`k`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'U'}` and :math:`\mathrm{ipiv}[i-2] = \mathrm{ipiv}[i-1] = -l < 0`, :math:`\begin{pmatrix}d_{{i-1,i-1}}&\bar{d}_{{i,i-1}}\\\bar{d}_{{i,i-1}}&d_{{ii}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i-1\right)`\ th row and column of :math:`A` were interchanged with the :math:`l`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'L'}` and :math:`\mathrm{ipiv}[i-1] = \mathrm{ipiv}[i] = -m < 0`, :math:`\begin{pmatrix}d_{{ii}}&d_{{i+1,i}}\\d_{{i+1,i}}&d_{{i+1,i+1}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i+1\right)`\ th row and column of :math:`A` were interchanged with the :math:`m`\ th row and column. **b** : complex, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`. .. _f07mn-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the block diagonal matrix :math:`D` is exactly singular, so the solution could not be computed. .. _f07mn-py2-py-notes: **Notes** ``zhesv`` uses the diagonal pivoting method to factor :math:`A` as :math:`A = UDU^\mathrm{H}` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LDL^\mathrm{H}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` (or :math:`L`) is a product of permutation and unit upper (lower) triangular matrices, and :math:`D` is Hermitian and block diagonal with :math:`1\times 1` and :math:`2\times 2` diagonal blocks. The factored form of :math:`A` is then used to solve the system of equations :math:`AX = B`. .. _f07mn-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def zhesvx(fact, uplo, a, af, ipiv, b): r""" ``zhesvx`` uses the diagonal pivoting factorization to compute the solution to a complex system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` Hermitian matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices. Error bounds on the solution and a condition estimate are also provided. .. _f07mp-py2-py-doc: For full information please refer to the NAG Library document for f07mp https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07mpf.html .. _f07mp-py2-py-parameters: **Parameters** **fact** : str, length 1 Specifies whether or not the factorized form of the matrix :math:`A` has been supplied. :math:`\mathrm{fact} = \texttt{'F'}` :math:`\mathrm{af}` and :math:`\mathrm{ipiv}` contain the factorized form of the matrix :math:`A`. :math:`\mathrm{af}` and :math:`\mathrm{ipiv}` will not be modified. :math:`\mathrm{fact} = \texttt{'N'}` The matrix :math:`A` will be copied to :math:`\mathrm{af}` and factorized. **uplo** : str, length 1 If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored. If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored. **a** : complex, array-like, shape :math:`\left(n, n\right)` The :math:`n\times n` Hermitian matrix :math:`A`. **af** : complex, array-like, shape :math:`\left(n, n\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{af}` contains the block diagonal matrix :math:`D` and the multipliers used to obtain the factor :math:`U` or :math:`L` from the factorization :math:`\mathrm{a} = UDU^\mathrm{H}` or :math:`\mathrm{a} = LDL^\mathrm{H}` as computed by :meth:`zhetrf`. **ipiv** : int, array-like, shape :math:`\left(n\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{ipiv}` contains details of the interchanges and the block structure of :math:`D`, as determined by :meth:`zhetrf`. if :math:`\mathrm{ipiv}[i-1] = k > 0`, :math:`d_{{ii}}` is a :math:`1\times 1` pivot block and the :math:`i`\ th row and column of :math:`A` were interchanged with the :math:`k`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'U'}` and :math:`\mathrm{ipiv}[i-2] = \mathrm{ipiv}[i-1] = -l < 0`, :math:`\begin{pmatrix}d_{{i-1,i-1}}&\bar{d}_{{i,i-1}}\\\bar{d}_{{i,i-1}}&d_{{ii}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i-1\right)`\ th row and column of :math:`A` were interchanged with the :math:`l`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'L'}` and :math:`\mathrm{ipiv}[i-1] = \mathrm{ipiv}[i] = -m < 0`, :math:`\begin{pmatrix}d_{{ii}}&d_{{i+1,i}}\\d_{{i+1,i}}&d_{{i+1,i+1}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i+1\right)`\ th row and column of :math:`A` were interchanged with the :math:`m`\ th row and column. **b** : complex, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **af** : complex, ndarray, shape :math:`\left(n, n\right)` If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{af}` returns the block diagonal matrix :math:`D` and the multipliers used to obtain the factor :math:`U` or :math:`L` from the factorization :math:`\mathrm{a} = UDU^\mathrm{H}` or :math:`\mathrm{a} = LDL^\mathrm{H}`. **ipiv** : int, ndarray, shape :math:`\left(n\right)` If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{ipiv}` contains details of the interchanges and the block structure of :math:`D`, as determined by :meth:`zhetrf`, as described above. **x** : complex, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, the :math:`n\times r` solution matrix :math:`X`. **rcond** : float The estimate of the reciprocal condition number of the matrix :math:`A`. If :math:`\mathrm{rcond} = 0.0`, the matrix may be exactly singular. This condition is indicated by :math:`\mathrm{errno}` in 1 ... :math:`\mathrm{n}`. Otherwise, if :math:`\mathrm{rcond}` is less than the machine precision, the matrix is singular to working precision. This condition is indicated by :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1. **ferr** : float, ndarray, shape :math:`\left(\textit{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the forward error bound for each computed solution vector, such that :math:`\left\lVert \hat{x}_j-x_j\right\rVert_\infty/\left\lVert x_j\right\rVert_\infty\leq \mathrm{ferr}[j-1]` where :math:`\hat{x}_j` is the :math:`j`\ th column of the computed solution returned in the array :math:`\mathrm{x}` and :math:`x_j` is the corresponding column of the exact solution :math:`X`. The estimate is as reliable as the estimate for :math:`\mathrm{rcond}`, and is almost always a slight overestimate of the true error. **berr** : float, ndarray, shape :math:`\left(\textit{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the component-wise relative backward error of each computed solution vector :math:`\hat{x}_j` (i.e., the smallest relative change in any element of :math:`A` or :math:`B` that makes :math:`\hat{x}_j` an exact solution). .. _f07mp-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{fact}`. Constraint: :math:`\mathrm{fact} = \texttt{'F'}` or :math:`\texttt{'N'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq n\right)`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`D` is exactly singular, so the solution and error bounds could not be computed. :math:`\mathrm{rcond} = 0.0` is returned. (`errno` :math:`n+1`) :math:`D` is nonsingular, but :math:`\mathrm{rcond}` is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of :math:`\mathrm{rcond}` would suggest. .. _f07mp-py2-py-notes: **Notes** ``zhesvx`` performs the following steps: (1) If :math:`\mathrm{fact} = \texttt{'N'}`, the diagonal pivoting method is used to factor :math:`A`. The form of the factorization is :math:`A = UDU^\mathrm{H}` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LDL^\mathrm{H}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` (or :math:`L`) is a product of permutation and unit upper (lower) triangular matrices, and :math:`D` is Hermitian and block diagonal with :math:`1\times 1` and :math:`2\times 2` diagonal blocks. (#) If some :math:`d_{{ii}} = 0`, so that :math:`D` is exactly singular, then the function returns with :math:`\textit{errno} = i`. Otherwise, the factored form of :math:`A` is used to estimate the condition number of the matrix :math:`A`. If the reciprocal of the condition number is less than machine precision, :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1 is returned as a warning, but the function still goes on to solve for :math:`X` and compute error bounds as described below. (#) The system of equations is solved for :math:`X` using the factored form of :math:`A`. (#) Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for it. .. _f07mp-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def zhetrf(uplo, n, a): r""" ``zhetrf`` computes the Bunch--Kaufman factorization of a complex Hermitian indefinite matrix. .. _f07mr-py2-py-doc: For full information please refer to the NAG Library document for f07mr https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07mrf.html .. _f07mr-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies whether the upper or lower triangular part of :math:`A` is stored and how :math:`A` is to be factorized. :math:`\mathrm{uplo} = \texttt{'U'}` The upper triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`PUDU^\mathrm{H}P^\mathrm{T}`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` The lower triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`PLDL^\mathrm{H}P^\mathrm{T}`, where :math:`L` is lower triangular. **n** : int :math:`n`, the order of the matrix :math:`A`. **a** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` The :math:`n\times n` Hermitian indefinite matrix :math:`A`. **Returns** **a** : complex, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` The upper or lower triangle of :math:`A` is overwritten by details of the block diagonal matrix :math:`D` and the multipliers used to obtain the factor :math:`U` or :math:`L` as specified by :math:`\mathrm{uplo}`. **ipiv** : int, ndarray, shape :math:`\left(\mathrm{n}\right)` Details of the interchanges and the block structure of :math:`D`. More precisely, if :math:`\mathrm{ipiv}[i-1] = k > 0`, :math:`d_{{ii}}` is a :math:`1\times 1` pivot block and the :math:`i`\ th row and column of :math:`A` were interchanged with the :math:`k`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'U'}` and :math:`\mathrm{ipiv}[i-2] = \mathrm{ipiv}[i-1] = -l < 0`, :math:`\begin{pmatrix}d_{{i-1,i-1}}&\bar{d}_{{i,i-1}}\\\bar{d}_{{i,i-1}}&d_{{ii}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i-1\right)`\ th row and column of :math:`A` were interchanged with the :math:`l`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'L'}` and :math:`\mathrm{ipiv}[i-1] = \mathrm{ipiv}[i] = -m < 0`, :math:`\begin{pmatrix}d_{{ii}}&d_{{i+1,i}}\\d_{{i+1,i}}&d_{{i+1,i+1}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i+1\right)`\ th row and column of :math:`A` were interchanged with the :math:`m`\ th row and column. .. _f07mr-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the block diagonal matrix :math:`D` is exactly singular, and division by zero will occur if it is used to solve a system of equations. .. _f07mr-py2-py-notes: **Notes** ``zhetrf`` factorizes a complex Hermitian matrix :math:`A`, using the Bunch--Kaufman diagonal pivoting method. :math:`A` is factorized either as :math:`A = PUDU^\mathrm{H}P^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = PLDL^\mathrm{H}P^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`P` is a permutation matrix, :math:`U` (or :math:`L`) is a unit upper (or lower) triangular matrix and :math:`D` is an Hermitian block diagonal matrix with :math:`1\times 1` and :math:`2\times 2` diagonal blocks; :math:`U` (or :math:`L`) has :math:`2\times 2` unit diagonal blocks corresponding to the :math:`2\times 2` blocks of :math:`D`. Row and column interchanges are performed to ensure numerical stability while keeping the matrix Hermitian. This method is suitable for Hermitian matrices which are not known to be positive definite. If :math:`A` is in fact positive definite, no interchanges are performed and no :math:`2\times 2` blocks occur in :math:`D`. .. _f07mr-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def zhetrs(uplo, a, ipiv, b): r""" ``zhetrs`` solves a complex Hermitian indefinite system of linear equations with multiple right-hand sides, .. math:: AX = B\text{,} where :math:`A` has been factorized by :meth:`zhetrf`. .. _f07ms-py2-py-doc: For full information please refer to the NAG Library document for f07ms https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07msf.html .. _f07ms-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies how :math:`A` has been factorized. :math:`\mathrm{uplo} = \texttt{'U'}` :math:`A = PUDU^\mathrm{H}P^\mathrm{T}`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` :math:`A = PLDL^\mathrm{H}P^\mathrm{T}`, where :math:`L` is lower triangular. **a** : complex, array-like, shape :math:`\left(n, n\right)` Details of the factorization of :math:`A`, as returned by :meth:`zhetrf`. **ipiv** : int, array-like, shape :math:`\left(n\right)` Details of the interchanges and the block structure of :math:`D`, as returned by :meth:`zhetrf`. **b** : complex, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **b** : complex, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`. .. _f07ms-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. .. _f07ms-py2-py-notes: **Notes** ``zhetrs`` is used to solve a complex Hermitian indefinite system of linear equations :math:`AX = B`, this function must be preceded by a call to :meth:`zhetrf` which computes the Bunch--Kaufman factorization of :math:`A`. If :math:`\mathrm{uplo} = \texttt{'U'}`, :math:`A = PUDU^\mathrm{H}P^\mathrm{T}`, where :math:`P` is a permutation matrix, :math:`U` is an upper triangular matrix and :math:`D` is an Hermitian block diagonal matrix with :math:`1\times 1` and :math:`2\times 2` blocks; the solution :math:`X` is computed by solving :math:`PUDY = B` and then :math:`U^\mathrm{H}P^\mathrm{T}X = Y`. If :math:`\mathrm{uplo} = \texttt{'L'}`, :math:`A = PLDL^\mathrm{H}P^\mathrm{T}`, where :math:`L` is a lower triangular matrix; the solution :math:`X` is computed by solving :math:`PLDY = B` and then :math:`L^\mathrm{H}P^\mathrm{T}X = Y`. .. _f07ms-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def zhecon(uplo, a, ipiv, anorm): r""" ``zhecon`` estimates the condition number of a complex Hermitian indefinite matrix :math:`A`, where :math:`A` has been factorized by :meth:`zhetrf`. .. _f07mu-py2-py-doc: For full information please refer to the NAG Library document for f07mu https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07muf.html .. _f07mu-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies how :math:`A` has been factorized. :math:`\mathrm{uplo} = \texttt{'U'}` :math:`A = PUDU^\mathrm{H}P^\mathrm{T}`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` :math:`A = PLDL^\mathrm{H}P^\mathrm{T}`, where :math:`L` is lower triangular. **a** : complex, array-like, shape :math:`\left(n, n\right)` Details of the factorization of :math:`A`, as returned by :meth:`zhetrf`. **ipiv** : int, array-like, shape :math:`\left(n\right)` Details of the interchanges and the block structure of :math:`D`, as returned by :meth:`zhetrf`. **anorm** : float The :math:`1`-norm of the **original** matrix :math:`A`, which may be computed by calling :meth:`blas.zlanhe <naginterfaces.library.blas.zlanhe>` with its argument :math:`{\textit{norm}} = \texttt{'1'}`. :math:`\mathrm{anorm}` must be computed either **before** calling :meth:`zhetrf` or else from a **copy** of the original matrix :math:`A`. **Returns** **rcond** : float An estimate of the reciprocal of the condition number of :math:`A`. :math:`\mathrm{rcond}` is set to zero if exact singularity is detected or the estimate underflows. If :math:`\mathrm{rcond}` is less than machine precision, :math:`A` is singular to working precision. .. _f07mu-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-6`) On entry, error in parameter :math:`\mathrm{anorm}`. Constraint: :math:`\mathrm{anorm}\geq 0.0`. .. _f07mu-py2-py-notes: **Notes** ``zhecon`` estimates the condition number (in the :math:`1`-norm) of a complex Hermitian indefinite matrix :math:`A`: .. math:: \kappa_1\left(A\right) = \left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\text{.} Since :math:`A` is Hermitian, :math:`\kappa_1\left(A\right) = \kappa_{\infty }\left(A\right) = \left\lVert A\right\rVert_\infty\left\lVert A^{-1}\right\rVert_\infty`. Because :math:`\kappa_1\left(A\right)` is infinite if :math:`A` is singular, the function actually returns an estimate of the **reciprocal** of :math:`\kappa_1\left(A\right)`. The function should be preceded by a call to :meth:`blas.zlanhe <naginterfaces.library.blas.zlanhe>` to compute :math:`\left\lVert A\right\rVert_1` and a call to :meth:`zhetrf` to compute the Bunch--Kaufman factorization of :math:`A`. The function then uses Higham's implementation of Hager's method (see Higham (1988)) to estimate :math:`\left\lVert A^{-1}\right\rVert_1`. .. _f07mu-py2-py-references: **References** Higham, N J, 1988, `FORTRAN codes for estimating the one-norm of a real or complex matrix, with applications to condition estimation`, ACM Trans. Math. Software (14), 381--396 """ raise NotImplementedError
[docs]def zherfs(uplo, n, a, af, ipiv, b, x): r""" ``zherfs`` returns error bounds for the solution of a complex Hermitian indefinite system of linear equations with multiple right-hand sides, :math:`AX = B`. It improves the solution by iterative refinement, in order to reduce the backward error as much as possible. .. _f07mv-py2-py-doc: For full information please refer to the NAG Library document for f07mv https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07mvf.html .. _f07mv-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies whether the upper or lower triangular part of :math:`A` is stored and how :math:`A` is to be factorized. :math:`\mathrm{uplo} = \texttt{'U'}` The upper triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`PUDU^\mathrm{H}P^\mathrm{T}`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` The lower triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`PLDL^\mathrm{H}P^\mathrm{T}`, where :math:`L` is lower triangular. **n** : int :math:`n`, the order of the matrix :math:`A`. **a** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` The :math:`n\times n` original Hermitian matrix :math:`A` as supplied to :meth:`zhetrf`. **af** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` Details of the factorization of :math:`A`, as returned by :meth:`zhetrf`. **ipiv** : int, array-like, shape :math:`\left(\mathrm{n}\right)` Details of the interchanges and the block structure of :math:`D`, as returned by :meth:`zhetrf`. **b** : complex, array-like, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **x** : complex, array-like, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`, as returned by :meth:`zhetrs`. **Returns** **x** : complex, ndarray, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The improved solution matrix :math:`X`. **ferr** : float, ndarray, shape :math:`\left(\textit{nrhs}\right)` :math:`\mathrm{ferr}[\textit{j}-1]` contains an estimated error bound for the :math:`\textit{j}`\ th solution vector, that is, the :math:`\textit{j}`\ th column of :math:`X`, for :math:`\textit{j} = 1,2,\ldots,r`. **berr** : float, ndarray, shape :math:`\left(\textit{nrhs}\right)` :math:`\mathrm{berr}[\textit{j}-1]` contains the component-wise backward error bound :math:`\beta` for the :math:`\textit{j}`\ th solution vector, that is, the :math:`\textit{j}`\ th column of :math:`X`, for :math:`\textit{j} = 1,2,\ldots,r`. .. _f07mv-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. .. _f07mv-py2-py-notes: **Notes** ``zherfs`` returns the backward errors and estimated bounds on the forward errors for the solution of a complex Hermitian indefinite system of linear equations with multiple right-hand sides :math:`AX = B`. The function handles each right-hand side vector (stored as a column of the matrix :math:`B`) independently, so we describe the function of ``zherfs`` in terms of a single right-hand side :math:`b` and solution :math:`x`. Given a computed solution :math:`x`, the function computes the `component-wise backward error` :math:`\beta`. This is the size of the smallest relative perturbation in each element of :math:`A` and :math:`b` such that :math:`x` is the exact solution of a perturbed system .. math:: \begin{array}{c}\left(A+\delta A\right)x = b+\delta b\\\left\lvert \delta a_{{ij}}\right\rvert \leq \beta \left\lvert a_{{ij}}\right\rvert \quad \text{ and }\quad \left\lvert \delta b_i\right\rvert \leq \beta \left\lvert b_i\right\rvert \text{.} \end{array} Then the function estimates a bound for the `component-wise forward error` in the computed solution, defined by: .. math:: \mathrm{max}_i\left\lvert x_i-\hat{x}_i\right\rvert /\mathrm{max}_i\left\lvert x_i\right\rvert where :math:`\hat{x}` is the true solution. For details of the method, see `the F07 Introduction <https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07intro.html>`__. .. _f07mv-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def zhetri(uplo, n, a, ipiv): r""" ``zhetri`` computes the inverse of a complex Hermitian indefinite matrix :math:`A`, where :math:`A` has been factorized by :meth:`zhetrf`. .. _f07mw-py2-py-doc: For full information please refer to the NAG Library document for f07mw https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07mwf.html .. _f07mw-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies how :math:`A` has been factorized. :math:`\mathrm{uplo} = \texttt{'U'}` :math:`A = PUDU^\mathrm{H}P^\mathrm{T}`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` :math:`A = PLDL^\mathrm{H}P^\mathrm{T}`, where :math:`L` is lower triangular. **n** : int :math:`n`, the order of the matrix :math:`A`. **a** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` Details of the factorization of :math:`A`, as returned by :meth:`zhetrf`. **ipiv** : int, array-like, shape :math:`\left(\mathrm{n}\right)` Details of the interchanges and the block structure of :math:`D`, as returned by :meth:`zhetrf`. **Returns** **a** : complex, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` The factorization is overwritten by the :math:`n\times n` Hermitian matrix :math:`A^{-1}`. If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A^{-1}` is stored in the upper triangular part of the array. If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A^{-1}` is stored in the lower triangular part of the array. .. _f07mw-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. :math:`D` is singular and the inverse of :math:`A` cannot be computed. .. _f07mw-py2-py-notes: **Notes** ``zhetri`` is used to compute the inverse of a complex Hermitian indefinite matrix :math:`A`, the function must be preceded by a call to :meth:`zhetrf`, which computes the Bunch--Kaufman factorization of :math:`A`. If :math:`\mathrm{uplo} = \texttt{'U'}`, :math:`A = PUDU^\mathrm{H}P^\mathrm{T}` and :math:`A^{-1}` is computed by solving :math:`U^\mathrm{H}P^\mathrm{T}XPU = D^{-1}` for :math:`X`. If :math:`\mathrm{uplo} = \texttt{'L'}`, :math:`A = PLDL^\mathrm{H}P^\mathrm{T}` and :math:`A^{-1}` is computed by solving :math:`L^\mathrm{H}P^\mathrm{T}XPL = D^{-1}` for :math:`X`. .. _f07mw-py2-py-references: **References** Du Croz, J J and Higham, N J, 1992, `Stability of methods for matrix inversion`, IMA J. Numer. Anal. (12), 1--19 """ raise NotImplementedError
[docs]def zsysv(uplo, a, b): r""" ``zsysv`` computes the solution to a complex system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` symmetric matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices. .. _f07nn-py2-py-doc: For full information please refer to the NAG Library document for f07nn https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07nnf.html .. _f07nn-py2-py-parameters: **Parameters** **uplo** : str, length 1 If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored. If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored. **a** : complex, array-like, shape :math:`\left(n, n\right)` The :math:`n\times n` symmetric matrix :math:`A`. **b** : complex, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **a** : complex, ndarray, shape :math:`\left(n, n\right)` If no exception or warning is raised, the block diagonal matrix :math:`D` and the multipliers used to obtain the factor :math:`U` or :math:`L` from the factorization :math:`A = UDU^\mathrm{H}` or :math:`A = LDL^\mathrm{H}` as computed by :meth:`zsytrf`. **ipiv** : int, ndarray, shape :math:`\left(n\right)` Details of the interchanges and the block structure of :math:`D`. More precisely, if :math:`\mathrm{ipiv}[i-1] = k > 0`, :math:`d_{{ii}}` is a :math:`1\times 1` pivot block and the :math:`i`\ th row and column of :math:`A` were interchanged with the :math:`k`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'U'}` and :math:`\mathrm{ipiv}[i-2] = \mathrm{ipiv}[i-1] = -l < 0`, :math:`\begin{pmatrix}d_{{i-1,i-1}}&\bar{d}_{{i,i-1}}\\\bar{d}_{{i,i-1}}&d_{{ii}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i-1\right)`\ th row and column of :math:`A` were interchanged with the :math:`l`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'L'}` and :math:`\mathrm{ipiv}[i-1] = \mathrm{ipiv}[i] = -m < 0`, :math:`\begin{pmatrix}d_{{ii}}&d_{{i+1,i}}\\d_{{i+1,i}}&d_{{i+1,i+1}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i+1\right)`\ th row and column of :math:`A` were interchanged with the :math:`m`\ th row and column. **b** : complex, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`. .. _f07nn-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the block diagonal matrix :math:`D` is exactly singular, so the solution could not be computed. .. _f07nn-py2-py-notes: **Notes** ``zsysv`` uses the diagonal pivoting method to factor :math:`A` as :math:`A = UDU^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LDL^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` (or :math:`L`) is a product of permutation and unit upper (lower) triangular matrices, and :math:`D` is symmetric and block diagonal with :math:`1\times 1` and :math:`2\times 2` diagonal blocks. The factored form of :math:`A` is then used to solve the system of equations :math:`AX = B`. .. _f07nn-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def zsysvx(fact, uplo, a, af, ipiv, b): r""" ``zsysvx`` uses the diagonal pivoting factorization to compute the solution to a complex system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` symmetric matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices. Error bounds on the solution and a condition estimate are also provided. .. _f07np-py2-py-doc: For full information please refer to the NAG Library document for f07np https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07npf.html .. _f07np-py2-py-parameters: **Parameters** **fact** : str, length 1 Specifies whether or not the factorized form of the matrix :math:`A` has been supplied. :math:`\mathrm{fact} = \texttt{'F'}` :math:`\mathrm{af}` and :math:`\mathrm{ipiv}` contain the factorized form of the matrix :math:`A`. :math:`\mathrm{af}` and :math:`\mathrm{ipiv}` will not be modified. :math:`\mathrm{fact} = \texttt{'N'}` The matrix :math:`A` will be copied to :math:`\mathrm{af}` and factorized. **uplo** : str, length 1 If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored. If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored. **a** : complex, array-like, shape :math:`\left(n, n\right)` The :math:`n\times n` symmetric matrix :math:`A`. **af** : complex, array-like, shape :math:`\left(n, n\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{af}` contains the block diagonal matrix :math:`D` and the multipliers used to obtain the factor :math:`U` or :math:`L` from the factorization :math:`\mathrm{a} = UDU^\mathrm{H}` or :math:`\mathrm{a} = LDL^\mathrm{H}` as computed by :meth:`zsytrf`. **ipiv** : int, array-like, shape :math:`\left(n\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{ipiv}` contains details of the interchanges and the block structure of :math:`D`, as determined by :meth:`zsytrf`. if :math:`\mathrm{ipiv}[i-1] = k > 0`, :math:`d_{{ii}}` is a :math:`1\times 1` pivot block and the :math:`i`\ th row and column of :math:`A` were interchanged with the :math:`k`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'U'}` and :math:`\mathrm{ipiv}[i-2] = \mathrm{ipiv}[i-1] = -l < 0`, :math:`\begin{pmatrix}d_{{i-1,i-1}}&\bar{d}_{{i,i-1}}\\\bar{d}_{{i,i-1}}&d_{{ii}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i-1\right)`\ th row and column of :math:`A` were interchanged with the :math:`l`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'L'}` and :math:`\mathrm{ipiv}[i-1] = \mathrm{ipiv}[i] = -m < 0`, :math:`\begin{pmatrix}d_{{ii}}&d_{{i+1,i}}\\d_{{i+1,i}}&d_{{i+1,i+1}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i+1\right)`\ th row and column of :math:`A` were interchanged with the :math:`m`\ th row and column. **b** : complex, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **af** : complex, ndarray, shape :math:`\left(n, n\right)` If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{af}` returns the block diagonal matrix :math:`D` and the multipliers used to obtain the factor :math:`U` or :math:`L` from the factorization :math:`\mathrm{a} = UDU^\mathrm{H}` or :math:`\mathrm{a} = LDL^\mathrm{H}`. **ipiv** : int, ndarray, shape :math:`\left(n\right)` If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{ipiv}` contains details of the interchanges and the block structure of :math:`D`, as determined by :meth:`zsytrf`, as described above. **x** : complex, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, the :math:`n\times r` solution matrix :math:`X`. **rcond** : float The estimate of the reciprocal condition number of the matrix :math:`A`. If :math:`\mathrm{rcond} = 0.0`, the matrix may be exactly singular. This condition is indicated by :math:`\mathrm{errno}` in 1 ... :math:`\mathrm{n}`. Otherwise, if :math:`\mathrm{rcond}` is less than the machine precision, the matrix is singular to working precision. This condition is indicated by :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1. **ferr** : float, ndarray, shape :math:`\left(\textit{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the forward error bound for each computed solution vector, such that :math:`\left\lVert \hat{x}_j-x_j\right\rVert_\infty/\left\lVert x_j\right\rVert_\infty\leq \mathrm{ferr}[j-1]` where :math:`\hat{x}_j` is the :math:`j`\ th column of the computed solution returned in the array :math:`\mathrm{x}` and :math:`x_j` is the corresponding column of the exact solution :math:`X`. The estimate is as reliable as the estimate for :math:`\mathrm{rcond}`, and is almost always a slight overestimate of the true error. **berr** : float, ndarray, shape :math:`\left(\textit{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the component-wise relative backward error of each computed solution vector :math:`\hat{x}_j` (i.e., the smallest relative change in any element of :math:`A` or :math:`B` that makes :math:`\hat{x}_j` an exact solution). .. _f07np-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{fact}`. Constraint: :math:`\mathrm{fact} = \texttt{'F'}` or :math:`\texttt{'N'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq n\right)`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`D` is exactly singular, so the solution and error bounds could not be computed. :math:`\mathrm{rcond} = 0.0` is returned. (`errno` :math:`n+1`) :math:`D` is nonsingular, but :math:`\mathrm{rcond}` is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of :math:`\mathrm{rcond}` would suggest. .. _f07np-py2-py-notes: **Notes** ``zsysvx`` performs the following steps: (1) If :math:`\mathrm{fact} = \texttt{'N'}`, the diagonal pivoting method is used to factor :math:`A`. The form of the factorization is :math:`A = UDU^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LDL^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` (or :math:`L`) is a product of permutation and unit upper (lower) triangular matrices, and :math:`D` is symmetric and block diagonal with :math:`1\times 1` and :math:`2\times 2` diagonal blocks. (#) If some :math:`d_{{ii}} = 0`, so that :math:`D` is exactly singular, then the function returns with :math:`\textit{errno} = i`. Otherwise, the factored form of :math:`A` is used to estimate the condition number of the matrix :math:`A`. If the reciprocal of the condition number is less than machine precision, :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1 is returned as a warning, but the function still goes on to solve for :math:`X` and compute error bounds as described below. (#) The system of equations is solved for :math:`X` using the factored form of :math:`A`. (#) Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for it. .. _f07np-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def zsytrf(uplo, a): r""" ``zsytrf`` computes the Bunch--Kaufman factorization of a complex symmetric matrix. .. _f07nr-py2-py-doc: For full information please refer to the NAG Library document for f07nr https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07nrf.html .. _f07nr-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies whether the upper or lower triangular part of :math:`A` is stored and how :math:`A` is to be factorized. :math:`\mathrm{uplo} = \texttt{'U'}` The upper triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`PUDU^\mathrm{H}P^\mathrm{T}`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` The lower triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`PLDL^\mathrm{H}P^\mathrm{T}`, where :math:`L` is lower triangular. **a** : complex, array-like, shape :math:`\left(n, n\right)` The :math:`n\times n` symmetric indefinite matrix :math:`A`. **Returns** **a** : complex, ndarray, shape :math:`\left(n, n\right)` The upper or lower triangle of :math:`A` is overwritten by details of the block diagonal matrix :math:`D` and the multipliers used to obtain the factor :math:`U` or :math:`L` as specified by :math:`\mathrm{uplo}`. **ipiv** : int, ndarray, shape :math:`\left(n\right)` Details of the interchanges and the block structure of :math:`D`. More precisely, if :math:`\mathrm{ipiv}[i-1] = k > 0`, :math:`d_{{ii}}` is a :math:`1\times 1` pivot block and the :math:`i`\ th row and column of :math:`A` were interchanged with the :math:`k`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'U'}` and :math:`\mathrm{ipiv}[i-2] = \mathrm{ipiv}[i-1] = -l < 0`, :math:`\begin{pmatrix}d_{{i-1,i-1}}&\bar{d}_{{i,i-1}}\\\bar{d}_{{i,i-1}}&d_{{ii}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i-1\right)`\ th row and column of :math:`A` were interchanged with the :math:`l`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'L'}` and :math:`\mathrm{ipiv}[i-1] = \mathrm{ipiv}[i] = -m < 0`, :math:`\begin{pmatrix}d_{{ii}}&d_{{i+1,i}}\\d_{{i+1,i}}&d_{{i+1,i+1}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i+1\right)`\ th row and column of :math:`A` were interchanged with the :math:`m`\ th row and column. .. _f07nr-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the block diagonal matrix :math:`D` is exactly singular, and division by zero will occur if it is used to solve a system of equations. .. _f07nr-py2-py-notes: **Notes** ``zsytrf`` factorizes a complex symmetric matrix :math:`A`, using the Bunch--Kaufman diagonal pivoting method. :math:`A` is factorized as either :math:`A = PUDU^\mathrm{T}P^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = PLDL^\mathrm{T}P^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`P` is a permutation matrix, :math:`U` (or :math:`L`) is a unit upper (or lower) triangular matrix and :math:`D` is a symmetric block diagonal matrix with :math:`1\times 1` and :math:`2\times 2` diagonal blocks; :math:`U` (or :math:`L`) has :math:`2\times 2` unit diagonal blocks corresponding to the :math:`2\times 2` blocks of :math:`D`. Row and column interchanges are performed to ensure numerical stability while preserving symmetry. .. _f07nr-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def zsytrs(uplo, a, ipiv, b): r""" ``zsytrs`` solves a complex symmetric system of linear equations with multiple right-hand sides, .. math:: AX = B\text{,} where :math:`A` has been factorized by :meth:`zsytrf`. .. _f07ns-py2-py-doc: For full information please refer to the NAG Library document for f07ns https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07nsf.html .. _f07ns-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies how :math:`A` has been factorized. :math:`\mathrm{uplo} = \texttt{'U'}` :math:`A = PUDU^\mathrm{H}P^\mathrm{T}`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` :math:`A = PLDL^\mathrm{H}P^\mathrm{T}`, where :math:`L` is lower triangular. **a** : complex, array-like, shape :math:`\left(n, n\right)` Details of the factorization of :math:`A`, as returned by :meth:`zsytrf`. **ipiv** : int, array-like, shape :math:`\left(n\right)` Details of the interchanges and the block structure of :math:`D`, as returned by :meth:`zsytrf`. **b** : complex, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **b** : complex, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`. .. _f07ns-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. .. _f07ns-py2-py-notes: **Notes** ``zsytrs`` is used to solve a complex symmetric system of linear equations :math:`AX = B`, this function must be preceded by a call to :meth:`zsytrf` which computes the Bunch--Kaufman factorization of :math:`A`. If :math:`\mathrm{uplo} = \texttt{'U'}`, :math:`A = PUDU^\mathrm{T}P^\mathrm{T}`, where :math:`P` is a permutation matrix, :math:`U` is an upper triangular matrix and :math:`D` is a symmetric block diagonal matrix with :math:`1\times 1` and :math:`2\times 2` blocks; the solution :math:`X` is computed by solving :math:`PUDY = B` and then :math:`U^\mathrm{T}P^\mathrm{T}X = Y`. If :math:`\mathrm{uplo} = \texttt{'L'}`, :math:`A = PLDL^\mathrm{T}P^\mathrm{T}`, where :math:`L` is a lower triangular matrix; the solution :math:`X` is computed by solving :math:`PLDY = B` and then :math:`L^\mathrm{T}P^\mathrm{T}X = Y`. .. _f07ns-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def zsycon(uplo, a, ipiv, anorm): r""" ``zsycon`` estimates the condition number of a complex symmetric matrix :math:`A`, where :math:`A` has been factorized by :meth:`zsytrf`. .. _f07nu-py2-py-doc: For full information please refer to the NAG Library document for f07nu https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07nuf.html .. _f07nu-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies how :math:`A` has been factorized. :math:`\mathrm{uplo} = \texttt{'U'}` :math:`A = PUDU^\mathrm{H}P^\mathrm{T}`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` :math:`A = PLDL^\mathrm{H}P^\mathrm{T}`, where :math:`L` is lower triangular. **a** : complex, array-like, shape :math:`\left(n, n\right)` Details of the factorization of :math:`A`, as returned by :meth:`zsytrf`. **ipiv** : int, array-like, shape :math:`\left(n\right)` Details of the interchanges and the block structure of :math:`D`, as returned by :meth:`zsytrf`. **anorm** : float The :math:`1`-norm of the **original** matrix :math:`A`, which may be computed by calling :meth:`blas.zlansy <naginterfaces.library.blas.zlansy>` with its argument :math:`{\textit{norm}} = \texttt{'1'}`. :math:`\mathrm{anorm}` must be computed either **before** calling :meth:`zsytrf` or else from a **copy** of the original matrix :math:`A`. **Returns** **rcond** : float An estimate of the reciprocal of the condition number of :math:`A`. :math:`\mathrm{rcond}` is set to zero if exact singularity is detected or the estimate underflows. If :math:`\mathrm{rcond}` is less than machine precision, :math:`A` is singular to working precision. .. _f07nu-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-6`) On entry, error in parameter :math:`\mathrm{anorm}`. Constraint: :math:`\mathrm{anorm}\geq 0.0`. .. _f07nu-py2-py-notes: **Notes** ``zsycon`` estimates the condition number (in the :math:`1`-norm) of a complex symmetric matrix :math:`A`: .. math:: \kappa_1\left(A\right) = \left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\text{.} Since :math:`A` is symmetric, :math:`\kappa_1\left(A\right) = \kappa_{\infty }\left(A\right) = \left\lVert A\right\rVert_\infty\left\lVert A^{-1}\right\rVert_\infty`. Because :math:`\kappa_1\left(A\right)` is infinite if :math:`A` is singular, the function actually returns an estimate of the **reciprocal** of :math:`\kappa_1\left(A\right)`. The function should be preceded by a call to :meth:`blas.zlansy <naginterfaces.library.blas.zlansy>` to compute :math:`\left\lVert A\right\rVert_1` and a call to :meth:`zsytrf` to compute the Bunch--Kaufman factorization of :math:`A`. The function then uses Higham's implementation of Hager's method (see Higham (1988)) to estimate :math:`\left\lVert A^{-1}\right\rVert_1`. .. _f07nu-py2-py-references: **References** Higham, N J, 1988, `FORTRAN codes for estimating the one-norm of a real or complex matrix, with applications to condition estimation`, ACM Trans. Math. Software (14), 381--396 """ raise NotImplementedError
[docs]def zsyrfs(uplo, n, a, af, ipiv, b, x): r""" ``zsyrfs`` returns error bounds for the solution of a complex symmetric system of linear equations with multiple right-hand sides, :math:`AX = B`. It improves the solution by iterative refinement, in order to reduce the backward error as much as possible. .. _f07nv-py2-py-doc: For full information please refer to the NAG Library document for f07nv https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07nvf.html .. _f07nv-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies whether the upper or lower triangular part of :math:`A` is stored and how :math:`A` is to be factorized. :math:`\mathrm{uplo} = \texttt{'U'}` The upper triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`PUDU^\mathrm{H}P^\mathrm{T}`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` The lower triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`PLDL^\mathrm{H}P^\mathrm{T}`, where :math:`L` is lower triangular. **n** : int :math:`n`, the order of the matrix :math:`A`. **a** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` The :math:`n\times n` original symmetric matrix :math:`A` as supplied to :meth:`zsytrf`. **af** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)` Details of the factorization of :math:`A`, as returned by :meth:`zsytrf`. **ipiv** : int, array-like, shape :math:`\left(\mathrm{n}\right)` Details of the interchanges and the block structure of :math:`D`, as returned by :meth:`zsytrf`. **b** : complex, array-like, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **x** : complex, array-like, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`, as returned by :meth:`zsytrs`. **Returns** **x** : complex, ndarray, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The improved solution matrix :math:`X`. **ferr** : float, ndarray, shape :math:`\left(\textit{nrhs}\right)` :math:`\mathrm{ferr}[\textit{j}-1]` contains an estimated error bound for the :math:`\textit{j}`\ th solution vector, that is, the :math:`\textit{j}`\ th column of :math:`X`, for :math:`\textit{j} = 1,2,\ldots,r`. **berr** : float, ndarray, shape :math:`\left(\textit{nrhs}\right)` :math:`\mathrm{berr}[\textit{j}-1]` contains the component-wise backward error bound :math:`\beta` for the :math:`\textit{j}`\ th solution vector, that is, the :math:`\textit{j}`\ th column of :math:`X`, for :math:`\textit{j} = 1,2,\ldots,r`. .. _f07nv-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. .. _f07nv-py2-py-notes: **Notes** ``zsyrfs`` returns the backward errors and estimated bounds on the forward errors for the solution of a complex symmetric system of linear equations with multiple right-hand sides :math:`AX = B`. The function handles each right-hand side vector (stored as a column of the matrix :math:`B`) independently, so we describe the function of ``zsyrfs`` in terms of a single right-hand side :math:`b` and solution :math:`x`. Given a computed solution :math:`x`, the function computes the `component-wise backward error` :math:`\beta`. This is the size of the smallest relative perturbation in each element of :math:`A` and :math:`b` such that :math:`x` is the exact solution of a perturbed system .. math:: \begin{array}{c}\left(A+\delta A\right)x = b+\delta b\\\left\lvert \delta a_{{ij}}\right\rvert \leq \beta \left\lvert a_{{ij}}\right\rvert \quad \text{ and }\quad \left\lvert \delta b_i\right\rvert \leq \beta \left\lvert b_i\right\rvert \text{.} \end{array} Then the function estimates a bound for the `component-wise forward error` in the computed solution, defined by: .. math:: \mathrm{max}_i\left\lvert x_i-\hat{x}_i\right\rvert /\mathrm{max}_i\left\lvert x_i\right\rvert where :math:`\hat{x}` is the true solution. For details of the method, see `the F07 Introduction <https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07intro.html>`__. .. _f07nv-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def zsytri(uplo, a, ipiv): r""" ``zsytri`` computes the inverse of a complex symmetric matrix :math:`A`, where :math:`A` has been factorized by :meth:`zsytrf`. .. _f07nw-py2-py-doc: For full information please refer to the NAG Library document for f07nw https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07nwf.html .. _f07nw-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies how :math:`A` has been factorized. :math:`\mathrm{uplo} = \texttt{'U'}` :math:`A = PUDU^\mathrm{H}P^\mathrm{T}`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` :math:`A = PLDL^\mathrm{H}P^\mathrm{T}`, where :math:`L` is lower triangular. **a** : complex, array-like, shape :math:`\left(n, n\right)` Details of the factorization of :math:`A`, as returned by :meth:`zsytrf`. **ipiv** : int, array-like, shape :math:`\left(n\right)` Details of the interchanges and the block structure of :math:`D`, as returned by :meth:`zsytrf`. **Returns** **a** : complex, ndarray, shape :math:`\left(n, n\right)` The factorization is overwritten by the :math:`n\times n` symmetric matrix :math:`A^{-1}`. If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A^{-1}` is stored in the upper triangular part of the array. If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A^{-1}` is stored in the lower triangular part of the array. .. _f07nw-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. :math:`D` is singular and the inverse of :math:`A` cannot be computed. .. _f07nw-py2-py-notes: **Notes** ``zsytri`` is used to compute the inverse of a complex symmetric matrix :math:`A`, the function must be preceded by a call to :meth:`zsytrf`, which computes the Bunch--Kaufman factorization of :math:`A`. If :math:`\mathrm{uplo} = \texttt{'U'}`, :math:`A = PUDU^\mathrm{T}P^\mathrm{T}` and :math:`A^{-1}` is computed by solving :math:`U^\mathrm{T}P^\mathrm{T}XPU = D^{-1}` for :math:`X`. If :math:`\mathrm{uplo} = \texttt{'L'}`, :math:`A = PLDL^\mathrm{T}P^\mathrm{T}` and :math:`A^{-1}` is computed by solving :math:`L^\mathrm{T}P^\mathrm{T}XPL = D^{-1}` for :math:`X`. .. _f07nw-py2-py-references: **References** Du Croz, J J and Higham, N J, 1992, `Stability of methods for matrix inversion`, IMA J. Numer. Anal. (12), 1--19 """ raise NotImplementedError
[docs]def dspsv(uplo, ap, b): r""" ``dspsv`` computes the solution to a real system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` symmetric matrix stored in packed format and :math:`X` and :math:`B` are :math:`n\times r` matrices. .. _f07pa-py2-py-doc: For full information please refer to the NAG Library document for f07pa https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07paf.html .. _f07pa-py2-py-parameters: **Parameters** **uplo** : str, length 1 If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored. If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored. **ap** : float, array-like, shape :math:`\left(n\times \left(n+1\right)/2\right)` The :math:`n\times n` symmetric matrix :math:`A`, packed by columns. **b** : float, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **ap** : float, ndarray, shape :math:`\left(n\times \left(n+1\right)/2\right)` The block diagonal matrix :math:`D` and the multipliers used to obtain the factor :math:`U` or :math:`L` from the factorization :math:`A = UDU^\mathrm{T}` or :math:`A = LDL^\mathrm{T}` as computed by :meth:`dsptrf`, stored as a packed triangular matrix in the same storage format as :math:`A`. **ipiv** : int, ndarray, shape :math:`\left(n\right)` Details of the interchanges and the block structure of :math:`D`. More precisely, if :math:`\mathrm{ipiv}[i-1] = k > 0`, :math:`d_{{ii}}` is a :math:`1\times 1` pivot block and the :math:`i`\ th row and column of :math:`A` were interchanged with the :math:`k`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'U'}` and :math:`\mathrm{ipiv}[i-2] = \mathrm{ipiv}[i-1] = -l < 0`, :math:`\begin{pmatrix}d_{{i-1,i-1}}&\bar{d}_{{i,i-1}}\\\bar{d}_{{i,i-1}}&d_{{ii}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i-1\right)`\ th row and column of :math:`A` were interchanged with the :math:`l`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'L'}` and :math:`\mathrm{ipiv}[i-1] = \mathrm{ipiv}[i] = -m < 0`, :math:`\begin{pmatrix}d_{{ii}}&d_{{i+1,i}}\\d_{{i+1,i}}&d_{{i+1,i+1}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i+1\right)`\ th row and column of :math:`A` were interchanged with the :math:`m`\ th row and column. **b** : float, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`. .. _f07pa-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the block diagonal matrix :math:`D` is exactly singular, so the solution could not be computed. .. _f07pa-py2-py-notes: **Notes** ``dspsv`` uses the diagonal pivoting method to factor :math:`A` as :math:`A = UDU^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LDL^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` (or :math:`L`) is a product of permutation and unit upper (lower) triangular matrices, :math:`D` is symmetric and block diagonal with :math:`1\times 1` and :math:`2\times 2` diagonal blocks. The factored form of :math:`A` is then used to solve the system of equations :math:`AX = B`. .. _f07pa-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def dspsvx(fact, uplo, nrhs, ap, afp, ipiv, b): r""" ``dspsvx`` uses the diagonal pivoting factorization .. math:: A = UDU^\mathrm{T}\quad \text{ or }\quad A = LDL^\mathrm{T} to compute the solution to a real system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` symmetric matrix stored in packed format and :math:`X` and :math:`B` are :math:`n\times r` matrices. Error bounds on the solution and a condition estimate are also provided. .. _f07pb-py2-py-doc: For full information please refer to the NAG Library document for f07pb https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07pbf.html .. _f07pb-py2-py-parameters: **Parameters** **fact** : str, length 1 Specifies whether or not the factorized form of the matrix :math:`A` has been supplied. :math:`\mathrm{fact} = \texttt{'F'}` :math:`\mathrm{afp}` and :math:`\mathrm{ipiv}` contain the factorized form of the matrix :math:`A`. :math:`\mathrm{afp}` and :math:`\mathrm{ipiv}` will not be modified. :math:`\mathrm{fact} = \texttt{'N'}` The matrix :math:`A` will be copied to :math:`\mathrm{afp}` and factorized. **uplo** : str, length 1 If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored. If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored. **nrhs** : int :math:`r`, the number of right-hand sides, i.e., the number of columns of the matrix :math:`B`. **ap** : float, array-like, shape :math:`\left(n\times \left(n+1\right)/2\right)` The :math:`n\times n` symmetric matrix :math:`A`, packed by columns. **afp** : float, array-like, shape :math:`\left(n\times \left(n+1\right)/2\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{afp}` contains the block diagonal matrix :math:`D` and the multipliers used to obtain the factor :math:`U` or :math:`L` from the factorization :math:`A = UDU^\mathrm{T}` or :math:`A = LDL^\mathrm{T}` as computed by :meth:`dsptrf`, stored as a packed triangular matrix in the same storage format as :math:`A`. **ipiv** : int, array-like, shape :math:`\left(n\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{ipiv}` contains details of the interchanges and the block structure of :math:`D`, as determined by :meth:`dsptrf`. if :math:`\mathrm{ipiv}[i-1] = k > 0`, :math:`d_{{ii}}` is a :math:`1\times 1` pivot block and the :math:`i`\ th row and column of :math:`A` were interchanged with the :math:`k`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'U'}` and :math:`\mathrm{ipiv}[i-2] = \mathrm{ipiv}[i-1] = -l < 0`, :math:`\begin{pmatrix}d_{{i-1,i-1}}&\bar{d}_{{i,i-1}}\\\bar{d}_{{i,i-1}}&d_{{ii}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i-1\right)`\ th row and column of :math:`A` were interchanged with the :math:`l`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'L'}` and :math:`\mathrm{ipiv}[i-1] = \mathrm{ipiv}[i] = -m < 0`, :math:`\begin{pmatrix}d_{{ii}}&d_{{i+1,i}}\\d_{{i+1,i}}&d_{{i+1,i+1}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i+1\right)`\ th row and column of :math:`A` were interchanged with the :math:`m`\ th row and column. **b** : float, array-like, shape :math:`\left(n, \mathrm{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **afp** : float, ndarray, shape :math:`\left(n\times \left(n+1\right)/2\right)` If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{afp}` contains the block diagonal matrix :math:`D` and the multipliers used to obtain the factor :math:`U` or :math:`L` from the factorization :math:`A = UDU^\mathrm{T}` or :math:`A = LDL^\mathrm{T}` as computed by :meth:`dsptrf`, stored as a packed triangular matrix in the same storage format as :math:`A`. **ipiv** : int, ndarray, shape :math:`\left(n\right)` If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{ipiv}` contains details of the interchanges and the block structure of :math:`D`, as determined by :meth:`dsptrf`, as described above. **x** : float, ndarray, shape :math:`\left(n, \mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, the :math:`n\times r` solution matrix :math:`X`. **rcond** : float The estimate of the reciprocal condition number of the matrix :math:`A`. If :math:`\mathrm{rcond} = 0.0`, the matrix may be exactly singular. This condition is indicated by :math:`\mathrm{errno}` in 1 ... :math:`\mathrm{n}`. Otherwise, if :math:`\mathrm{rcond}` is less than the machine precision, the matrix is singular to working precision. This condition is indicated by :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1. **ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the forward error bound for each computed solution vector, such that :math:`\left\lVert \hat{x}_j-x_j\right\rVert_\infty/\left\lVert x_j\right\rVert_\infty\leq \mathrm{ferr}[j-1]` where :math:`\hat{x}_j` is the :math:`j`\ th column of the computed solution returned in the array :math:`\mathrm{x}` and :math:`x_j` is the corresponding column of the exact solution :math:`X`. The estimate is as reliable as the estimate for :math:`\mathrm{rcond}`, and is almost always a slight overestimate of the true error. **berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the component-wise relative backward error of each computed solution vector :math:`\hat{x}_j` (i.e., the smallest relative change in any element of :math:`A` or :math:`B` that makes :math:`\hat{x}_j` an exact solution). .. _f07pb-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{fact}`. Constraint: :math:`\mathrm{fact} = \texttt{'F'}` or :math:`\texttt{'N'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\mathrm{nrhs}`. Constraint: :math:`\mathrm{nrhs}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq n\right)`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`D` is exactly singular, so the solution and error bounds could not be computed. :math:`\mathrm{rcond} = 0.0` is returned. (`errno` :math:`n+1`) :math:`D` is nonsingular, but :math:`\mathrm{rcond}` is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of :math:`\mathrm{rcond}` would suggest. .. _f07pb-py2-py-notes: **Notes** ``dspsvx`` performs the following steps: (1) If :math:`\mathrm{fact} = \texttt{'N'}`, the diagonal pivoting method is used to factor :math:`A` as :math:`A = UDU^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LDL^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` (or :math:`L`) is a product of permutation and unit upper (lower) triangular matrices and :math:`D` is symmetric and block diagonal with :math:`1\times 1` and :math:`2\times 2` diagonal blocks. (#) If some :math:`d_{{ii}} = 0`, so that :math:`D` is exactly singular, then the function returns with :math:`\textit{errno} = i`. Otherwise, the factored form of :math:`A` is used to estimate the condition number of the matrix :math:`A`. If the reciprocal of the condition number is less than machine precision, :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1 is returned as a warning, but the function still goes on to solve for :math:`X` and compute error bounds as described below. (#) The system of equations is solved for :math:`X` using the factored form of :math:`A`. (#) Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for it. .. _f07pb-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def dsptrf(uplo, n, ap): r""" ``dsptrf`` computes the Bunch--Kaufman factorization of a real symmetric indefinite matrix, using packed storage. .. _f07pd-py2-py-doc: For full information please refer to the NAG Library document for f07pd https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07pdf.html .. _f07pd-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies whether the upper or lower triangular part of :math:`A` is stored and how :math:`A` is to be factorized. :math:`\mathrm{uplo} = \texttt{'U'}` The upper triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`PUDU^\mathrm{T}P^\mathrm{T}`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` The lower triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`PLDL^\mathrm{T}P^\mathrm{T}`, where :math:`L` is lower triangular. **n** : int :math:`n`, the order of the matrix :math:`A`. **ap** : float, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` The :math:`n\times n` symmetric matrix :math:`A`, packed by columns. **Returns** **ap** : float, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` :math:`A` is overwritten by details of the block diagonal matrix :math:`D` and the multipliers used to obtain the factor :math:`U` or :math:`L` as specified by :math:`\mathrm{uplo}`. **ipiv** : int, ndarray, shape :math:`\left(\mathrm{n}\right)` Details of the interchanges and the block structure of :math:`D`. More precisely, if :math:`\mathrm{ipiv}[i-1] = k > 0`, :math:`d_{{ii}}` is a :math:`1\times 1` pivot block and the :math:`i`\ th row and column of :math:`A` were interchanged with the :math:`k`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'U'}` and :math:`\mathrm{ipiv}[i-2] = \mathrm{ipiv}[i-1] = -l < 0`, :math:`\begin{pmatrix}d_{{i-1,i-1}}&\bar{d}_{{i,i-1}}\\\bar{d}_{{i,i-1}}&d_{{ii}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i-1\right)`\ th row and column of :math:`A` were interchanged with the :math:`l`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'L'}` and :math:`\mathrm{ipiv}[i-1] = \mathrm{ipiv}[i] = -m < 0`, :math:`\begin{pmatrix}d_{{ii}}&d_{{i+1,i}}\\d_{{i+1,i}}&d_{{i+1,i+1}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i+1\right)`\ th row and column of :math:`A` were interchanged with the :math:`m`\ th row and column. .. _f07pd-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the block diagonal matrix :math:`D` is exactly singular, and division by zero will occur if it is used to solve a system of equations. .. _f07pd-py2-py-notes: **Notes** ``dsptrf`` factorizes a real symmetric matrix :math:`A`, using the Bunch--Kaufman diagonal pivoting method and packed storage. :math:`A` is factorized as either :math:`A = PUDU^\mathrm{T}P^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = PLDL^\mathrm{T}P^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`P` is a permutation matrix, :math:`U` (or :math:`L`) is a unit upper (or lower) triangular matrix and :math:`D` is a symmetric block diagonal matrix with :math:`1\times 1` and :math:`2\times 2` diagonal blocks; :math:`U` (or :math:`L`) has :math:`2\times 2` unit diagonal blocks corresponding to the :math:`2\times 2` blocks of :math:`D`. Row and column interchanges are performed to ensure numerical stability while preserving symmetry. This method is suitable for symmetric matrices which are not known to be positive definite. If :math:`A` is in fact positive definite, no interchanges are performed and no :math:`2\times 2` blocks occur in :math:`D`. .. _f07pd-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def dsptrs(uplo, n, ap, ipiv, b): r""" ``dsptrs`` solves a real symmetric indefinite system of linear equations with multiple right-hand sides, .. math:: AX = B\text{,} where :math:`A` has been factorized by :meth:`dsptrf`, using packed storage. .. _f07pe-py2-py-doc: For full information please refer to the NAG Library document for f07pe https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07pef.html .. _f07pe-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies how :math:`A` has been factorized. :math:`\mathrm{uplo} = \texttt{'U'}` :math:`A = PUDU^\mathrm{T}P^\mathrm{T}`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` :math:`A = PLDL^\mathrm{T}P^\mathrm{T}`, where :math:`L` is lower triangular. **n** : int :math:`n`, the order of the matrix :math:`A`. **ap** : float, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` The factorization of :math:`A` stored in packed form, as returned by :meth:`dsptrf`. **ipiv** : int, array-like, shape :math:`\left(\mathrm{n}\right)` Details of the interchanges and the block structure of :math:`D`, as returned by :meth:`dsptrf`. **b** : float, array-like, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **b** : float, ndarray, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`. .. _f07pe-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. .. _f07pe-py2-py-notes: **Notes** ``dsptrs`` is used to solve a real symmetric indefinite system of linear equations :math:`AX = B`, the function must be preceded by a call to :meth:`dsptrf` which computes the Bunch--Kaufman factorization of :math:`A`, using packed storage. If :math:`\mathrm{uplo} = \texttt{'U'}`, :math:`A = PUDU^\mathrm{T}P^\mathrm{T}`, where :math:`P` is a permutation matrix, :math:`U` is an upper triangular matrix and :math:`D` is a symmetric block diagonal matrix with :math:`1\times 1` and :math:`2\times 2` blocks; the solution :math:`X` is computed by solving :math:`PUDY = B` and then :math:`U^\mathrm{T}P^\mathrm{T}X = Y`. If :math:`\mathrm{uplo} = \texttt{'L'}`, :math:`A = PLDL^\mathrm{T}P^\mathrm{T}`, where :math:`L` is a lower triangular matrix; the solution :math:`X` is computed by solving :math:`PLDY = B` and then :math:`L^\mathrm{T}P^\mathrm{T}X = Y`. .. _f07pe-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def dspcon(uplo, n, ap, ipiv, anorm): r""" ``dspcon`` estimates the condition number of a real symmetric indefinite matrix :math:`A`, where :math:`A` has been factorized by :meth:`dsptrf`, using packed storage. .. _f07pg-py2-py-doc: For full information please refer to the NAG Library document for f07pg https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07pgf.html .. _f07pg-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies how :math:`A` has been factorized. :math:`\mathrm{uplo} = \texttt{'U'}` :math:`A = PUDU^\mathrm{T}P^\mathrm{T}`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` :math:`A = PLDL^\mathrm{T}P^\mathrm{T}`, where :math:`L` is lower triangular. **n** : int :math:`n`, the order of the matrix :math:`A`. **ap** : float, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` The factorization of :math:`A` stored in packed form, as returned by :meth:`dsptrf`. **ipiv** : int, array-like, shape :math:`\left(\mathrm{n}\right)` Details of the interchanges and the block structure of :math:`D`, as returned by :meth:`dsptrf`. **anorm** : float The :math:`1`-norm of the **original** matrix :math:`A`, which may be computed by calling :meth:`blas.dlansp <naginterfaces.library.blas.dlansp>` with its argument :math:`{\textit{norm}} = \texttt{'1'}`. :math:`\mathrm{anorm}` must be computed either **before** calling :meth:`dsptrf` or else from a **copy** of the original matrix :math:`A`. **Returns** **rcond** : float An estimate of the reciprocal of the condition number of :math:`A`. :math:`\mathrm{rcond}` is set to zero if exact singularity is detected or the estimate underflows. If :math:`\mathrm{rcond}` is less than machine precision, :math:`A` is singular to working precision. .. _f07pg-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-5`) On entry, error in parameter :math:`\mathrm{anorm}`. Constraint: :math:`\mathrm{anorm}\geq 0.0`. .. _f07pg-py2-py-notes: **Notes** ``dspcon`` estimates the condition number (in the :math:`1`-norm) of a real symmetric indefinite matrix :math:`A`: .. math:: \kappa_1\left(A\right) = \left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\text{.} Since :math:`A` is symmetric, :math:`\kappa_1\left(A\right) = \kappa_{\infty }\left(A\right) = \left\lVert A\right\rVert_\infty\left\lVert A^{-1}\right\rVert_\infty`. Because :math:`\kappa_1\left(A\right)` is infinite if :math:`A` is singular, the function actually returns an estimate of the **reciprocal** of :math:`\kappa_1\left(A\right)`. The function should be preceded by a call to :meth:`blas.dlansp <naginterfaces.library.blas.dlansp>` to compute :math:`\left\lVert A\right\rVert_1` and a call to :meth:`dsptrf` to compute the Bunch--Kaufman factorization of :math:`A`. The function then uses Higham's implementation of Hager's method (see Higham (1988)) to estimate :math:`\left\lVert A^{-1}\right\rVert_1`. .. _f07pg-py2-py-references: **References** Higham, N J, 1988, `FORTRAN codes for estimating the one-norm of a real or complex matrix, with applications to condition estimation`, ACM Trans. Math. Software (14), 381--396 """ raise NotImplementedError
[docs]def dsprfs(uplo, n, ap, afp, ipiv, b, x): r""" ``dsprfs`` returns error bounds for the solution of a real symmetric indefinite system of linear equations with multiple right-hand sides, :math:`AX = B`, using packed storage. It improves the solution by iterative refinement, in order to reduce the backward error as much as possible. .. _f07ph-py2-py-doc: For full information please refer to the NAG Library document for f07ph https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07phf.html .. _f07ph-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies whether the upper or lower triangular part of :math:`A` is stored and how :math:`A` is to be factorized. :math:`\mathrm{uplo} = \texttt{'U'}` The upper triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`PUDU^\mathrm{T}P^\mathrm{T}`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` The lower triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`PLDL^\mathrm{T}P^\mathrm{T}`, where :math:`L` is lower triangular. **n** : int :math:`n`, the order of the matrix :math:`A`. **ap** : float, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` The :math:`n\times n` original symmetric matrix :math:`A` as supplied to :meth:`dsptrf`. **afp** : float, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` The factorization of :math:`A` stored in packed form, as returned by :meth:`dsptrf`. **ipiv** : int, array-like, shape :math:`\left(\mathrm{n}\right)` Details of the interchanges and the block structure of :math:`D`, as returned by :meth:`dsptrf`. **b** : float, array-like, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **x** : float, array-like, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`, as returned by :meth:`dsptrs`. **Returns** **x** : float, ndarray, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The improved solution matrix :math:`X`. **ferr** : float, ndarray, shape :math:`\left(\textit{nrhs}\right)` :math:`\mathrm{ferr}[\textit{j}-1]` contains an estimated error bound for the :math:`\textit{j}`\ th solution vector, that is, the :math:`\textit{j}`\ th column of :math:`X`, for :math:`\textit{j} = 1,2,\ldots,r`. **berr** : float, ndarray, shape :math:`\left(\textit{nrhs}\right)` :math:`\mathrm{berr}[\textit{j}-1]` contains the component-wise backward error bound :math:`\beta` for the :math:`\textit{j}`\ th solution vector, that is, the :math:`\textit{j}`\ th column of :math:`X`, for :math:`\textit{j} = 1,2,\ldots,r`. .. _f07ph-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. .. _f07ph-py2-py-notes: **Notes** ``dsprfs`` returns the backward errors and estimated bounds on the forward errors for the solution of a real symmetric indefinite system of linear equations with multiple right-hand sides :math:`AX = B`, using packed storage. The function handles each right-hand side vector (stored as a column of the matrix :math:`B`) independently, so we describe the function of ``dsprfs`` in terms of a single right-hand side :math:`b` and solution :math:`x`. Given a computed solution :math:`x`, the function computes the `component-wise backward error` :math:`\beta`. This is the size of the smallest relative perturbation in each element of :math:`A` and :math:`b` such that :math:`x` is the exact solution of a perturbed system .. math:: \begin{array}{c}\left(A+\delta A\right)x = b+\delta b\\\left\lvert \delta a_{{ij}}\right\rvert \leq \beta \left\lvert a_{{ij}}\right\rvert \quad \text{ and }\quad \left\lvert \delta b_i\right\rvert \leq \beta \left\lvert b_i\right\rvert \text{.} \end{array} Then the function estimates a bound for the `component-wise forward error` in the computed solution, defined by: .. math:: \mathrm{max}_i\left\lvert x_i-\hat{x}_i\right\rvert /\mathrm{max}_i\left\lvert x_i\right\rvert where :math:`\hat{x}` is the true solution. For details of the method, see `the F07 Introduction <https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07intro.html>`__. .. _f07ph-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def dsptri(uplo, n, ap, ipiv): r""" ``dsptri`` computes the inverse of a real symmetric indefinite matrix :math:`A`, where :math:`A` has been factorized by :meth:`dsptrf`, using packed storage. .. _f07pj-py2-py-doc: For full information please refer to the NAG Library document for f07pj https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07pjf.html .. _f07pj-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies how :math:`A` has been factorized. :math:`\mathrm{uplo} = \texttt{'U'}` :math:`A = PUDU^\mathrm{T}P^\mathrm{T}`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` :math:`A = PLDL^\mathrm{T}P^\mathrm{T}`, where :math:`L` is lower triangular. **n** : int :math:`n`, the order of the matrix :math:`A`. **ap** : float, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` The factorization of :math:`A` stored in packed form, as returned by :meth:`dsptrf`. **ipiv** : int, array-like, shape :math:`\left(\mathrm{n}\right)` Details of the interchanges and the block structure of :math:`D`, as returned by :meth:`dsptrf`. **Returns** **ap** : float, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` The factorization is overwritten by the :math:`n\times n` matrix :math:`A^{-1}`. .. _f07pj-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. :math:`D` is singular and the inverse of :math:`A` cannot be computed. .. _f07pj-py2-py-notes: **Notes** ``dsptri`` is used to compute the inverse of a real symmetric indefinite matrix :math:`A`, the function must be preceded by a call to :meth:`dsptrf`, which computes the Bunch--Kaufman factorization of :math:`A`, using packed storage. If :math:`\mathrm{uplo} = \texttt{'U'}`, :math:`A = PUDU^\mathrm{T}P^\mathrm{T}` and :math:`A^{-1}` is computed by solving :math:`U^\mathrm{T}P^\mathrm{T}XPU = D^{-1}`. If :math:`\mathrm{uplo} = \texttt{'L'}`, :math:`A = PLDL^\mathrm{T}P^\mathrm{T}` and :math:`A^{-1}` is computed by solving :math:`L^\mathrm{T}P^\mathrm{T}XPL = D^{-1}`. .. _f07pj-py2-py-references: **References** Du Croz, J J and Higham, N J, 1992, `Stability of methods for matrix inversion`, IMA J. Numer. Anal. (12), 1--19 """ raise NotImplementedError
[docs]def zhpsv(uplo, ap, b): r""" ``zhpsv`` computes the solution to a complex system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` Hermitian matrix stored in packed format and :math:`X` and :math:`B` are :math:`n\times r` matrices. .. _f07pn-py2-py-doc: For full information please refer to the NAG Library document for f07pn https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07pnf.html .. _f07pn-py2-py-parameters: **Parameters** **uplo** : str, length 1 If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored. If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored. **ap** : complex, array-like, shape :math:`\left(n\times \left(n+1\right)/2\right)` The :math:`n\times n` Hermitian matrix :math:`A`, packed by columns. **b** : complex, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **ap** : complex, ndarray, shape :math:`\left(n\times \left(n+1\right)/2\right)` The block diagonal matrix :math:`D` and the multipliers used to obtain the factor :math:`U` or :math:`L` from the factorization :math:`A = UDU^\mathrm{H}` or :math:`A = LDL^\mathrm{H}` as computed by :meth:`zhptrf`, stored as a packed triangular matrix in the same storage format as :math:`A`. **ipiv** : int, ndarray, shape :math:`\left(n\right)` Details of the interchanges and the block structure of :math:`D`. More precisely, if :math:`\mathrm{ipiv}[i-1] = k > 0`, :math:`d_{{ii}}` is a :math:`1\times 1` pivot block and the :math:`i`\ th row and column of :math:`A` were interchanged with the :math:`k`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'U'}` and :math:`\mathrm{ipiv}[i-2] = \mathrm{ipiv}[i-1] = -l < 0`, :math:`\begin{pmatrix}d_{{i-1,i-1}}&\bar{d}_{{i,i-1}}\\\bar{d}_{{i,i-1}}&d_{{ii}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i-1\right)`\ th row and column of :math:`A` were interchanged with the :math:`l`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'L'}` and :math:`\mathrm{ipiv}[i-1] = \mathrm{ipiv}[i] = -m < 0`, :math:`\begin{pmatrix}d_{{ii}}&d_{{i+1,i}}\\d_{{i+1,i}}&d_{{i+1,i+1}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i+1\right)`\ th row and column of :math:`A` were interchanged with the :math:`m`\ th row and column. **b** : complex, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`. .. _f07pn-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the block diagonal matrix :math:`D` is exactly singular, so the solution could not be computed. .. _f07pn-py2-py-notes: **Notes** ``zhpsv`` uses the diagonal pivoting method to factor :math:`A` as :math:`A = UDU^\mathrm{H}` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LDL^\mathrm{H}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` (or :math:`L`) is a product of permutation and unit upper (lower) triangular matrices, :math:`D` is Hermitian and block diagonal with :math:`1\times 1` and :math:`2\times 2` diagonal blocks. The factored form of :math:`A` is then used to solve the system of equations :math:`AX = B`. .. _f07pn-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def zhpsvx(fact, uplo, nrhs, ap, afp, ipiv, b): r""" ``zhpsvx`` uses the diagonal pivoting factorization .. math:: A = UDU^\mathrm{H}\quad \text{ or }\quad A = LDL^\mathrm{H} to compute the solution to a complex system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` Hermitian matrix stored in packed format and :math:`X` and :math:`B` are :math:`n\times r` matrices. Error bounds on the solution and a condition estimate are also provided. .. _f07pp-py2-py-doc: For full information please refer to the NAG Library document for f07pp https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07ppf.html .. _f07pp-py2-py-parameters: **Parameters** **fact** : str, length 1 Specifies whether or not the factorized form of the matrix :math:`A` has been supplied. :math:`\mathrm{fact} = \texttt{'F'}` :math:`\mathrm{afp}` and :math:`\mathrm{ipiv}` contain the factorized form of the matrix :math:`A`. :math:`\mathrm{afp}` and :math:`\mathrm{ipiv}` will not be modified. :math:`\mathrm{fact} = \texttt{'N'}` The matrix :math:`A` will be copied to :math:`\mathrm{afp}` and factorized. **uplo** : str, length 1 If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored. If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored. **nrhs** : int :math:`r`, the number of right-hand sides, i.e., the number of columns of the matrix :math:`B`. **ap** : complex, array-like, shape :math:`\left(n\times \left(n+1\right)/2\right)` The :math:`n\times n` Hermitian matrix :math:`A`, packed by columns. **afp** : complex, array-like, shape :math:`\left(n\times \left(n+1\right)/2\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{afp}` contains the block diagonal matrix :math:`D` and the multipliers used to obtain the factor :math:`U` or :math:`L` from the factorization :math:`A = UDU^\mathrm{H}` or :math:`A = LDL^\mathrm{H}` as computed by :meth:`zhptrf`, stored as a packed triangular matrix in the same storage format as :math:`A`. **ipiv** : int, array-like, shape :math:`\left(n\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{ipiv}` contains details of the interchanges and the block structure of :math:`D`, as determined by :meth:`zhptrf`. if :math:`\mathrm{ipiv}[i-1] = k > 0`, :math:`d_{{ii}}` is a :math:`1\times 1` pivot block and the :math:`i`\ th row and column of :math:`A` were interchanged with the :math:`k`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'U'}` and :math:`\mathrm{ipiv}[i-2] = \mathrm{ipiv}[i-1] = -l < 0`, :math:`\begin{pmatrix}d_{{i-1,i-1}}&\bar{d}_{{i,i-1}}\\\bar{d}_{{i,i-1}}&d_{{ii}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i-1\right)`\ th row and column of :math:`A` were interchanged with the :math:`l`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'L'}` and :math:`\mathrm{ipiv}[i-1] = \mathrm{ipiv}[i] = -m < 0`, :math:`\begin{pmatrix}d_{{ii}}&d_{{i+1,i}}\\d_{{i+1,i}}&d_{{i+1,i+1}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i+1\right)`\ th row and column of :math:`A` were interchanged with the :math:`m`\ th row and column. **b** : complex, array-like, shape :math:`\left(n, \mathrm{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **afp** : complex, ndarray, shape :math:`\left(n\times \left(n+1\right)/2\right)` If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{afp}` contains the block diagonal matrix :math:`D` and the multipliers used to obtain the factor :math:`U` or :math:`L` from the factorization :math:`A = UDU^\mathrm{H}` or :math:`A = LDL^\mathrm{H}` as computed by :meth:`zhptrf`, stored as a packed triangular matrix in the same storage format as :math:`A`. **ipiv** : int, ndarray, shape :math:`\left(n\right)` If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{ipiv}` contains details of the interchanges and the block structure of :math:`D`, as determined by :meth:`zhptrf`, as described above. **x** : complex, ndarray, shape :math:`\left(n, \mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, the :math:`n\times r` solution matrix :math:`X`. **rcond** : float The estimate of the reciprocal condition number of the matrix :math:`A`. If :math:`\mathrm{rcond} = 0.0`, the matrix may be exactly singular. This condition is indicated by :math:`\mathrm{errno}` in 1 ... :math:`\mathrm{n}`. Otherwise, if :math:`\mathrm{rcond}` is less than the machine precision, the matrix is singular to working precision. This condition is indicated by :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1. **ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the forward error bound for each computed solution vector, such that :math:`\left\lVert \hat{x}_j-x_j\right\rVert_\infty/\left\lVert x_j\right\rVert_\infty\leq \mathrm{ferr}[j-1]` where :math:`\hat{x}_j` is the :math:`j`\ th column of the computed solution returned in the array :math:`\mathrm{x}` and :math:`x_j` is the corresponding column of the exact solution :math:`X`. The estimate is as reliable as the estimate for :math:`\mathrm{rcond}`, and is almost always a slight overestimate of the true error. **berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the component-wise relative backward error of each computed solution vector :math:`\hat{x}_j` (i.e., the smallest relative change in any element of :math:`A` or :math:`B` that makes :math:`\hat{x}_j` an exact solution). .. _f07pp-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{fact}`. Constraint: :math:`\mathrm{fact} = \texttt{'F'}` or :math:`\texttt{'N'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\mathrm{nrhs}`. Constraint: :math:`\mathrm{nrhs}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq n\right)`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`D` is exactly singular, so the solution and error bounds could not be computed. :math:`\mathrm{rcond} = 0.0` is returned. (`errno` :math:`n+1`) :math:`D` is nonsingular, but :math:`\mathrm{rcond}` is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of :math:`\mathrm{rcond}` would suggest. .. _f07pp-py2-py-notes: **Notes** ``zhpsvx`` performs the following steps: (1) If :math:`\mathrm{fact} = \texttt{'N'}`, the diagonal pivoting method is used to factor :math:`A` as :math:`A = UDU^\mathrm{H}` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LDL^\mathrm{H}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` (or :math:`L`) is a product of permutation and unit upper (lower) triangular matrices and :math:`D` is Hermitian and block diagonal with :math:`1\times 1` and :math:`2\times 2` diagonal blocks. (#) If some :math:`d_{{ii}} = 0`, so that :math:`D` is exactly singular, then the function returns with :math:`\textit{errno} = i`. Otherwise, the factored form of :math:`A` is used to estimate the condition number of the matrix :math:`A`. If the reciprocal of the condition number is less than machine precision, :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1 is returned as a warning, but the function still goes on to solve for :math:`X` and compute error bounds as described below. (#) The system of equations is solved for :math:`X` using the factored form of :math:`A`. (#) Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for it. .. _f07pp-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def zhptrf(uplo, n, ap): r""" ``zhptrf`` computes the Bunch--Kaufman factorization of a complex Hermitian indefinite matrix, using packed storage. .. _f07pr-py2-py-doc: For full information please refer to the NAG Library document for f07pr https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07prf.html .. _f07pr-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies whether the upper or lower triangular part of :math:`A` is stored and how :math:`A` is to be factorized. :math:`\mathrm{uplo} = \texttt{'U'}` The upper triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`PUDU^\mathrm{H}P^\mathrm{T}`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` The lower triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`PLDL^\mathrm{H}P^\mathrm{T}`, where :math:`L` is lower triangular. **n** : int :math:`n`, the order of the matrix :math:`A`. **ap** : complex, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` The :math:`n\times n` Hermitian matrix :math:`A`, packed by columns. **Returns** **ap** : complex, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` :math:`A` is overwritten by details of the block diagonal matrix :math:`D` and the multipliers used to obtain the factor :math:`U` or :math:`L` as specified by :math:`\mathrm{uplo}`. **ipiv** : int, ndarray, shape :math:`\left(\mathrm{n}\right)` Details of the interchanges and the block structure of :math:`D`. More precisely, if :math:`\mathrm{ipiv}[i-1] = k > 0`, :math:`d_{{ii}}` is a :math:`1\times 1` pivot block and the :math:`i`\ th row and column of :math:`A` were interchanged with the :math:`k`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'U'}` and :math:`\mathrm{ipiv}[i-2] = \mathrm{ipiv}[i-1] = -l < 0`, :math:`\begin{pmatrix}d_{{i-1,i-1}}&\bar{d}_{{i,i-1}}\\\bar{d}_{{i,i-1}}&d_{{ii}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i-1\right)`\ th row and column of :math:`A` were interchanged with the :math:`l`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'L'}` and :math:`\mathrm{ipiv}[i-1] = \mathrm{ipiv}[i] = -m < 0`, :math:`\begin{pmatrix}d_{{ii}}&d_{{i+1,i}}\\d_{{i+1,i}}&d_{{i+1,i+1}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i+1\right)`\ th row and column of :math:`A` were interchanged with the :math:`m`\ th row and column. .. _f07pr-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the block diagonal matrix :math:`D` is exactly singular, and division by zero will occur if it is used to solve a system of equations. .. _f07pr-py2-py-notes: **Notes** ``zhptrf`` factorizes a complex Hermitian matrix :math:`A`, using the Bunch--Kaufman diagonal pivoting method and packed storage. :math:`A` is factorized as either :math:`A = PUDU^\mathrm{H}P^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = PLDL^\mathrm{H}P^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`P` is a permutation matrix, :math:`U` (or :math:`L`) is a unit upper (or lower) triangular matrix and :math:`D` is an Hermitian block diagonal matrix with :math:`1\times 1` and :math:`2\times 2` diagonal blocks; :math:`U` (or :math:`L`) has :math:`2\times 2` unit diagonal blocks corresponding to the :math:`2\times 2` blocks of :math:`D`. Row and column interchanges are performed to ensure numerical stability while keeping the matrix Hermitian. This method is suitable for Hermitian matrices which are not known to be positive definite. If :math:`A` is in fact positive definite, no interchanges are performed and no :math:`2\times 2` blocks occur in :math:`D`. .. _f07pr-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def zhptrs(uplo, n, ap, ipiv, b): r""" ``zhptrs`` solves a complex Hermitian indefinite system of linear equations with multiple right-hand sides, .. math:: AX = B\text{,} where :math:`A` has been factorized by :meth:`zhptrf`, using packed storage. .. _f07ps-py2-py-doc: For full information please refer to the NAG Library document for f07ps https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07psf.html .. _f07ps-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies how :math:`A` has been factorized. :math:`\mathrm{uplo} = \texttt{'U'}` :math:`A = PUDU^\mathrm{H}P^\mathrm{T}`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` :math:`A = PLDL^\mathrm{H}P^\mathrm{T}`, where :math:`L` is lower triangular. **n** : int :math:`n`, the order of the matrix :math:`A`. **ap** : complex, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` The factorization of :math:`A` stored in packed form, as returned by :meth:`zhptrf`. **ipiv** : int, array-like, shape :math:`\left(\mathrm{n}\right)` Details of the interchanges and the block structure of :math:`D`, as returned by :meth:`zhptrf`. **b** : complex, array-like, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **b** : complex, ndarray, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`. .. _f07ps-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. .. _f07ps-py2-py-notes: **Notes** ``zhptrs`` is used to solve a complex Hermitian indefinite system of linear equations :math:`AX = B`, the function must be preceded by a call to :meth:`zhptrf` which computes the Bunch--Kaufman factorization of :math:`A`, using packed storage. If :math:`\mathrm{uplo} = \texttt{'U'}`, :math:`A = PUDU^\mathrm{H}P^\mathrm{T}`, where :math:`P` is a permutation matrix, :math:`U` is an upper triangular matrix and :math:`D` is an Hermitian block diagonal matrix with :math:`1\times 1` and :math:`2\times 2` blocks; the solution :math:`X` is computed by solving :math:`PUDY = B` and then :math:`U^\mathrm{H}P^\mathrm{T}X = Y`. If :math:`\mathrm{uplo} = \texttt{'L'}`, :math:`A = PLDL^\mathrm{H}P^\mathrm{T}`, where :math:`L` is a lower triangular matrix; the solution :math:`X` is computed by solving :math:`PLDY = B` and then :math:`L^\mathrm{H}P^\mathrm{T}X = Y`. .. _f07ps-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def zhpcon(uplo, ap, ipiv, anorm): r""" ``zhpcon`` estimates the condition number of a complex Hermitian indefinite matrix :math:`A`, where :math:`A` has been factorized by :meth:`zhptrf`, using packed storage. .. _f07pu-py2-py-doc: For full information please refer to the NAG Library document for f07pu https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07puf.html .. _f07pu-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies how :math:`A` has been factorized. :math:`\mathrm{uplo} = \texttt{'U'}` :math:`A = PUDU^\mathrm{H}P^\mathrm{T}`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` :math:`A = PLDL^\mathrm{H}P^\mathrm{T}`, where :math:`L` is lower triangular. **ap** : complex, array-like, shape :math:`\left(n\times \left(n+1\right)/2\right)` The factorization of :math:`A` stored in packed form, as returned by :meth:`zhptrf`. **ipiv** : int, array-like, shape :math:`\left(n\right)` Details of the interchanges and the block structure of :math:`D`, as returned by :meth:`zhptrf`. **anorm** : float The :math:`1`-norm of the **original** matrix :math:`A`, which may be computed by calling :meth:`blas.zlanhp <naginterfaces.library.blas.zlanhp>` with its argument :math:`{\textit{norm}} = \texttt{'1'}`. :math:`\mathrm{anorm}` must be computed either **before** calling :meth:`zhptrf` or else from a **copy** of the original matrix :math:`A`. **Returns** **rcond** : float An estimate of the reciprocal of the condition number of :math:`A`. :math:`\mathrm{rcond}` is set to zero if exact singularity is detected or the estimate underflows. If :math:`\mathrm{rcond}` is less than machine precision, :math:`A` is singular to working precision. .. _f07pu-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-5`) On entry, error in parameter :math:`\mathrm{anorm}`. Constraint: :math:`\mathrm{anorm}\geq 0.0`. .. _f07pu-py2-py-notes: **Notes** ``zhpcon`` estimates the condition number (in the :math:`1`-norm) of a complex Hermitian indefinite matrix :math:`A`: .. math:: \kappa_1\left(A\right) = \left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\text{.} Since :math:`A` is Hermitian, :math:`\kappa_1\left(A\right) = \kappa_{\infty }\left(A\right) = \left\lVert A\right\rVert_\infty\left\lVert A^{-1}\right\rVert_\infty`. Because :math:`\kappa_1\left(A\right)` is infinite if :math:`A` is singular, the function actually returns an estimate of the **reciprocal** of :math:`\kappa_1\left(A\right)`. The function should be preceded by a call to :meth:`blas.zlanhp <naginterfaces.library.blas.zlanhp>` to compute :math:`\left\lVert A\right\rVert_1` and a call to :meth:`zhptrf` to compute the Bunch--Kaufman factorization of :math:`A`. The function then uses Higham's implementation of Hager's method (see Higham (1988)) to estimate :math:`\left\lVert A^{-1}\right\rVert_1`. .. _f07pu-py2-py-references: **References** Higham, N J, 1988, `FORTRAN codes for estimating the one-norm of a real or complex matrix, with applications to condition estimation`, ACM Trans. Math. Software (14), 381--396 """ raise NotImplementedError
[docs]def zhprfs(uplo, n, ap, afp, ipiv, b, x): r""" ``zhprfs`` returns error bounds for the solution of a complex Hermitian indefinite system of linear equations with multiple right-hand sides, :math:`AX = B`, using packed storage. It improves the solution by iterative refinement, in order to reduce the backward error as much as possible. .. _f07pv-py2-py-doc: For full information please refer to the NAG Library document for f07pv https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07pvf.html .. _f07pv-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies whether the upper or lower triangular part of :math:`A` is stored and how :math:`A` is to be factorized. :math:`\mathrm{uplo} = \texttt{'U'}` The upper triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`PUDU^\mathrm{H}P^\mathrm{T}`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` The lower triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`PLDL^\mathrm{H}P^\mathrm{T}`, where :math:`L` is lower triangular. **n** : int :math:`n`, the order of the matrix :math:`A`. **ap** : complex, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` The :math:`n\times n` original Hermitian matrix :math:`A` as supplied to :meth:`zhptrf`. **afp** : complex, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` The factorization of :math:`A` stored in packed form, as returned by :meth:`zhptrf`. **ipiv** : int, array-like, shape :math:`\left(\mathrm{n}\right)` Details of the interchanges and the block structure of :math:`D`, as returned by :meth:`zhptrf`. **b** : complex, array-like, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **x** : complex, array-like, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`, as returned by :meth:`zhptrs`. **Returns** **x** : complex, ndarray, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The improved solution matrix :math:`X`. **ferr** : float, ndarray, shape :math:`\left(\textit{nrhs}\right)` :math:`\mathrm{ferr}[\textit{j}-1]` contains an estimated error bound for the :math:`\textit{j}`\ th solution vector, that is, the :math:`\textit{j}`\ th column of :math:`X`, for :math:`\textit{j} = 1,2,\ldots,r`. **berr** : float, ndarray, shape :math:`\left(\textit{nrhs}\right)` :math:`\mathrm{berr}[\textit{j}-1]` contains the component-wise backward error bound :math:`\beta` for the :math:`\textit{j}`\ th solution vector, that is, the :math:`\textit{j}`\ th column of :math:`X`, for :math:`\textit{j} = 1,2,\ldots,r`. .. _f07pv-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. .. _f07pv-py2-py-notes: **Notes** ``zhprfs`` returns the backward errors and estimated bounds on the forward errors for the solution of a complex Hermitian indefinite system of linear equations with multiple right-hand sides :math:`AX = B`, using packed storage. The function handles each right-hand side vector (stored as a column of the matrix :math:`B`) independently, so we describe the function of ``zhprfs`` in terms of a single right-hand side :math:`b` and solution :math:`x`. Given a computed solution :math:`x`, the function computes the `component-wise backward error` :math:`\beta`. This is the size of the smallest relative perturbation in each element of :math:`A` and :math:`b` such that :math:`x` is the exact solution of a perturbed system .. math:: \begin{array}{c}\left(A+\delta A\right)x = b+\delta b\\\left\lvert \delta a_{{ij}}\right\rvert \leq \beta \left\lvert a_{{ij}}\right\rvert \quad \text{ and }\quad \left\lvert \delta b_i\right\rvert \leq \beta \left\lvert b_i\right\rvert \text{.} \end{array} Then the function estimates a bound for the `component-wise forward error` in the computed solution, defined by: .. math:: \mathrm{max}_i\left\lvert x_i-\hat{x}_i\right\rvert /\mathrm{max}_i\left\lvert x_i\right\rvert where :math:`\hat{x}` is the true solution. For details of the method, see `the F07 Introduction <https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07intro.html>`__. .. _f07pv-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def zhptri(uplo, n, ap, ipiv): r""" ``zhptri`` computes the inverse of a complex Hermitian indefinite matrix :math:`A`, where :math:`A` has been factorized by :meth:`zhptrf`, using packed storage. .. _f07pw-py2-py-doc: For full information please refer to the NAG Library document for f07pw https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07pwf.html .. _f07pw-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies how :math:`A` has been factorized. :math:`\mathrm{uplo} = \texttt{'U'}` :math:`A = PUDU^\mathrm{H}P^\mathrm{T}`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` :math:`A = PLDL^\mathrm{H}P^\mathrm{T}`, where :math:`L` is lower triangular. **n** : int :math:`n`, the order of the matrix :math:`A`. **ap** : complex, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` The factorization of :math:`A` stored in packed form, as returned by :meth:`zhptrf`. **ipiv** : int, array-like, shape :math:`\left(\mathrm{n}\right)` Details of the interchanges and the block structure of :math:`D`, as returned by :meth:`zhptrf`. **Returns** **ap** : complex, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` The factorization is overwritten by the :math:`n\times n` matrix :math:`A^{-1}`. .. _f07pw-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. :math:`D` is singular and the inverse of :math:`A` cannot be computed. .. _f07pw-py2-py-notes: **Notes** ``zhptri`` is used to compute the inverse of a complex Hermitian indefinite matrix :math:`A`, the function must be preceded by a call to :meth:`zhptrf`, which computes the Bunch--Kaufman factorization of :math:`A`, using packed storage. If :math:`\mathrm{uplo} = \texttt{'U'}`, :math:`A = PUDU^\mathrm{H}P^\mathrm{T}` and :math:`A^{-1}` is computed by solving :math:`U^\mathrm{H}P^\mathrm{T}XPU = D^{-1}` for :math:`X`. If :math:`\mathrm{uplo} = \texttt{'L'}`, :math:`A = PLDL^\mathrm{H}P^\mathrm{T}` and :math:`A^{-1}` is computed by solving :math:`L^\mathrm{H}P^\mathrm{T}XPL = D^{-1}` for :math:`X`. .. _f07pw-py2-py-references: **References** Du Croz, J J and Higham, N J, 1992, `Stability of methods for matrix inversion`, IMA J. Numer. Anal. (12), 1--19 """ raise NotImplementedError
[docs]def zspsv(uplo, ap, b): r""" ``zspsv`` computes the solution to a complex system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` symmetric matrix stored in packed format and :math:`X` and :math:`B` are :math:`n\times r` matrices. .. _f07qn-py2-py-doc: For full information please refer to the NAG Library document for f07qn https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07qnf.html .. _f07qn-py2-py-parameters: **Parameters** **uplo** : str, length 1 If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored. If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored. **ap** : complex, array-like, shape :math:`\left(n\times \left(n+1\right)/2\right)` The :math:`n\times n` symmetric matrix :math:`A`, packed by columns. **b** : complex, array-like, shape :math:`\left(n, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **ap** : complex, ndarray, shape :math:`\left(n\times \left(n+1\right)/2\right)` The block diagonal matrix :math:`D` and the multipliers used to obtain the factor :math:`U` or :math:`L` from the factorization :math:`A = UDU^\mathrm{H}` or :math:`A = LDL^\mathrm{H}` as computed by :meth:`zsptrf`, stored as a packed triangular matrix in the same storage format as :math:`A`. **ipiv** : int, ndarray, shape :math:`\left(n\right)` Details of the interchanges and the block structure of :math:`D`. More precisely, if :math:`\mathrm{ipiv}[i-1] = k > 0`, :math:`d_{{ii}}` is a :math:`1\times 1` pivot block and the :math:`i`\ th row and column of :math:`A` were interchanged with the :math:`k`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'U'}` and :math:`\mathrm{ipiv}[i-2] = \mathrm{ipiv}[i-1] = -l < 0`, :math:`\begin{pmatrix}d_{{i-1,i-1}}&\bar{d}_{{i,i-1}}\\\bar{d}_{{i,i-1}}&d_{{ii}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i-1\right)`\ th row and column of :math:`A` were interchanged with the :math:`l`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'L'}` and :math:`\mathrm{ipiv}[i-1] = \mathrm{ipiv}[i] = -m < 0`, :math:`\begin{pmatrix}d_{{ii}}&d_{{i+1,i}}\\d_{{i+1,i}}&d_{{i+1,i+1}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i+1\right)`\ th row and column of :math:`A` were interchanged with the :math:`m`\ th row and column. **b** : complex, ndarray, shape :math:`\left(n, \textit{nrhs}\right)` If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`. .. _f07qn-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the block diagonal matrix :math:`D` is exactly singular, so the solution could not be computed. .. _f07qn-py2-py-notes: **Notes** ``zspsv`` uses the diagonal pivoting method to factor :math:`A` as :math:`A = UDU^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LDL^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` (or :math:`L`) is a product of permutation and unit upper (lower) triangular matrices, :math:`D` is symmetric and block diagonal with :math:`1\times 1` and :math:`2\times 2` diagonal blocks. The factored form of :math:`A` is then used to solve the system of equations :math:`AX = B`. .. _f07qn-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def zspsvx(fact, uplo, nrhs, ap, afp, ipiv, b): r""" ``zspsvx`` uses the diagonal pivoting factorization .. math:: A = UDU^\mathrm{T}\quad \text{ or }\quad A = LDL^\mathrm{T} to compute the solution to a complex system of linear equations .. math:: AX = B\text{,} where :math:`A` is an :math:`n\times n` symmetric matrix stored in packed format and :math:`X` and :math:`B` are :math:`n\times r` matrices. Error bounds on the solution and a condition estimate are also provided. .. _f07qp-py2-py-doc: For full information please refer to the NAG Library document for f07qp https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07qpf.html .. _f07qp-py2-py-parameters: **Parameters** **fact** : str, length 1 Specifies whether or not the factorized form of the matrix :math:`A` has been supplied. :math:`\mathrm{fact} = \texttt{'F'}` :math:`\mathrm{afp}` and :math:`\mathrm{ipiv}` contain the factorized form of the matrix :math:`A`. :math:`\mathrm{afp}` and :math:`\mathrm{ipiv}` will not be modified. :math:`\mathrm{fact} = \texttt{'N'}` The matrix :math:`A` will be copied to :math:`\mathrm{afp}` and factorized. **uplo** : str, length 1 If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored. If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored. **nrhs** : int :math:`r`, the number of right-hand sides, i.e., the number of columns of the matrix :math:`B`. **ap** : complex, array-like, shape :math:`\left(n\times \left(n+1\right)/2\right)` The :math:`n\times n` symmetric matrix :math:`A`, packed by columns. **afp** : complex, array-like, shape :math:`\left(n\times \left(n+1\right)/2\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{afp}` contains the block diagonal matrix :math:`D` and the multipliers used to obtain the factor :math:`U` or :math:`L` from the factorization :math:`A = UDU^\mathrm{H}` or :math:`A = LDL^\mathrm{H}` as computed by :meth:`zsptrf`, stored as a packed triangular matrix in the same storage format as :math:`A`. **ipiv** : int, array-like, shape :math:`\left(n\right)` If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{ipiv}` contains details of the interchanges and the block structure of :math:`D`, as determined by :meth:`zsptrf`. if :math:`\mathrm{ipiv}[i-1] = k > 0`, :math:`d_{{ii}}` is a :math:`1\times 1` pivot block and the :math:`i`\ th row and column of :math:`A` were interchanged with the :math:`k`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'U'}` and :math:`\mathrm{ipiv}[i-2] = \mathrm{ipiv}[i-1] = -l < 0`, :math:`\begin{pmatrix}d_{{i-1,i-1}}&\bar{d}_{{i,i-1}}\\\bar{d}_{{i,i-1}}&d_{{ii}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i-1\right)`\ th row and column of :math:`A` were interchanged with the :math:`l`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'L'}` and :math:`\mathrm{ipiv}[i-1] = \mathrm{ipiv}[i] = -m < 0`, :math:`\begin{pmatrix}d_{{ii}}&d_{{i+1,i}}\\d_{{i+1,i}}&d_{{i+1,i+1}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i+1\right)`\ th row and column of :math:`A` were interchanged with the :math:`m`\ th row and column. **b** : complex, array-like, shape :math:`\left(n, \mathrm{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **afp** : complex, ndarray, shape :math:`\left(n\times \left(n+1\right)/2\right)` If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{afp}` contains the block diagonal matrix :math:`D` and the multipliers used to obtain the factor :math:`U` or :math:`L` from the factorization :math:`A = UDU^\mathrm{H}` or :math:`A = LDL^\mathrm{H}` as computed by :meth:`zsptrf`, stored as a packed triangular matrix in the same storage format as :math:`A`. **ipiv** : int, ndarray, shape :math:`\left(n\right)` If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{ipiv}` contains details of the interchanges and the block structure of :math:`D`, as determined by :meth:`zsptrf`, as described above. **x** : complex, ndarray, shape :math:`\left(n, \mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, the :math:`n\times r` solution matrix :math:`X`. **rcond** : float The estimate of the reciprocal condition number of the matrix :math:`A`. If :math:`\mathrm{rcond} = 0.0`, the matrix may be exactly singular. This condition is indicated by :math:`\mathrm{errno}` in 1 ... :math:`\mathrm{n}`. Otherwise, if :math:`\mathrm{rcond}` is less than the machine precision, the matrix is singular to working precision. This condition is indicated by :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1. **ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the forward error bound for each computed solution vector, such that :math:`\left\lVert \hat{x}_j-x_j\right\rVert_\infty/\left\lVert x_j\right\rVert_\infty\leq \mathrm{ferr}[j-1]` where :math:`\hat{x}_j` is the :math:`j`\ th column of the computed solution returned in the array :math:`\mathrm{x}` and :math:`x_j` is the corresponding column of the exact solution :math:`X`. The estimate is as reliable as the estimate for :math:`\mathrm{rcond}`, and is almost always a slight overestimate of the true error. **berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)` If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the component-wise relative backward error of each computed solution vector :math:`\hat{x}_j` (i.e., the smallest relative change in any element of :math:`A` or :math:`B` that makes :math:`\hat{x}_j` an exact solution). .. _f07qp-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{fact}`. Constraint: :math:`\mathrm{fact} = \texttt{'F'}` or :math:`\texttt{'N'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{n}`. Constraint: :math:`n\geq 0`. (`errno` :math:`-4`) On entry, error in parameter :math:`\mathrm{nrhs}`. Constraint: :math:`\mathrm{nrhs}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq n\right)`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`D` is exactly singular, so the solution and error bounds could not be computed. :math:`\mathrm{rcond} = 0.0` is returned. (`errno` :math:`n+1`) :math:`D` is nonsingular, but :math:`\mathrm{rcond}` is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of :math:`\mathrm{rcond}` would suggest. .. _f07qp-py2-py-notes: **Notes** ``zspsvx`` performs the following steps: (1) If :math:`\mathrm{fact} = \texttt{'N'}`, the diagonal pivoting method is used to factor :math:`A` as :math:`A = UDU^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LDL^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` (or :math:`L`) is a product of permutation and unit upper (lower) triangular matrices and :math:`D` is symmetric and block diagonal with :math:`1\times 1` and :math:`2\times 2` diagonal blocks. (#) If some :math:`d_{{ii}} = 0`, so that :math:`D` is exactly singular, then the function returns with :math:`\textit{errno} = i`. Otherwise, the factored form of :math:`A` is used to estimate the condition number of the matrix :math:`A`. If the reciprocal of the condition number is less than machine precision, :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1 is returned as a warning, but the function still goes on to solve for :math:`X` and compute error bounds as described below. (#) The system of equations is solved for :math:`X` using the factored form of :math:`A`. (#) Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for it. .. _f07qp-py2-py-references: **References** Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia """ raise NotImplementedError
[docs]def zsptrf(uplo, n, ap): r""" ``zsptrf`` computes the Bunch--Kaufman factorization of a complex symmetric matrix, using packed storage. .. _f07qr-py2-py-doc: For full information please refer to the NAG Library document for f07qr https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07qrf.html .. _f07qr-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies whether the upper or lower triangular part of :math:`A` is stored and how :math:`A` is to be factorized. :math:`\mathrm{uplo} = \texttt{'U'}` The upper triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`PUDU^\mathrm{H}P^\mathrm{T}`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` The lower triangular part of :math:`A` is stored and :math:`A` is factorized as :math:`PLDL^\mathrm{H}P^\mathrm{T}`, where :math:`L` is lower triangular. **n** : int :math:`n`, the order of the matrix :math:`A`. **ap** : complex, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` The :math:`n\times n` symmetric matrix :math:`A`, packed by columns. **Returns** **ap** : complex, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` :math:`A` is overwritten by details of the block diagonal matrix :math:`D` and the multipliers used to obtain the factor :math:`U` or :math:`L` as specified by :math:`\mathrm{uplo}`. **ipiv** : int, ndarray, shape :math:`\left(\mathrm{n}\right)` Details of the interchanges and the block structure of :math:`D`. More precisely, if :math:`\mathrm{ipiv}[i-1] = k > 0`, :math:`d_{{ii}}` is a :math:`1\times 1` pivot block and the :math:`i`\ th row and column of :math:`A` were interchanged with the :math:`k`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'U'}` and :math:`\mathrm{ipiv}[i-2] = \mathrm{ipiv}[i-1] = -l < 0`, :math:`\begin{pmatrix}d_{{i-1,i-1}}&\bar{d}_{{i,i-1}}\\\bar{d}_{{i,i-1}}&d_{{ii}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i-1\right)`\ th row and column of :math:`A` were interchanged with the :math:`l`\ th row and column; if :math:`\mathrm{uplo} = \texttt{'L'}` and :math:`\mathrm{ipiv}[i-1] = \mathrm{ipiv}[i] = -m < 0`, :math:`\begin{pmatrix}d_{{ii}}&d_{{i+1,i}}\\d_{{i+1,i}}&d_{{i+1,i+1}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i+1\right)`\ th row and column of :math:`A` were interchanged with the :math:`m`\ th row and column. .. _f07qr-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. **Warns** **NagAlgorithmicWarning** (`errno` :math:`i > 0`) Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the block diagonal matrix :math:`D` is exactly singular, and division by zero will occur if it is used to solve a system of equations. .. _f07qr-py2-py-notes: **Notes** ``zsptrf`` factorizes a complex symmetric matrix :math:`A`, using the Bunch--Kaufman diagonal pivoting method and packed storage. :math:`A` is factorized as either :math:`A = PUDU^\mathrm{T}P^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = PLDL^\mathrm{T}P^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`P` is a permutation matrix, :math:`U` (or :math:`L`) is a unit upper (or lower) triangular matrix and :math:`D` is a symmetric block diagonal matrix with :math:`1\times 1` and :math:`2\times 2` diagonal blocks; :math:`U` (or :math:`L`) has :math:`2\times 2` unit diagonal blocks corresponding to the :math:`2\times 2` blocks of :math:`D`. Row and column interchanges are performed to ensure numerical stability while preserving symmetry. .. _f07qr-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore """ raise NotImplementedError
[docs]def zsptrs(uplo, n, ap, ipiv, b): r""" ``zsptrs`` solves a complex symmetric system of linear equations with multiple right-hand sides, .. math:: AX = B\text{,} where :math:`A` has been factorized by :meth:`zsptrf`, using packed storage. .. _f07qs-py2-py-doc: For full information please refer to the NAG Library document for f07qs https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07qsf.html .. _f07qs-py2-py-parameters: **Parameters** **uplo** : str, length 1 Specifies how :math:`A` has been factorized. :math:`\mathrm{uplo} = \texttt{'U'}` :math:`A = PUDU^\mathrm{H}P^\mathrm{T}`, where :math:`U` is upper triangular. :math:`\mathrm{uplo} = \texttt{'L'}` :math:`A = PLDL^\mathrm{H}P^\mathrm{T}`, where :math:`L` is lower triangular. **n** : int :math:`n`, the order of the matrix :math:`A`. **ap** : complex, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)` The factorization of :math:`A` stored in packed form, as returned by :meth:`zsptrf`. **ipiv** : int, array-like, shape :math:`\left(\mathrm{n}\right)` Details of the interchanges and the block structure of :math:`D`, as returned by :meth:`zsptrf`. **b** : complex, array-like, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The :math:`n\times r` right-hand side matrix :math:`B`. **Returns** **b** : complex, ndarray, shape :math:`\left(\mathrm{n}, \textit{nrhs}\right)` The :math:`n\times r` solution matrix :math:`X`. .. _f07qs-py2-py-errors: **Raises** **NagValueError** (`errno` :math:`-1`) On entry, error in parameter :math:`\mathrm{uplo}`. Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`. (`errno` :math:`-2`) On entry, error in parameter :math:`\mathrm{n}`. Constraint: :math:`\mathrm{n}\geq 0`. (`errno` :math:`-3`) On entry, error in parameter :math:`\textit{nrhs}`. Constraint: :math:`\textit{nrhs}\geq 0`. .. _f07qs-py2-py-notes: **Notes** ``zsptrs`` is used to solve a complex symmetric system of linear equations :math:`AX = B`, the function must be preceded by a call to :meth:`zsptrf` which computes the Bunch--Kaufman factorization of :math:`A`, using packed storage. If :math:`\mathrm{uplo} = \texttt{'U'}`, :math:`A = PUDU^\mathrm{T}P^\mathrm{T}`, where :math:`P` is a permutation matrix, :math:`U` is an upper triangular matrix and :math:`D` is a symmetric block diagonal matrix with :math:`1\times 1` and :math:`2\times 2` blocks; the solution :math:`X` is computed by solving :math:`PUDY = B` and then :math:`U^\mathrm{T}P^\mathrm{T}X = Y`. If :math:`\mathrm{uplo} = \texttt{'L'}`, :math:`A = PLDL^\mathrm{T}P^\mathrm{T}`, where :math:`L` is a lower triangular matrix; the solution :math:`X` is computed by solving :math:`PLDY = B` and then :math:`L^\mathrm{T}P^\mathrm{T}X = Y`. .. _f07qs-py2-py-references: **References** Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore