# 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.

--------
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
"""

[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

--------
: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::

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::

and

.. math::

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.

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

**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.

**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.

**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.

**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::

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::

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::

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::

.. math::

and

.. math::

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::

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::

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::

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::

and

.. math::

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::

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::

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::

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::

.. math::

and

.. math::

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::

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::

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::

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::

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::

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::

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::

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::

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::

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::

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::

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::

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::

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::

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::

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::

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::

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::

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::

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::

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::

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