# -*- coding: utf-8 -*-
r"""
Module Summary
--------------
Interfaces for the NAG Mark 30.1 `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://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f04/f04intro.html>`__.
The decision trees, in `the F04 Introduction <https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f04/f04intro.html#dtree>`__, direct you to the most appropriate functions in submodule :mod:`~naginterfaces.library.linsys` or submodule ``lapacklin`` for solving your particular problem.
In particular, submodule :mod:`~naginterfaces.library.linsys` and submodule ``lapacklin`` contain `Black Box` (or `driver`) functions which enable some standard types of problem to be solved by a call to a single function.
Where possible, functions in submodule :mod:`~naginterfaces.library.linsys` call submodule ``lapacklin`` functions to perform the necessary computational tasks.
There are two types of driver functions in this module: `simple drivers` which just return the solution to the linear equations; and `expert drivers` which also return condition and error estimates and, in many cases, also allow equilibration.
The simple drivers for real matrices have names of the form and for complex matrices have names of the form The expert drivers for real matrices have names of the form and for complex matrices have names of the form
The functions in this module (submodule ``lapacklin``) handle only `dense` and `band` matrices (not matrices with more specialised structures, or general sparse matrices).
The functions in this module have all been derived from the LAPACK project (see Anderson `et al.` (1999)).
They have been designed to be efficient on a wide range of high-performance computers, without compromising efficiency on conventional serial machines.
See Also
--------
``naginterfaces.library.examples.lapacklin`` :
This subpackage contains examples for the ``lapacklin`` module.
See also the :ref:`library_lapacklin_ex` subsection.
Functionality Index
-------------------
**Apply iterative refinement to the solution and compute error estimates**
after factorizing the matrix of coefficients
complex band matrix: :meth:`zgbrfs`
complex Hermitian indefinite matrix: :meth:`zherfs`
complex Hermitian indefinite matrix, packed storage: :meth:`zhprfs`
complex Hermitian positive definite band matrix: :meth:`zpbrfs`
complex Hermitian positive definite matrix: :meth:`zporfs`
complex Hermitian positive definite matrix, packed storage: :meth:`zpprfs`
complex Hermitian positive definite tridiagonal matrix: :meth:`zptrfs`
complex matrix: :meth:`zgerfs`
complex symmetric indefinite matrix: :meth:`zsyrfs`
complex symmetric indefinite matrix, packed storage: :meth:`zsprfs`
complex tridiagonal matrix: :meth:`zgtrfs`
real band matrix: :meth:`dgbrfs`
real matrix: :meth:`dgerfs`
real symmetric indefinite matrix: :meth:`dsyrfs`
real symmetric indefinite matrix, packed storage: :meth:`dsprfs`
real symmetric positive definite band matrix: :meth:`dpbrfs`
real symmetric positive definite matrix: :meth:`dporfs`
real symmetric positive definite matrix, packed storage: :meth:`dpprfs`
real symmetric positive definite tridiagonal matrix: :meth:`dptrfs`
real tridiagonal matrix: :meth:`dgtrfs`
**Compute error estimates**
complex triangular band matrix: :meth:`ztbrfs`
complex triangular matrix: :meth:`ztrrfs`
complex triangular matrix, packed storage: :meth:`ztprfs`
real triangular band matrix: :meth:`dtbrfs`
real triangular matrix: :meth:`dtrrfs`
real triangular matrix, packed storage: :meth:`dtprfs`
**Compute row and column scalings**
complex band matrix: :meth:`zgbequ`
complex Hermitian positive definite band matrix: :meth:`zpbequ`
complex Hermitian positive definite matrix: :meth:`zpoequ`
complex Hermitian positive definite matrix, packed storage: :meth:`zppequ`
complex matrix: :meth:`zgeequ`
real band matrix: :meth:`dgbequ`
real matrix: :meth:`dgeequ`
real symmetric positive definite band matrix: :meth:`dpbequ`
real symmetric positive definite matrix: :meth:`dpoequ`
real symmetric positive definite matrix, packed storage: :meth:`dppequ`
**Condition number estimation**
after factorizing the matrix of coefficients
complex band matrix: :meth:`zgbcon`
complex Hermitian indefinite matrix: :meth:`zhecon`
complex Hermitian indefinite matrix, packed storage: :meth:`zhpcon`
complex Hermitian positive definite band matrix: :meth:`zpbcon`
complex Hermitian positive definite matrix: :meth:`zpocon`
complex Hermitian positive definite matrix, packed storage: :meth:`zppcon`
complex Hermitian positive definite tridiagonal matrix: :meth:`zptcon`
complex matrix: :meth:`zgecon`
complex symmetric indefinite matrix: :meth:`zsycon`
complex symmetric indefinite matrix, packed storage: :meth:`zspcon`
complex tridiagonal matrix: :meth:`zgtcon`
real band matrix: :meth:`dgbcon`
real matrix: :meth:`dgecon`
real symmetric indefinite matrix: :meth:`dsycon`
real symmetric indefinite matrix, packed storage: :meth:`dspcon`
real symmetric positive definite band matrix: :meth:`dpbcon`
real symmetric positive definite matrix: :meth:`dpocon`
real symmetric positive definite matrix, packed storage: :meth:`dppcon`
real symmetric positive definite tridiagonal matrix: :meth:`dptcon`
real tridiagonal matrix: :meth:`dgtcon`
complex triangular band matrix: :meth:`ztbcon`
complex triangular matrix: :meth:`ztrcon`
complex triangular matrix, packed storage: :meth:`ztpcon`
real triangular band matrix: :meth:`dtbcon`
real triangular matrix: :meth:`dtrcon`
real triangular matrix, packed storage: :meth:`dtpcon`
:math:`LDL^\mathrm{T}` **factorization**
complex Hermitian positive definite tridiagonal matrix: :meth:`zpttrf`
real symmetric positive definite tridiagonal matrix: :meth:`dpttrf`
:math:`LL^\mathrm{H}` **or** :math:`U^\mathrm{H}U` **factorization**
complex Hermitian positive definite band matrix: :meth:`zpbtrf`
complex Hermitian positive definite matrix: :meth:`zpotrf`
complex Hermitian positive definite matrix, packed storage: :meth:`zpptrf`
complex Hermitian positive definite matrix, RFP storage: :meth:`zpftrf`
complex Hermitian positive semidefinite matrix: :meth:`zpstrf`
:math:`LL^\mathrm{T}` **or** :math:`U^\mathrm{T}U` **factorization**
real symmetric positive definite band matrix: :meth:`dpbtrf`
real symmetric positive definite matrix: :meth:`dpotrf`
real symmetric positive definite matrix, packed storage: :meth:`dpptrf`
real symmetric positive definite matrix, RFP storage: :meth:`dpftrf`
real symmetric positive semidefinite matrix: :meth:`dpstrf`
:math:`LU` **factorization**
complex band matrix: :meth:`zgbtrf`
complex matrix: :meth:`zgetrf`
complex tridiagonal matrix: :meth:`zgttrf`
real band matrix: :meth:`dgbtrf`
real matrix: :meth:`dgetrf`
real tridiagonal matrix: :meth:`dgttrf`
**Matrix inversion**
after factorizing the matrix of coefficients
complex Hermitian indefinite matrix: :meth:`zhetri`
complex Hermitian indefinite matrix, packed storage: :meth:`zhptri`
complex Hermitian positive definite matrix: :meth:`zpotri`
complex Hermitian positive definite matrix, packed storage: :meth:`zpptri`
complex Hermitian positive definite matrix, RFP storage: :meth:`zpftri`
complex matrix: :meth:`zgetri`
complex symmetric indefinite matrix: :meth:`zsytri`
complex symmetric indefinite matrix, packed storage: :meth:`zsptri`
real matrix: :meth:`dgetri`
real symmetric indefinite matrix: :meth:`dsytri`
real symmetric indefinite matrix, packed storage: :meth:`dsptri`
real symmetric positive definite matrix: :meth:`dpotri`
real symmetric positive definite matrix, packed storage: :meth:`dpptri`
real symmetric positive definite matrix, RFP storage: :meth:`dpftri`
complex triangular matrix: :meth:`ztrtri`
complex triangular matrix, packed storage: :meth:`ztptri`
complex triangular matrix, RFP storage
expert driver: :meth:`ztftri`
real triangular matrix: :meth:`dtrtri`
real triangular matrix, packed storage: :meth:`dtptri`
real triangular matrix, RFP storage
expert driver: :meth:`dtftri`
:math:`PLDL^\mathrm{H}P^\mathrm{H}` **or** :math:`PUDU^\mathrm{H}P^\mathrm{H}` **factorization**
complex Hermitian indefinite matrix: :meth:`zhetrf`
complex Hermitian indefinite matrix, packed storage: :meth:`zhptrf`
:math:`PLDL^\mathrm{T}P^\mathrm{T}` **or** :math:`PUDU^\mathrm{T}P^\mathrm{T}` **factorization**
complex symmetric indefinite matrix: :meth:`zsytrf`
complex symmetric indefinite matrix, packed storage: :meth:`zsptrf`
real symmetric indefinite matrix: :meth:`dsytrf`
real symmetric indefinite matrix, packed storage: :meth:`dsptrf`
**Solution of simultaneous linear equations**
after factorizing the matrix of coefficients
complex band matrix: :meth:`zgbtrs`
complex Hermitian indefinite matrix: :meth:`zhetrs`
complex Hermitian indefinite matrix, packed storage: :meth:`zhptrs`
complex Hermitian positive definite band matrix: :meth:`zpbtrs`
complex Hermitian positive definite matrix: :meth:`zpotrs`
complex Hermitian positive definite matrix, packed storage: :meth:`zpptrs`
complex Hermitian positive definite matrix, RFP storage: :meth:`zpftrs`
complex Hermitian positive definite tridiagonal matrix: :meth:`zpttrs`
complex matrix: :meth:`zgetrs`
complex symmetric indefinite matrix: :meth:`zsytrs`
complex symmetric indefinite matrix, packed storage: :meth:`zsptrs`
complex tridiagonal matrix: :meth:`zgttrs`
real band matrix: :meth:`dgbtrs`
real matrix: :meth:`dgetrs`
real symmetric indefinite matrix: :meth:`dsytrs`
real symmetric indefinite matrix, packed storage: :meth:`dsptrs`
real symmetric positive definite band matrix: :meth:`dpbtrs`
real symmetric positive definite matrix: :meth:`dpotrs`
real symmetric positive definite matrix, packed storage: :meth:`dpptrs`
real symmetric positive definite matrix, RFP storage: :meth:`dpftrs`
real symmetric positive definite tridiagonal matrix: :meth:`dpttrs`
real tridiagonal matrix: :meth:`dgttrs`
expert drivers (with condition and error estimation)
complex band matrix: :meth:`zgbsvx`
complex Hermitian indefinite matrix: :meth:`zhesvx`
complex Hermitian indefinite matrix, packed storage: :meth:`zhpsvx`
complex Hermitian positive definite band matrix: :meth:`zpbsvx`
complex Hermitian positive definite matrix: :meth:`zposvx`
complex Hermitian positive definite matrix, packed storage: :meth:`zppsvx`
complex Hermitian positive definite tridiagonal matrix: :meth:`zptsvx`
complex matrix: :meth:`zgesvx`
complex symmetric indefinite matrix: :meth:`zsysvx`
complex symmetric indefinite matrix, packed storage: :meth:`zspsvx`
complex tridiagonal matrix: :meth:`zgtsvx`
real band matrix: :meth:`dgbsvx`
real matrix: :meth:`dgesvx`
real symmetric indefinite matrix: :meth:`dsysvx`
real symmetric indefinite matrix, packed storage: :meth:`dspsvx`
real symmetric positive definite band matrix: :meth:`dpbsvx`
real symmetric positive definite matrix: :meth:`dposvx`
real symmetric positive definite matrix, packed storage: :meth:`dppsvx`
real symmetric positive definite tridiagonal matrix: :meth:`dptsvx`
real tridiagonal matrix: :meth:`dgtsvx`
simple drivers
complex band matrix: :meth:`zgbsv`
complex Hermitian indefinite matrix: :meth:`zhesv`
complex Hermitian indefinite matrix, packed storage: :meth:`zhpsv`
complex Hermitian positive definite band matrix: :meth:`zpbsv`
complex Hermitian positive definite matrix: :meth:`zposv`
complex Hermitian positive definite matrix, packed storage: :meth:`zppsv`
complex Hermitian positive definite matrix, using mixed precision: :meth:`zcposv`
complex Hermitian positive definite tridiagonal matrix: :meth:`zptsv`
complex matrix: :meth:`zgesv`
complex matrix, using mixed precision: :meth:`zcgesv`
complex symmetric indefinite matrix: :meth:`zsysv`
complex symmetric indefinite matrix, packed storage: :meth:`zspsv`
complex triangular band matrix: :meth:`ztbtrs`
complex triangular matrix: :meth:`ztrtrs`
complex triangular matrix, packed storage: :meth:`ztptrs`
complex tridiagonal matrix: :meth:`zgtsv`
real band matrix: :meth:`dgbsv`
real matrix: :meth:`dgesv`
real matrix, using mixed precision: :meth:`dsgesv`
real symmetric indefinite matrix: :meth:`dsysv`
real symmetric indefinite matrix, packed storage: :meth:`dspsv`
real symmetric positive definite band matrix: :meth:`dpbsv`
real symmetric positive definite matrix: :meth:`dposv`
real symmetric positive definite matrix, packed storage: :meth:`dppsv`
real symmetric positive definite matrix, using mixed precision: :meth:`dsposv`
real symmetric positive definite tridiagonal matrix: :meth:`dptsv`
real triangular band matrix: :meth:`dtbtrs`
real triangular matrix: :meth:`dtrtrs`
real triangular matrix, packed storage: :meth:`dtptrs`
real tridiagonal matrix: :meth:`dgtsv`
For full information please refer to the NAG Library document
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07intro.html
"""
# NAG Copyright 2017-2024.
[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://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07aaf.html
.. _f07aa-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` coefficient matrix :math:`A`.
**b** : float, array-like, shape :math:`\left(n, \textit{nrhs}\right)`
The :math:`n\times r` right-hand side matrix :math:`B`.
**Returns**
**a** : float, ndarray, shape :math:`\left(n, n\right)`
The factors :math:`L` and :math:`U` from the factorization :math:`A = PLU`; the unit diagonal elements of :math:`L` are not stored.
**ipiv** : int, ndarray, shape :math:`\left(n\right)`
If no constraints are violated, the pivot indices that define the permutation matrix :math:`P`; at the :math:`i`\ th step row :math:`i` of the matrix was interchanged with row :math:`\mathrm{ipiv}[i-1]`. :math:`\mathrm{ipiv}[i-1] = i` indicates a row interchange was not required.
**b** : float, ndarray, shape :math:`\left(n, \textit{nrhs}\right)`
If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`.
.. _f07aa-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\textit{nrhs}`.
Constraint: :math:`\textit{nrhs}\geq 0`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`i > 0`)
Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`U` is exactly singular, so the solution could not be computed.
.. _f07aa-py2-py-notes:
**Notes**
``dgesv`` uses the :math:`LU` decomposition with partial pivoting and row interchanges to factor :math:`A` as
.. math::
A = PLU\text{,}
where :math:`P` is a permutation matrix, :math:`L` is unit lower triangular, and :math:`U` is upper triangular.
The factored form of :math:`A` is then used to solve the system of equations :math:`AX = B`.
.. _f07aa-py2-py-references:
**References**
Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
See Also
--------
:meth:`naginterfaces.library.examples.lapacklin.dgesv_ex.main`
"""
raise NotImplementedError
[docs]def dgesvx(fact, trans, n, nrhs, a, equed, b, af=None, ipiv=None, r=None, c=None):
r"""
``dgesvx`` uses the :math:`LU` factorization to compute the solution to a real system of linear equations
.. math::
AX = B\quad \text{ or }\quad A^\mathrm{T}X = B\text{,}
where :math:`A` is an :math:`n\times n` matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices.
Error bounds on the solution and a condition estimate are also provided.
.. _f07ab-py2-py-doc:
For full information please refer to the NAG Library document for f07ab
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07abf.html
.. _f07ab-py2-py-parameters:
**Parameters**
**fact** : str, length 1
Specifies whether or not the factorized form of the matrix :math:`A` is supplied on entry, and if not, whether the matrix :math:`A` should be equilibrated before it is factorized.
:math:`\mathrm{fact} = \texttt{'F'}`
:math:`\mathrm{af}` and :math:`\mathrm{ipiv}` contain the factorized form of :math:`A`. If :math:`\mathrm{equed} \neq \texttt{'N'}`, the matrix :math:`A` has been equilibrated with scaling factors given by :math:`\mathrm{r}` and :math:`\mathrm{c}`. :math:`\mathrm{a}`, :math:`\mathrm{af}` and :math:`\mathrm{ipiv}` are not modified.
:math:`\mathrm{fact} = \texttt{'N'}`
The matrix :math:`A` will be copied to :math:`\mathrm{af}` and factorized.
:math:`\mathrm{fact} = \texttt{'E'}`
The matrix :math:`A` will be equilibrated if necessary, then copied to :math:`\mathrm{af}` and factorized.
**trans** : str, length 1
Specifies the form of the system of equations.
:math:`\mathrm{trans} = \texttt{'N'}`
:math:`AX = B` (No transpose).
:math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}`
:math:`A^\mathrm{T}X = B` (Transpose).
**n** : int
:math:`n`, the number of linear equations, i.e., the order of the matrix :math:`A`.
**nrhs** : int
:math:`r`, the number of right-hand sides, i.e., the number of columns of the matrix :math:`B`.
**a** : float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)`
The :math:`n\times n` matrix :math:`A`.
If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} \neq \texttt{'N'}`, :math:`\mathrm{a}` must have been equilibrated by the scaling factors in :math:`\mathrm{r}` and/or :math:`\mathrm{c}`.
**equed** : None or str, length 1
If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{equed}` need not be set.
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` must specify the form of the equilibration that was performed as follows:
if :math:`\mathrm{equed} = \texttt{'N'}`, no equilibration;
if :math:`\mathrm{equed} = \texttt{'R'}`, row equilibration, i.e., :math:`A` has been premultiplied by :math:`D_R`;
if :math:`\mathrm{equed} = \texttt{'C'}`, column equilibration, i.e., :math:`A` has been postmultiplied by :math:`D_C`;
if :math:`\mathrm{equed} = \texttt{'B'}`, both row and column equilibration, i.e., :math:`A` has been replaced by :math:`D_RAD_C`.
**b** : float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)`
The :math:`n\times r` right-hand side matrix :math:`B`.
**af** : None or float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)`, optional
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{af}` contains the factors :math:`L` and :math:`U` from the factorization :math:`A = PLU` as computed by :meth:`dgetrf`. If :math:`\mathrm{equed} \neq \texttt{'N'}`, :math:`\mathrm{af}` is the factorized form of the equilibrated matrix :math:`A`.
If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{af}` need not be set.
**ipiv** : None or int, array-like, shape :math:`\left(\mathrm{n}\right)`, optional
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{ipiv}` contains the pivot indices from the factorization :math:`A = PLU` as computed by :meth:`dgetrf`; at the :math:`i`\ th step row :math:`i` of the matrix was interchanged with row :math:`\mathrm{ipiv}[i-1]`. :math:`\mathrm{ipiv}[i-1] = i` indicates a row interchange was not required.
If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{ipiv}` need not be set.
**r** : None or float, array-like, shape :math:`\left(\mathrm{n}\right)`, optional
If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{r}` need not be set.
If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{r}` must contain the row scale factors for :math:`A`, :math:`D_R`; each element of :math:`\mathrm{r}` must be positive.
**c** : None or float, array-like, shape :math:`\left(\mathrm{n}\right)`, optional
If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{c}` need not be set.
If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'C'}` or :math:`\texttt{'B'}`, :math:`\mathrm{c}` must contain the column scale factors for :math:`A`, :math:`D_C`; each element of :math:`\mathrm{c}` must be positive.
**Returns**
**a** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'F'}` or :math:`\texttt{'N'}`, or if :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{a}` is not modified.
If :math:`\mathrm{fact} = \texttt{'E'}` or :math:`\mathrm{equed} \neq \texttt{'N'}`, :math:`A` is scaled as follows:
if :math:`\mathrm{equed} = \texttt{'R'}`, :math:`A = D_RA`;
if :math:`\mathrm{equed} = \texttt{'C'}`, :math:`A = AD_C`;
if :math:`\mathrm{equed} = \texttt{'B'}`, :math:`A = D_RAD_C`.
**af** : None or float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{af}` returns the factors :math:`L` and :math:`U` from the factorization :math:`A = PLU` of the original matrix :math:`A`.
If :math:`\mathrm{fact} = \texttt{'E'}`, :math:`\mathrm{af}` returns the factors :math:`L` and :math:`U` from the factorization :math:`A = PLU` of the equilibrated matrix :math:`A` (see the description of :math:`\mathrm{a}` for the form of the equilibrated matrix).
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{af}` is unchanged from entry.
**ipiv** : None or int, ndarray, shape :math:`\left(\mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{ipiv}` contains the pivot indices from the factorization :math:`A = PLU` of the original matrix :math:`A`.
If :math:`\mathrm{fact} = \texttt{'E'}`, :math:`\mathrm{ipiv}` contains the pivot indices from the factorization :math:`A = PLU` of the equilibrated matrix :math:`A`.
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{ipiv}` is unchanged from entry.
**equed** : None or str, length 1
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` is unchanged from entry.
Otherwise, if no constraints are violated, :math:`\mathrm{equed}` specifies the form of equilibration that was performed as specified above.
**r** : None or float, ndarray, shape :math:`\left(\mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{r}` is unchanged from entry.
Otherwise, if no constraints are violated and :math:`\mathrm{equed} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{r}` contains the row scale factors for :math:`A`, :math:`D_R`, such that :math:`A` is multiplied on the left by :math:`D_R`; each element of :math:`\mathrm{r}` is positive.
**c** : None or float, ndarray, shape :math:`\left(\mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{c}` is unchanged from entry.
Otherwise, if no constraints are violated and :math:`\mathrm{equed} = \texttt{'C'}` or :math:`\texttt{'B'}`, :math:`\mathrm{c}` contains the row scale factors for :math:`A`, :math:`D_C`; each element of :math:`\mathrm{c}` is positive.
**b** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)`
If :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{b}` is not modified.
If :math:`\mathrm{trans} = \texttt{'N'}` and :math:`\mathrm{equed} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{b}` is overwritten by :math:`D_RB`.
If :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}` and :math:`\mathrm{equed} = \texttt{'C'}` or :math:`\texttt{'B'}`, :math:`\mathrm{b}` is overwritten by :math:`D_CB`.
**x** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)`
If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, the :math:`n\times r` solution matrix :math:`X` to the original system of equations. Note that the arrays :math:`A` and :math:`B` are modified on exit if :math:`\mathrm{equed} \neq \texttt{'N'}`, and the solution to the equilibrated system is :math:`D_C^{-1}X` if :math:`\mathrm{trans} = \texttt{'N'}` and :math:`\mathrm{equed} = \texttt{'C'}` or :math:`\texttt{'B'}`, or :math:`D_R^{-1}X` if :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}` and :math:`\mathrm{equed} = \texttt{'R'}` or :math:`\texttt{'B'}`.
**rcond** : float
If no constraints are violated, an estimate of the reciprocal condition number of the matrix :math:`A` (after equilibration if that is performed), computed as :math:`\mathrm{rcond} = 1.0/\left(\left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\right)`.
**ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)`
If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the forward error bound for each computed solution vector, such that :math:`\left\lVert \hat{x}_j-x_j\right\rVert_\infty/\left\lVert x_j\right\rVert_\infty\leq \mathrm{ferr}[j-1]` where :math:`\hat{x}_j` is the :math:`j`\ th column of the computed solution returned in the array :math:`\mathrm{x}` and :math:`x_j` is the corresponding column of the exact solution :math:`X`. The estimate is as reliable as the estimate for :math:`\mathrm{rcond}`, and is almost always a slight overestimate of the true error.
**berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)`
If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the component-wise relative backward error of each computed solution vector :math:`\hat{x}_j` (i.e., the smallest relative change in any element of :math:`A` or :math:`B` that makes :math:`\hat{x}_j` an exact solution).
**recip_growth_factor** : float
If no exception or warning is raised, the reciprocal pivot growth factor :math:`\left\lVert A\right\rVert /\left\lVert U\right\rVert`, where :math:`\left\lVert.\right\rVert` denotes the maximum absolute element norm. If :math:`\mathrm{recip\_growth\_factor}≪1`, the stability of the :math:`LU` factorization of (equilibrated) :math:`A` could be poor. This also means that the solution :math:`\mathrm{x}`, condition estimate :math:`\mathrm{rcond}`, and forward error bound :math:`\mathrm{ferr}` could be unreliable. If the factorization fails with :math:`\mathrm{errno}` in 1 ... :math:`\mathrm{n}`, then :math:`\mathrm{recip\_growth\_factor}` contains the reciprocal pivot growth factor for the leading :math:`\textit{errno}` columns of :math:`A`.
.. _f07ab-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{fact}`.
Constraint: :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\texttt{'N'}` or :math:`\texttt{'E'}`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\mathrm{trans}`.
Constraint: :math:`\mathrm{trans} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{n}`.
Constraint: :math:`\mathrm{n}\geq 0`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\mathrm{nrhs}`.
Constraint: :math:`\mathrm{nrhs}\geq 0`.
(`errno` :math:`-10`)
On entry, error in parameter :math:`\mathrm{equed}`.
Constraint: :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\texttt{'R'}`, :math:`\texttt{'C'}` or :math:`\texttt{'B'}`.
(`errno` :math:`-11`)
On entry, error in parameter :math:`\mathrm{r}`.
(`errno` :math:`-12`)
On entry, error in parameter :math:`\mathrm{c}`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq \mathrm{n}\right)`)
Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`U` is exactly singular, so the solution and error bounds could not be computed. :math:`\mathrm{rcond} = 0.0` is returned.
(`errno` :math:`\mathrm{n}+1`)
:math:`U` is nonsingular, but :math:`\mathrm{rcond}` is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of :math:`\mathrm{rcond}` would suggest.
.. _f07ab-py2-py-notes:
**Notes**
``dgesvx`` performs the following steps:
(1) **Equilibration**
The linear system to be solved may be badly scaled.
However, the system can be equilibrated as a first stage by setting :math:`\mathrm{fact} = \texttt{'E'}`.
In this case, real scaling factors are computed and these factors then determine whether the system is to be equilibrated.
Equilibrated forms of the systems :math:`AX = B` and :math:`A^\mathrm{T}X = B` are
.. math::
\left(D_RAD_C\right)\left(D_C^{-1}X\right) = D_RB
and
.. math::
\left(D_RAD_C\right)^\mathrm{T}\left(D_R^{-1}X\right) = D_CB\text{,}
respectively, where :math:`D_R` and :math:`D_C` are diagonal matrices, with positive diagonal elements, formed from the computed scaling factors.
When equilibration is used, :math:`A` will be overwritten by :math:`D_RAD_C` and :math:`B` will be overwritten by :math:`D_RB` (or :math:`D_CB` when the solution of :math:`A^\mathrm{T}X = B` is sought).
(#) **Factorization**
The matrix :math:`A`, or its scaled form, is copied and factored using the :math:`LU` decomposition
.. math::
A = PLU\text{,}
where :math:`P` is a permutation matrix, :math:`L` is a unit lower triangular matrix, and :math:`U` is upper triangular.
This stage can be by-passed when a factored matrix (with scaled matrices and scaling factors) are supplied; for example, as provided by a previous call to ``dgesvx`` with the same matrix :math:`A`.
(#) **Condition Number Estimation**
The :math:`LU` factorization of :math:`A` determines whether a solution to the linear system exists.
If some diagonal element of :math:`U` is zero, then :math:`U` is exactly singular, no solution exists and the function returns with a failure.
Otherwise the factorized form of :math:`A` is used to estimate the condition number of the matrix :math:`A`.
If the reciprocal of the condition number is less than machine precision then a warning code is returned on final exit.
(#) **Solution**
The (equilibrated) system is solved for :math:`X` (:math:`D_C^{-1}X` or :math:`D_R^{-1}X`) using the factored form of :math:`A` (:math:`D_RAD_C`).
(#) **Iterative Refinement**
Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for the computed solution.
(#) **Construct Solution Matrix** :math:`X`
If equilibration was used, the matrix :math:`X` is premultiplied by :math:`D_C` (if :math:`\mathrm{trans} = \texttt{'N'}`) or :math:`D_R` (if :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}`) so that it solves the original system before equilibration.
.. _f07ab-py2-py-references:
**References**
Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia
"""
raise NotImplementedError
[docs]def dsgesv(a, b):
r"""
``dsgesv`` computes the solution to a real system of linear equations
.. math::
AX = B\text{,}
where :math:`A` is an :math:`n\times n` matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices.
.. _f07ac-py2-py-doc:
For full information please refer to the NAG Library document for f07ac
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07acf.html
.. _f07ac-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` coefficient matrix :math:`A`.
**b** : float, array-like, shape :math:`\left(n, \textit{nrhs}\right)`
The :math:`n\times r` right-hand side matrix :math:`B`.
**Returns**
**a** : float, ndarray, shape :math:`\left(n, n\right)`
If iterative refinement has been successfully used (i.e., if no exception or warning is raised and :math:`\mathrm{itera}\geq 0`), then :math:`A` is unchanged. If double precision factorization has been used (when no exception or warning is raised and :math:`\mathrm{itera} < 0`), :math:`A` contains the factors :math:`L` and :math:`U` from the factorization :math:`A = PLU`; the unit diagonal elements of :math:`L` are not stored.
**ipiv** : int, ndarray, shape :math:`\left(n\right)`
If no constraints are violated, the pivot indices that define the permutation matrix :math:`P`; at the :math:`i`\ th step row :math:`i` of the matrix was interchanged with row :math:`\mathrm{ipiv}[i-1]`. :math:`\mathrm{ipiv}[i-1] = i` indicates a row interchange was not required. :math:`\mathrm{ipiv}` corresponds either to the single precision factorization (if no exception or warning is raised and :math:`\mathrm{itera}\geq 0`) or to the double precision factorization (if no exception or warning is raised and :math:`\mathrm{itera} < 0`).
**x** : float, ndarray, shape :math:`\left(n, \textit{nrhs}\right)`
If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`.
**itera** : int
If :math:`\mathrm{itera} > 0`, iterative refinement has been successfully used and :math:`\mathrm{itera}` is the number of iterations carried out.
If :math:`\mathrm{itera} < 0`, iterative refinement has failed for one of the reasons given below and double precision factorization has been carried out instead.
:math:`\mathrm{itera} = -1`
Taking into account machine parameters, and the values of :math:`\textit{n}` and :math:`\textit{nrhs}`, it is not worth working in single precision.
:math:`\mathrm{itera} = -2`
Overflow of an entry occurred when moving from double to single precision.
:math:`\mathrm{itera} = -3`
An intermediate single precision factorization failed.
:math:`\mathrm{itera} = -31`
The maximum permitted number of iterations was exceeded.
.. _f07ac-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\textit{nrhs}`.
Constraint: :math:`\textit{nrhs}\geq 0`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`i > 0`)
Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`U` is exactly singular, so the solution could not be computed.
.. _f07ac-py2-py-notes:
**Notes**
``dsgesv`` first attempts to factorize the matrix in single precision and use this factorization within an iterative refinement procedure to produce a solution with full double precision accuracy.
If the approach fails the method switches to a double precision factorization and solve.
The iterative refinement process is stopped if
.. math::
\mathrm{itera} > \textit{itermax}\text{,}
where :math:`\mathrm{itera}` is the number of iterations carried out thus far and :math:`\textit{itermax}` is the maximum number of iterations allowed, which is fixed at :math:`30` iterations.
The process is also stopped if for all right-hand sides we have
.. math::
\left\lVert \textit{resid}\right\rVert < \sqrt{n}\left\lVert x\right\rVert \left\lVert A\right\rVert \epsilon \text{,}
where :math:`\left\lVert \textit{resid}\right\rVert` is the :math:`\infty`-norm of the residual, :math:`\left\lVert x\right\rVert` is the :math:`\infty`-norm of the solution, :math:`\left\lVert A\right\rVert` is the :math:`\infty`-operator-norm of the matrix :math:`A` and :math:`\epsilon` is the machine precision returned by :meth:`machine.precision <naginterfaces.library.machine.precision>`.
The iterative refinement strategy used by ``dsgesv`` can be more efficient than the corresponding direct full precision algorithm.
Since this strategy must perform iterative refinement on each right-hand side, any efficiency gains will reduce as the number of right-hand sides increases.
Conversely, as the matrix size increases the cost of these iterative refinements become less significant relative to the cost of factorization.
Thus, any efficiency gains will be greatest for a very small number of right-hand sides and for large matrix sizes.
The cut-off values for the number of right-hand sides and matrix size, for which the iterative refinement strategy performs better, depends on the relative performance of the reduced and full precision factorization and back-substitution.
For now, ``dsgesv`` always attempts the iterative refinement strategy first; you are advised to compare the performance of ``dsgesv`` with that of its full precision counterpart :meth:`dgesv` to determine whether this strategy is worthwhile for your particular problem dimensions.
.. _f07ac-py2-py-references:
**References**
Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug
Buttari, A, Dongarra, J, Langou, J, Langou, J, Luszczek, P and Kurzak, J, 2007, `Mixed precision iterative refinement techniques for the solution of dense linear systems`, International Journal of High Performance Computing Applications
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError
[docs]def dgetrf(a):
r"""
``dgetrf`` computes the :math:`LU` factorization of a real :math:`m\times n` matrix.
.. _f07ad-py2-py-doc:
For full information please refer to the NAG Library document for f07ad
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07adf.html
.. _f07ad-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(m, n\right)`
The :math:`m\times n` matrix :math:`A`.
**Returns**
**a** : float, ndarray, shape :math:`\left(m, n\right)`
The factors :math:`L` and :math:`U` from the factorization :math:`A = PLU`; the unit diagonal elements of :math:`L` are not stored.
**ipiv** : int, ndarray, shape :math:`\left(\min\left(m,n\right)\right)`
The pivot indices that define the permutation matrix. At the :math:`\textit{i}`\ th step, if :math:`\mathrm{ipiv}[\textit{i}-1] > \textit{i}` then row :math:`\textit{i}` of the matrix :math:`A` was interchanged with row :math:`\mathrm{ipiv}[\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,\mathrm{min}\left(m, n\right)`. :math:`\mathrm{ipiv}[i-1]\leq i` indicates that, at the :math:`i`\ th step, a row interchange was not required.
.. _f07ad-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\textit{m}`.
Constraint: :math:`m\geq 0`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`i > 0`)
Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`U` is exactly singular, and division by zero will occur if it is used to solve a system of equations.
.. _f07ad-py2-py-notes:
**Notes**
``dgetrf`` forms the :math:`LU` factorization of a real :math:`m\times n` matrix :math:`A` as :math:`A = PLU`, where :math:`P` is a permutation matrix, :math:`L` is lower triangular with unit diagonal elements (lower trapezoidal if :math:`m > n`) and :math:`U` is upper triangular (upper trapezoidal if :math:`m < n`).
Usually :math:`A` is square :math:`\left(m = n\right)`, and both :math:`L` and :math:`U` are triangular.
The function uses partial pivoting, with row interchanges.
.. _f07ad-py2-py-references:
**References**
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError
[docs]def dgetrs(trans, a, ipiv, b):
r"""
``dgetrs`` solves a real system of linear equations with multiple right-hand sides,
.. math::
AX = B\quad \text{ or }\quad A^\mathrm{T}X = B\text{,}
where :math:`A` has been factorized by :meth:`dgetrf`.
.. _f07ae-py2-py-doc:
For full information please refer to the NAG Library document for f07ae
https://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07aff.html
.. _f07af-py2-py-parameters:
**Parameters**
**a** : float, array-like, shape :math:`\left(m, n\right)`
The matrix :math:`A` whose scaling factors are to be computed.
**Returns**
**r** : float, ndarray, shape :math:`\left(m\right)`
If no exception or warning is raised or :math:`\mathrm{errno}` > :math:`\mathrm{m}`, :math:`\mathrm{r}` contains the row scale factors, the diagonal elements of :math:`D_R`. The elements of :math:`\mathrm{r}` will be positive.
**c** : float, ndarray, shape :math:`\left(n\right)`
If no exception or warning is raised, :math:`\mathrm{c}` contains the column scale factors, the diagonal elements of :math:`D_C`. The elements of :math:`\mathrm{c}` will be positive.
**rowcnd** : float
If no exception or warning is raised or :math:`\mathrm{errno}` > :math:`\mathrm{m}`, :math:`\mathrm{rowcnd}` contains the ratio of the smallest value of :math:`\mathrm{r}[i-1]` to the largest value of :math:`\mathrm{r}[i-1]`. If :math:`\mathrm{rowcnd}\geq 0.1` and :math:`\mathrm{amax}` is neither too large nor too small, it is not worth scaling by :math:`D_R`.
**colcnd** : float
If no exception or warning is raised, :math:`\mathrm{colcnd}` contains the ratio of the smallest value of :math:`\mathrm{c}[i-1]` to the largest value of :math:`\mathrm{c}[i-1]`.
If :math:`\mathrm{colcnd}\geq 0.1`, it is not worth scaling by :math:`D_C`.
**amax** : float
:math:`\mathrm{max}\left\lvert a_{{ij}}\right\rvert`. If :math:`\mathrm{amax}` is very close to overflow or underflow, the matrix :math:`A` should be scaled.
.. _f07af-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\textit{m}`.
Constraint: :math:`m\geq 0`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq m\right)`)
Row :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is exactly zero.
(`errno` :math:`i > m`)
Column :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is exactly zero.
.. _f07af-py2-py-notes:
**Notes**
``dgeequ`` computes the diagonal scaling matrices.
The diagonal scaling matrices are chosen to try to make the elements of largest absolute value in each row and column of the matrix :math:`B` given by
.. math::
B = D_RAD_C
have absolute value :math:`1`.
The diagonal elements of :math:`D_R` and :math:`D_C` are restricted to lie in the safe range :math:`\left(\delta, {1/\delta }\right)`, where :math:`\delta` is the value returned by function :meth:`machine.real_safe <naginterfaces.library.machine.real_safe>`.
Use of these scaling factors is not guaranteed to reduce the condition number of :math:`A` but works well in practice.
"""
raise NotImplementedError
[docs]def dgecon(norm, n, a, anorm):
r"""
``dgecon`` estimates the condition number of a real matrix :math:`A`, where :math:`A` has been factorized by :meth:`dgetrf`.
.. _f07ag-py2-py-doc:
For full information please refer to the NAG Library document for f07ag
https://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07anf.html
.. _f07an-py2-py-parameters:
**Parameters**
**a** : complex, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` coefficient matrix :math:`A`.
**b** : complex, array-like, shape :math:`\left(n, \textit{nrhs}\right)`
The :math:`n\times r` right-hand side matrix :math:`B`.
**Returns**
**a** : complex, ndarray, shape :math:`\left(n, n\right)`
The factors :math:`L` and :math:`U` from the factorization :math:`A = PLU`; the unit diagonal elements of :math:`L` are not stored.
**ipiv** : int, ndarray, shape :math:`\left(n\right)`
If no constraints are violated, the pivot indices that define the permutation matrix :math:`P`; at the :math:`i`\ th step row :math:`i` of the matrix was interchanged with row :math:`\mathrm{ipiv}[i-1]`. :math:`\mathrm{ipiv}[i-1] = i` indicates a row interchange was not required.
**b** : complex, ndarray, shape :math:`\left(n, \textit{nrhs}\right)`
If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`.
.. _f07an-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\textit{nrhs}`.
Constraint: :math:`\textit{nrhs}\geq 0`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`i > 0`)
Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`U` is exactly singular, so the solution could not be computed.
.. _f07an-py2-py-notes:
**Notes**
``zgesv`` uses the :math:`LU` decomposition with partial pivoting and row interchanges to factor :math:`A` as
.. math::
A = PLU\text{,}
where :math:`P` is a permutation matrix, :math:`L` is unit lower triangular, and :math:`U` is upper triangular.
The factored form of :math:`A` is then used to solve the system of equations :math:`AX = B`.
.. _f07an-py2-py-references:
**References**
Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError
[docs]def zgesvx(fact, trans, nrhs, a, af, ipiv, equed, r, c, b):
r"""
``zgesvx`` uses the :math:`LU` factorization to compute the solution to a complex system of linear equations
.. math::
AX = B\quad \text{ or }\quad A^\mathrm{T}X = B\quad \text{ or }\quad A^\mathrm{H}X = B\text{,}
where :math:`A` is an :math:`n\times n` matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices.
Error bounds on the solution and a condition estimate are also provided.
.. _f07ap-py2-py-doc:
For full information please refer to the NAG Library document for f07ap
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07apf.html
.. _f07ap-py2-py-parameters:
**Parameters**
**fact** : str, length 1
Specifies whether or not the factorized form of the matrix :math:`A` is supplied on entry, and if not, whether the matrix :math:`A` should be equilibrated before it is factorized.
:math:`\mathrm{fact} = \texttt{'F'}`
:math:`\mathrm{af}` and :math:`\mathrm{ipiv}` contain the factorized form of :math:`A`. If :math:`\mathrm{equed} \neq \texttt{'N'}`, the matrix :math:`A` has been equilibrated with scaling factors given by :math:`\mathrm{r}` and :math:`\mathrm{c}`. :math:`\mathrm{a}`, :math:`\mathrm{af}` and :math:`\mathrm{ipiv}` are not modified.
:math:`\mathrm{fact} = \texttt{'N'}`
The matrix :math:`A` will be copied to :math:`\mathrm{af}` and factorized.
:math:`\mathrm{fact} = \texttt{'E'}`
The matrix :math:`A` will be equilibrated if necessary, then copied to :math:`\mathrm{af}` and factorized.
**trans** : str, length 1
Specifies the form of the system of equations.
:math:`\mathrm{trans} = \texttt{'N'}`
:math:`AX = B` (No transpose).
:math:`\mathrm{trans} = \texttt{'T'}`
:math:`A^\mathrm{T}X = B` (Transpose).
:math:`\mathrm{trans} = \texttt{'C'}`
:math:`A^\mathrm{H}X = B` (Conjugate transpose).
**nrhs** : int
:math:`r`, the number of right-hand sides, i.e., the number of columns of the matrix :math:`B`.
**a** : complex, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` matrix :math:`A`.
If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} \neq \texttt{'N'}`, :math:`\mathrm{a}` must have been equilibrated by the scaling factors in :math:`\mathrm{r}` and/or :math:`\mathrm{c}`.
**af** : complex, array-like, shape :math:`\left(n, n\right)`
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{af}` contains the factors :math:`L` and :math:`U` from the factorization :math:`A = PLU` as computed by :meth:`zgetrf`. If :math:`\mathrm{equed} \neq \texttt{'N'}`, :math:`\mathrm{af}` is the factorized form of the equilibrated matrix :math:`A`.
If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{af}` need not be set.
**ipiv** : int, array-like, shape :math:`\left(n\right)`
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{ipiv}` contains the pivot indices from the factorization :math:`A = PLU` as computed by :meth:`zgetrf`; at the :math:`i`\ th step row :math:`i` of the matrix was interchanged with row :math:`\mathrm{ipiv}[i-1]`. :math:`\mathrm{ipiv}[i-1] = i` indicates a row interchange was not required.
If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{ipiv}` need not be set.
**equed** : str, length 1
If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{equed}` need not be set.
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` must specify the form of the equilibration that was performed as follows:
if :math:`\mathrm{equed} = \texttt{'N'}`, no equilibration;
if :math:`\mathrm{equed} = \texttt{'R'}`, row equilibration, i.e., :math:`A` has been premultiplied by :math:`D_R`;
if :math:`\mathrm{equed} = \texttt{'C'}`, column equilibration, i.e., :math:`A` has been postmultiplied by :math:`D_C`;
if :math:`\mathrm{equed} = \texttt{'B'}`, both row and column equilibration, i.e., :math:`A` has been replaced by :math:`D_RAD_C`.
**r** : float, array-like, shape :math:`\left(n\right)`
If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{r}` need not be set.
If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{r}` must contain the row scale factors for :math:`A`, :math:`D_R`; each element of :math:`\mathrm{r}` must be positive.
**c** : float, array-like, shape :math:`\left(n\right)`
If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{c}` need not be set.
If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'C'}` or :math:`\texttt{'B'}`, :math:`\mathrm{c}` must contain the column scale factors for :math:`A`, :math:`D_C`; each element of :math:`\mathrm{c}` must be positive.
**b** : complex, array-like, shape :math:`\left(n, \mathrm{nrhs}\right)`
The :math:`n\times r` right-hand side matrix :math:`B`.
**Returns**
**a** : complex, ndarray, shape :math:`\left(n, n\right)`
If :math:`\mathrm{fact} = \texttt{'F'}` or :math:`\texttt{'N'}`, or if :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{a}` is not modified.
If :math:`\mathrm{fact} = \texttt{'E'}` or :math:`\mathrm{equed} \neq \texttt{'N'}`, :math:`A` is scaled as follows:
if :math:`\mathrm{equed} = \texttt{'R'}`, :math:`A = D_RA`;
if :math:`\mathrm{equed} = \texttt{'C'}`, :math:`A = AD_C`;
if :math:`\mathrm{equed} = \texttt{'B'}`, :math:`A = D_RAD_C`.
**af** : complex, ndarray, shape :math:`\left(n, n\right)`
If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{af}` returns the factors :math:`L` and :math:`U` from the factorization :math:`A = PLU` of the original matrix :math:`A`.
If :math:`\mathrm{fact} = \texttt{'E'}`, :math:`\mathrm{af}` returns the factors :math:`L` and :math:`U` from the factorization :math:`A = PLU` of the equilibrated matrix :math:`A` (see the description of :math:`\mathrm{a}` for the form of the equilibrated matrix).
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{af}` is unchanged from entry.
**ipiv** : int, ndarray, shape :math:`\left(n\right)`
If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{ipiv}` contains the pivot indices from the factorization :math:`A = PLU` of the original matrix :math:`A`.
If :math:`\mathrm{fact} = \texttt{'E'}`, :math:`\mathrm{ipiv}` contains the pivot indices from the factorization :math:`A = PLU` of the equilibrated matrix :math:`A`.
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{ipiv}` is unchanged from entry.
**equed** : str, length 1
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` is unchanged from entry.
Otherwise, if no constraints are violated, :math:`\mathrm{equed}` specifies the form of equilibration that was performed as specified above.
**r** : float, ndarray, shape :math:`\left(n\right)`
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{r}` is unchanged from entry.
Otherwise, if no constraints are violated and :math:`\mathrm{equed} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{r}` contains the row scale factors for :math:`A`, :math:`D_R`, such that :math:`A` is multiplied on the left by :math:`D_R`; each element of :math:`\mathrm{r}` is positive.
**c** : float, ndarray, shape :math:`\left(n\right)`
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{c}` is unchanged from entry.
Otherwise, if no constraints are violated and :math:`\mathrm{equed} = \texttt{'C'}` or :math:`\texttt{'B'}`, :math:`\mathrm{c}` contains the row scale factors for :math:`A`, :math:`D_C`; each element of :math:`\mathrm{c}` is positive.
**b** : complex, ndarray, shape :math:`\left(n, \mathrm{nrhs}\right)`
If :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{b}` is not modified.
If :math:`\mathrm{trans} = \texttt{'N'}` and :math:`\mathrm{equed} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{b}` is overwritten by :math:`D_RB`.
If :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}` and :math:`\mathrm{equed} = \texttt{'C'}` or :math:`\texttt{'B'}`, :math:`\mathrm{b}` is overwritten by :math:`D_CB`.
**x** : complex, ndarray, shape :math:`\left(n, \mathrm{nrhs}\right)`
If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, the :math:`n\times r` solution matrix :math:`X` to the original system of equations. Note that the arrays :math:`A` and :math:`B` are modified on exit if :math:`\mathrm{equed} \neq \texttt{'N'}`, and the solution to the equilibrated system is :math:`D_C^{-1}X` if :math:`\mathrm{trans} = \texttt{'N'}` and :math:`\mathrm{equed} = \texttt{'C'}` or :math:`\texttt{'B'}`, or :math:`D_R^{-1}X` if :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}` and :math:`\mathrm{equed} = \texttt{'R'}` or :math:`\texttt{'B'}`.
**rcond** : float
If no constraints are violated, an estimate of the reciprocal condition number of the matrix :math:`A` (after equilibration if that is performed), computed as :math:`\mathrm{rcond} = 1.0/\left(\left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\right)`.
**ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)`
If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the forward error bound for each computed solution vector, such that :math:`\left\lVert \hat{x}_j-x_j\right\rVert_\infty/\left\lVert x_j\right\rVert_\infty\leq \mathrm{ferr}[j-1]` where :math:`\hat{x}_j` is the :math:`j`\ th column of the computed solution returned in the array :math:`\mathrm{x}` and :math:`x_j` is the corresponding column of the exact solution :math:`X`. The estimate is as reliable as the estimate for :math:`\mathrm{rcond}`, and is almost always a slight overestimate of the true error.
**berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)`
If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the component-wise relative backward error of each computed solution vector :math:`\hat{x}_j` (i.e., the smallest relative change in any element of :math:`A` or :math:`B` that makes :math:`\hat{x}_j` an exact solution).
**recip_growth_factor** : float
If no exception or warning is raised, the reciprocal pivot growth factor :math:`\left\lVert A\right\rVert /\left\lVert U\right\rVert`, where :math:`\left\lVert.\right\rVert` denotes the maximum absolute element norm. If :math:`\mathrm{recip\_growth\_factor}≪1`, the stability of the :math:`LU` factorization of (equilibrated) :math:`A` could be poor. This also means that the solution :math:`\mathrm{x}`, condition estimate :math:`\mathrm{rcond}`, and forward error bound :math:`\mathrm{ferr}` could be unreliable. If the factorization fails with :math:`\mathrm{errno}` in 1 ... :math:`\mathrm{n}`, then :math:`\mathrm{recip\_growth\_factor}` contains the reciprocal pivot growth factor for the leading :math:`\textit{errno}` columns of :math:`A`.
.. _f07ap-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{fact}`.
Constraint: :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\texttt{'N'}` or :math:`\texttt{'E'}`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\mathrm{trans}`.
Constraint: :math:`\mathrm{trans} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\mathrm{nrhs}`.
Constraint: :math:`\mathrm{nrhs}\geq 0`.
(`errno` :math:`-10`)
On entry, error in parameter :math:`\mathrm{equed}`.
Constraint: :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\texttt{'R'}`, :math:`\texttt{'C'}` or :math:`\texttt{'B'}`.
(`errno` :math:`-11`)
On entry, error in parameter :math:`\mathrm{r}`.
(`errno` :math:`-12`)
On entry, error in parameter :math:`\mathrm{c}`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq n\right)`)
Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`U` is exactly singular, so the solution and error bounds could not be computed. :math:`\mathrm{rcond} = 0.0` is returned.
(`errno` :math:`n+1`)
:math:`U` is nonsingular, but :math:`\mathrm{rcond}` is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of :math:`\mathrm{rcond}` would suggest.
.. _f07ap-py2-py-notes:
**Notes**
``zgesvx`` performs the following steps:
(1) **Equilibration**
The linear system to be solved may be badly scaled.
However, the system can be equilibrated as a first stage by setting :math:`\mathrm{fact} = \texttt{'E'}`.
In this case, real scaling factors are computed and these factors then determine whether the system is to be equilibrated.
Equilibrated forms of the systems :math:`AX = B`, :math:`A^\mathrm{T}X = B` and :math:`A^\mathrm{H}X = B` are
.. math::
\left(D_RAD_C\right)\left(D_C^{-1}X\right) = D_RB\text{,}
.. math::
\left(D_RAD_C\right)^\mathrm{T}\left(D_R^{-1}X\right) = D_CB\text{,}
and
.. math::
\left(D_RAD_C\right)^\mathrm{H}\left(D_R^{-1}X\right) = D_CB\text{,}
respectively, where :math:`D_R` and :math:`D_C` are diagonal matrices, with positive diagonal elements, formed from the computed scaling factors.
When equilibration is used, :math:`A` will be overwritten by :math:`D_RAD_C` and :math:`B` will be overwritten by :math:`D_RB` (or :math:`D_CB` when the solution of :math:`A^\mathrm{T}X = B` or :math:`A^\mathrm{H}X = B` is sought).
(#) **Factorization**
The matrix :math:`A`, or its scaled form, is copied and factored using the :math:`LU` decomposition
.. math::
A = PLU\text{,}
where :math:`P` is a permutation matrix, :math:`L` is a unit lower triangular matrix, and :math:`U` is upper triangular.
This stage can be by-passed when a factored matrix (with scaled matrices and scaling factors) are supplied; for example, as provided by a previous call to ``zgesvx`` with the same matrix :math:`A`.
(#) **Condition Number Estimation**
The :math:`LU` factorization of :math:`A` determines whether a solution to the linear system exists.
If some diagonal element of :math:`U` is zero, then :math:`U` is exactly singular, no solution exists and the function returns with a failure.
Otherwise the factorized form of :math:`A` is used to estimate the condition number of the matrix :math:`A`.
If the reciprocal of the condition number is less than machine precision then a warning code is returned on final exit.
(#) **Solution**
The (equilibrated) system is solved for :math:`X` (:math:`D_C^{-1}X` or :math:`D_R^{-1}X`) using the factored form of :math:`A` (:math:`D_RAD_C`).
(#) **Iterative Refinement**
Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for the computed solution.
(#) **Construct Solution Matrix** :math:`X`
If equilibration was used, the matrix :math:`X` is premultiplied by :math:`D_C` (if :math:`\mathrm{trans} = \texttt{'N'}`) or :math:`D_R` (if :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}`) so that it solves the original system before equilibration.
.. _f07ap-py2-py-references:
**References**
Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia
"""
raise NotImplementedError
[docs]def zcgesv(a, b):
r"""
``zcgesv`` computes the solution to a complex system of linear equations
.. math::
AX = B\text{,}
where :math:`A` is an :math:`n\times n` matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices.
.. _f07aq-py2-py-doc:
For full information please refer to the NAG Library document for f07aq
https://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07arf.html
.. _f07ar-py2-py-parameters:
**Parameters**
**a** : complex, array-like, shape :math:`\left(m, n\right)`
The :math:`m\times n` matrix :math:`A`.
**Returns**
**a** : complex, ndarray, shape :math:`\left(m, n\right)`
The factors :math:`L` and :math:`U` from the factorization :math:`A = PLU`; the unit diagonal elements of :math:`L` are not stored.
**ipiv** : int, ndarray, shape :math:`\left(\min\left(m,n\right)\right)`
The pivot indices that define the permutation matrix. At the :math:`\textit{i}`\ th step, if :math:`\mathrm{ipiv}[\textit{i}-1] > \textit{i}` then row :math:`\textit{i}` of the matrix :math:`A` was interchanged with row :math:`\mathrm{ipiv}[\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,\mathrm{min}\left(m, n\right)`. :math:`\mathrm{ipiv}[i-1]\leq i` indicates that, at the :math:`i`\ th step, a row interchange was not required.
.. _f07ar-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\textit{m}`.
Constraint: :math:`m\geq 0`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`i > 0`)
Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`U` is exactly singular, and division by zero will occur if it is used to solve a system of equations.
.. _f07ar-py2-py-notes:
**Notes**
``zgetrf`` forms the :math:`LU` factorization of a complex :math:`m\times n` matrix :math:`A` as :math:`A = PLU`, where :math:`P` is a permutation matrix, :math:`L` is lower triangular with unit diagonal elements (lower trapezoidal if :math:`m > n`) and :math:`U` is upper triangular (upper trapezoidal if :math:`m < n`).
Usually :math:`A` is square :math:`\left(m = n\right)`, and both :math:`L` and :math:`U` are triangular.
The function uses partial pivoting, with row interchanges.
.. _f07ar-py2-py-references:
**References**
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError
[docs]def zgetrs(trans, a, ipiv, b):
r"""
``zgetrs`` solves a complex system of linear equations with multiple right-hand sides,
.. math::
AX = B\text{, }\quad A^\mathrm{T}X = B\quad \text{ or }\quad A^\mathrm{H}X = B\text{,}
where :math:`A` has been factorized by :meth:`zgetrf`.
.. _f07as-py2-py-doc:
For full information please refer to the NAG Library document for f07as
https://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07atf.html
.. _f07at-py2-py-parameters:
**Parameters**
**a** : complex, array-like, shape :math:`\left(m, n\right)`
The matrix :math:`A` whose scaling factors are to be computed.
**Returns**
**r** : float, ndarray, shape :math:`\left(m\right)`
If no exception or warning is raised or :math:`\mathrm{errno}` > :math:`\mathrm{m}`, :math:`\mathrm{r}` contains the row scale factors, the diagonal elements of :math:`D_R`. The elements of :math:`\mathrm{r}` will be positive.
**c** : float, ndarray, shape :math:`\left(n\right)`
If no exception or warning is raised, :math:`\mathrm{c}` contains the column scale factors, the diagonal elements of :math:`D_C`. The elements of :math:`\mathrm{c}` will be positive.
**rowcnd** : float
If no exception or warning is raised or :math:`\mathrm{errno}` > :math:`\mathrm{m}`, :math:`\mathrm{rowcnd}` contains the ratio of the smallest value of :math:`\mathrm{r}[i-1]` to the largest value of :math:`\mathrm{r}[i-1]`. If :math:`\mathrm{rowcnd}\geq 0.1` and :math:`\mathrm{amax}` is neither too large nor too small, it is not worth scaling by :math:`D_R`.
**colcnd** : float
If no exception or warning is raised, :math:`\mathrm{colcnd}` contains the ratio of the smallest value of :math:`\mathrm{c}[i-1]` to the largest value of :math:`\mathrm{c}[i-1]`.
If :math:`\mathrm{colcnd}\geq 0.1`, it is not worth scaling by :math:`D_C`.
**amax** : float
:math:`\mathrm{max}\left\lvert a_{{ij}}\right\rvert`. If :math:`\mathrm{amax}` is very close to overflow or underflow, the matrix :math:`A` should be scaled.
.. _f07at-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\textit{m}`.
Constraint: :math:`m\geq 0`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq m\right)`)
Row :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is exactly zero.
(`errno` :math:`i > m`)
Column :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is exactly zero.
.. _f07at-py2-py-notes:
**Notes**
``zgeequ`` computes the diagonal scaling matrices.
The diagonal scaling matrices are chosen to try to make the elements of largest absolute value in each row and column of the matrix :math:`B` given by
.. math::
B = D_RAD_C
have absolute value :math:`1`.
The diagonal elements of :math:`D_R` and :math:`D_C` are restricted to lie in the safe range :math:`\left(\delta, {1/\delta }\right)`, where :math:`\delta` is the value returned by function :meth:`machine.real_safe <naginterfaces.library.machine.real_safe>`.
Use of these scaling factors is not guaranteed to reduce the condition number of :math:`A` but works well in practice.
"""
raise NotImplementedError
[docs]def zgecon(norm, a, anorm):
r"""
``zgecon`` estimates the condition number of a complex matrix :math:`A`, where :math:`A` has been factorized by :meth:`zgetrf`.
.. _f07au-py2-py-doc:
For full information please refer to the NAG Library document for f07au
https://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07baf.html#fcomments>`__ for further details.
**b** : float, array-like, shape :math:`\left(n, \textit{nrhs}\right)`
The :math:`n\times r` right-hand side matrix :math:`B`.
**Returns**
**ab** : float, ndarray, shape :math:`\left(2\times \mathrm{kl}+\mathrm{ku}+1, n\right)`
If :math:`\mathrm{errno}` >= 0, :math:`\mathrm{ab}` is overwritten by details of the factorization.
**ipiv** : int, ndarray, shape :math:`\left(n\right)`
If no constraints are violated, the pivot indices that define the permutation matrix :math:`P`; at the :math:`i`\ th step row :math:`i` of the matrix was interchanged with row :math:`\mathrm{ipiv}[i-1]`. :math:`\mathrm{ipiv}[i-1] = i` indicates a row interchange was not required.
**b** : float, ndarray, shape :math:`\left(n, \textit{nrhs}\right)`
If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`.
.. _f07ba-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\mathrm{kl}`.
Constraint: :math:`\mathrm{kl}\geq 0`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{ku}`.
Constraint: :math:`\mathrm{ku}\geq 0`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\textit{nrhs}`.
Constraint: :math:`\textit{nrhs}\geq 0`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`i > 0`)
Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`U` is exactly singular, so the solution could not be computed.
.. _f07ba-py2-py-notes:
**Notes**
``dgbsv`` uses the :math:`LU` decomposition with partial pivoting and row interchanges to factor :math:`A` as :math:`A = PLU`, where :math:`P` is a permutation matrix, :math:`L` is a product of permutation and unit lower triangular matrices with :math:`k_l` subdiagonals, and :math:`U` is upper triangular with :math:`\left(k_l+k_u\right)` superdiagonals.
The factored form of :math:`A` is then used to solve the system of equations :math:`AX = B`.
.. _f07ba-py2-py-references:
**References**
Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError
[docs]def dgbsvx(fact, trans, n, kl, ku, nrhs, ab, afb, ipiv, equed, r, c, b):
r"""
``dgbsvx`` uses the :math:`LU` factorization to compute the solution to a real system of linear equations
.. math::
AX = B\quad \text{ or }\quad A^\mathrm{T}X = B\text{,}
where :math:`A` is an :math:`n\times n` band matrix with :math:`k_l` subdiagonals and :math:`k_u` superdiagonals, and :math:`X` and :math:`B` are :math:`n\times r` matrices.
Error bounds on the solution and a condition estimate are also provided.
.. _f07bb-py2-py-doc:
For full information please refer to the NAG Library document for f07bb
https://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07bbf.html#fcomments>`__ for further details.
If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} \neq \texttt{'N'}`, :math:`A` must have been equilibrated by the scaling factors in :math:`\mathrm{r}` and/or :math:`\mathrm{c}`.
**afb** : float, array-like, shape :math:`\left(2\times \mathrm{kl}+\mathrm{ku}+1, \mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{afb}` need not be set.
If :math:`\mathrm{fact} = \texttt{'F'}`, details of the :math:`LU` factorization of the :math:`n\times n` band matrix :math:`A`, as computed by :meth:`dgbtrf`.
If :math:`\mathrm{equed} \neq \texttt{'N'}`, :math:`\mathrm{afb}` is the factorized form of the equilibrated matrix :math:`A`.
**ipiv** : int, array-like, shape :math:`\left(\mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{ipiv}` need not be set.
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{ipiv}` contains the pivot indices from the factorization :math:`A = LU`, as computed by :meth:`dgbtrf`; row :math:`i` of the matrix was interchanged with row :math:`\mathrm{ipiv}[i-1]`.
**equed** : str, length 1
If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{equed}` need not be set.
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` must specify the form of the equilibration that was performed as follows:
if :math:`\mathrm{equed} = \texttt{'N'}`, no equilibration;
if :math:`\mathrm{equed} = \texttt{'R'}`, row equilibration, i.e., :math:`A` has been premultiplied by :math:`D_R`;
if :math:`\mathrm{equed} = \texttt{'C'}`, column equilibration, i.e., :math:`A` has been postmultiplied by :math:`D_C`;
if :math:`\mathrm{equed} = \texttt{'B'}`, both row and column equilibration, i.e., :math:`A` has been replaced by :math:`D_RAD_C`.
**r** : float, array-like, shape :math:`\left(\mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{r}` need not be set.
If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{r}` must contain the row scale factors for :math:`A`, :math:`D_R`; each element of :math:`\mathrm{r}` must be positive.
**c** : float, array-like, shape :math:`\left(\mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{c}` need not be set.
If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'C'}` or :math:`\texttt{'B'}`, :math:`\mathrm{c}` must contain the column scale factors for :math:`A`, :math:`D_C`; each element of :math:`\mathrm{c}` must be positive.
**b** : float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)`
The :math:`n\times r` right-hand side matrix :math:`B`.
**Returns**
**ab** : float, ndarray, shape :math:`\left(\mathrm{kl}+\mathrm{ku}+1, \mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'F'}` or :math:`\texttt{'N'}`, or if :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{ab}` is not modified.
If :math:`\mathrm{equed} \neq \texttt{'N'}` then, if no constraints are violated, :math:`A` is scaled as follows:
if :math:`\mathrm{equed} = \texttt{'R'}`, :math:`A = D_rA`;
if :math:`\mathrm{equed} = \texttt{'C'}`, :math:`A = AD_c`;
if :math:`\mathrm{equed} = \texttt{'B'}`, :math:`A = D_rAD_c`.
**afb** : float, ndarray, shape :math:`\left(2\times \mathrm{kl}+\mathrm{ku}+1, \mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{afb}` is unchanged from entry.
Otherwise, if no constraints are violated, then if :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{afb}` returns details of the :math:`LU` factorization of the band matrix :math:`A`, and if :math:`\mathrm{fact} = \texttt{'E'}`, :math:`\mathrm{afb}` returns details of the :math:`LU` factorization of the equilibrated band matrix :math:`A` (see the description of :math:`\mathrm{ab}` for the form of the equilibrated matrix).
**ipiv** : int, ndarray, shape :math:`\left(\mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{ipiv}` is unchanged from entry.
Otherwise, if no constraints are violated, :math:`\mathrm{ipiv}` contains the pivot indices that define the permutation matrix :math:`P`; at the :math:`i`\ th step row :math:`i` of the matrix was interchanged with row :math:`\mathrm{ipiv}[i-1]`. :math:`\mathrm{ipiv}[i-1] = i` indicates a row interchange was not required.
If :math:`\mathrm{fact} = \texttt{'N'}`, the pivot indices are those corresponding to the factorization :math:`A = LU` of the original matrix :math:`A`.
If :math:`\mathrm{fact} = \texttt{'E'}`, the pivot indices are those corresponding to the factorization of :math:`A = LU` of the equilibrated matrix :math:`A`.
**equed** : str, length 1
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` is unchanged from entry.
Otherwise, if no constraints are violated, :math:`\mathrm{equed}` specifies the form of equilibration that was performed as specified above.
**r** : float, ndarray, shape :math:`\left(\mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{r}` is unchanged from entry.
Otherwise, if no constraints are violated and :math:`\mathrm{equed} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{r}` contains the row scale factors for :math:`A`, :math:`D_R`, such that :math:`A` is multiplied on the left by :math:`D_R`; each element of :math:`\mathrm{r}` is positive.
**c** : float, ndarray, shape :math:`\left(\mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{c}` is unchanged from entry.
Otherwise, if no constraints are violated and :math:`\mathrm{equed} = \texttt{'C'}` or :math:`\texttt{'B'}`, :math:`\mathrm{c}` contains the row scale factors for :math:`A`, :math:`D_C`; each element of :math:`\mathrm{c}` is positive.
**b** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)`
If :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{b}` is not modified.
If :math:`\mathrm{trans} = \texttt{'N'}` and :math:`\mathrm{equed} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{b}` is overwritten by :math:`D_RB`.
If :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}` and :math:`\mathrm{equed} = \texttt{'C'}` or :math:`\texttt{'B'}`, :math:`\mathrm{b}` is overwritten by :math:`D_CB`.
**x** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)`
If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, the :math:`n\times r` solution matrix :math:`X` to the original system of equations. Note that the arrays :math:`A` and :math:`B` are modified on exit if :math:`\mathrm{equed} \neq \texttt{'N'}`, and the solution to the equilibrated system is :math:`D_C^{-1}X` if :math:`\mathrm{trans} = \texttt{'N'}` and :math:`\mathrm{equed} = \texttt{'C'}` or :math:`\texttt{'B'}`, or :math:`D_R^{-1}X` if :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}` and :math:`\mathrm{equed} = \texttt{'R'}` or :math:`\texttt{'B'}`.
**rcond** : float
If no constraints are violated, an estimate of the reciprocal condition number of the matrix :math:`A` (after equilibration if that is performed), computed as :math:`\mathrm{rcond} = 1.0/\left(\left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\right)`.
**ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)`
If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the forward error bound for each computed solution vector, such that :math:`\left\lVert \hat{x}_j-x_j\right\rVert_\infty/\left\lVert x_j\right\rVert_\infty\leq \mathrm{ferr}[j-1]` where :math:`\hat{x}_j` is the :math:`j`\ th column of the computed solution returned in the array :math:`\mathrm{x}` and :math:`x_j` is the corresponding column of the exact solution :math:`X`. The estimate is as reliable as the estimate for :math:`\mathrm{rcond}`, and is almost always a slight overestimate of the true error.
**berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)`
If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the component-wise relative backward error of each computed solution vector :math:`\hat{x}_j` (i.e., the smallest relative change in any element of :math:`A` or :math:`B` that makes :math:`\hat{x}_j` an exact solution).
**recip_growth_factor** : float
If no exception or warning is raised, the reciprocal pivot growth factor :math:`\left\lVert A\right\rVert /\left\lVert U\right\rVert`, where :math:`\left\lVert.\right\rVert` denotes the maximum absolute element norm. If :math:`\mathrm{recip\_growth\_factor}≪1`, the stability of the :math:`LU` factorization of (equilibrated) :math:`A` could be poor. This also means that the solution :math:`\mathrm{x}`, condition estimate :math:`\mathrm{rcond}`, and forward error bound :math:`\mathrm{ferr}` could be unreliable. If the factorization fails with :math:`\mathrm{errno}` in 1 ... :math:`\mathrm{n}`, then :math:`\mathrm{recip\_growth\_factor}` contains the reciprocal pivot growth factor for the leading :math:`\textit{errno}` columns of :math:`A`.
.. _f07bb-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{fact}`.
Constraint: :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\texttt{'N'}` or :math:`\texttt{'E'}`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\mathrm{trans}`.
Constraint: :math:`\mathrm{trans} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{n}`.
Constraint: :math:`\mathrm{n}\geq 0`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\mathrm{kl}`.
Constraint: :math:`\mathrm{kl}\geq 0`.
(`errno` :math:`-5`)
On entry, error in parameter :math:`\mathrm{ku}`.
Constraint: :math:`\mathrm{ku}\geq 0`.
(`errno` :math:`-6`)
On entry, error in parameter :math:`\mathrm{nrhs}`.
Constraint: :math:`\mathrm{nrhs}\geq 0`.
(`errno` :math:`-12`)
On entry, error in parameter :math:`\mathrm{equed}`.
Constraint: :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\texttt{'R'}`, :math:`\texttt{'C'}` or :math:`\texttt{'B'}`.
(`errno` :math:`-13`)
On entry, error in parameter :math:`\mathrm{r}`.
(`errno` :math:`-14`)
On entry, error in parameter :math:`\mathrm{c}`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq \mathrm{n}\right)`)
Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`U` is exactly singular, so the solution and error bounds could not be computed. :math:`\mathrm{rcond} = 0.0` is returned.
(`errno` :math:`\mathrm{n}+1`)
:math:`U` is nonsingular, but :math:`\mathrm{rcond}` is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of :math:`\mathrm{rcond}` would suggest.
.. _f07bb-py2-py-notes:
**Notes**
``dgbsvx`` performs the following steps:
(1) **Equilibration**
The linear system to be solved may be badly scaled.
However, the system can be equilibrated as a first stage by setting :math:`\mathrm{fact} = \texttt{'E'}`.
In this case, real scaling factors are computed and these factors then determine whether the system is to be equilibrated.
Equilibrated forms of the systems :math:`AX = B` and :math:`A^\mathrm{T}X = B` are
.. math::
\left(D_RAD_C\right)\left(D_C^{-1}X\right) = D_RB
and
.. math::
\left(D_RAD_C\right)^\mathrm{T}\left(D_R^{-1}X\right) = D_CB\text{,}
respectively, where :math:`D_R` and :math:`D_C` are diagonal matrices, with positive diagonal elements, formed from the computed scaling factors.
When equilibration is used, :math:`A` will be overwritten by :math:`D_RAD_C` and :math:`B` will be overwritten by :math:`D_RB` (or :math:`D_CB` when the solution of :math:`A^\mathrm{T}X = B` is sought).
(#) **Factorization**
The matrix :math:`A`, or its scaled form, is copied and factored using the :math:`LU` decomposition
.. math::
A = PLU\text{,}
where :math:`P` is a permutation matrix, :math:`L` is a unit lower triangular matrix, and :math:`U` is upper triangular.
This stage can be by-passed when a factored matrix (with scaled matrices and scaling factors) are supplied; for example, as provided by a previous call to ``dgbsvx`` with the same matrix :math:`A`.
(#) **Condition Number Estimation**
The :math:`LU` factorization of :math:`A` determines whether a solution to the linear system exists.
If some diagonal element of :math:`U` is zero, then :math:`U` is exactly singular, no solution exists and the function returns with a failure.
Otherwise the factorized form of :math:`A` is used to estimate the condition number of the matrix :math:`A`.
If the reciprocal of the condition number is less than machine precision then a warning code is returned on final exit.
(#) **Solution**
The (equilibrated) system is solved for :math:`X` (:math:`D_C^{-1}X` or :math:`D_R^{-1}X`) using the factored form of :math:`A` (:math:`D_RAD_C`).
(#) **Iterative Refinement**
Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for the computed solution.
(#) **Construct Solution Matrix** :math:`X`
If equilibration was used, the matrix :math:`X` is premultiplied by :math:`D_C` (if :math:`\mathrm{trans} = \texttt{'N'}`) or :math:`D_R` (if :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}`) so that it solves the original system before equilibration.
.. _f07bb-py2-py-references:
**References**
Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia
"""
raise NotImplementedError
[docs]def dgbtrf(m, kl, ku, ab):
r"""
``dgbtrf`` computes the :math:`LU` factorization of a real :math:`m\times n` band matrix.
.. _f07bd-py2-py-doc:
For full information please refer to the NAG Library document for f07bd
https://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07baf.html#fcomments>`__ for further details.
**Returns**
**ab** : float, ndarray, shape :math:`\left(2\times \mathrm{kl}+\mathrm{ku}+1, n\right)`
If :math:`\mathrm{errno}` >= 0, :math:`\mathrm{ab}` is overwritten by details of the factorization.
**ipiv** : int, ndarray, shape :math:`\left(\min\left(\mathrm{m},n\right)\right)`
The pivot indices that define the permutation matrix. At the :math:`\textit{i}`\ th step, if :math:`\mathrm{ipiv}[\textit{i}-1] > \textit{i}` then row :math:`\textit{i}` of the matrix :math:`A` was interchanged with row :math:`\mathrm{ipiv}[\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,\mathrm{min}\left(m, n\right)`. :math:`\mathrm{ipiv}[i-1]\leq i` indicates that, at the :math:`i`\ th step, a row interchange was not required.
.. _f07bd-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{m}`.
Constraint: :math:`\mathrm{m}\geq 0`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{kl}`.
Constraint: :math:`\mathrm{kl}\geq 0`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\mathrm{ku}`.
Constraint: :math:`\mathrm{ku}\geq 0`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`i > 0`)
Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`U` is exactly singular, and division by zero will occur if it is used to solve a system of equations.
.. _f07bd-py2-py-notes:
**Notes**
``dgbtrf`` forms the :math:`LU` factorization of a real :math:`m\times n` band matrix :math:`A` using partial pivoting, with row interchanges.
Usually :math:`m = n`, and then, if :math:`A` has :math:`k_l` nonzero subdiagonals and :math:`k_u` nonzero superdiagonals, the factorization has the form :math:`A = PLU`, where :math:`P` is a permutation matrix, :math:`L` is a lower triangular matrix with unit diagonal elements and at most :math:`k_l` nonzero elements in each column, and :math:`U` is an upper triangular band matrix with :math:`k_l+k_u` superdiagonals.
Note that :math:`L` is not a band matrix, but the nonzero elements of :math:`L` can be stored in the same space as the subdiagonal elements of :math:`A`. :math:`U` is a band matrix but with :math:`k_l` additional superdiagonals compared with :math:`A`.
These additional superdiagonals are created by the row interchanges.
.. _f07bd-py2-py-references:
**References**
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError
[docs]def dgbtrs(trans, kl, ku, ab, ipiv, b):
r"""
``dgbtrs`` solves a real band system of linear equations with multiple right-hand sides,
.. math::
AX = B\quad \text{ or }\quad A^\mathrm{T}X = B\text{,}
where :math:`A` has been factorized by :meth:`dgbtrf`.
.. _f07be-py2-py-doc:
For full information please refer to the NAG Library document for f07be
https://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07baf.html#fcomments>`__ for further details.
**Returns**
**r** : float, ndarray, shape :math:`\left(\mathrm{m}\right)`
If no exception or warning is raised or :math:`\mathrm{errno}` > :math:`\mathrm{m}`, :math:`\mathrm{r}` contains the row scale factors, the diagonal elements of :math:`D_R`. The elements of :math:`\mathrm{r}` will be positive.
**c** : float, ndarray, shape :math:`\left(n\right)`
If no exception or warning is raised, :math:`\mathrm{c}` contains the column scale factors, the diagonal elements of :math:`D_C`. The elements of :math:`\mathrm{c}` will be positive.
**rowcnd** : float
If no exception or warning is raised or :math:`\mathrm{errno}` > :math:`\mathrm{m}`, :math:`\mathrm{rowcnd}` contains the ratio of the smallest value of :math:`\mathrm{r}[i-1]` to the largest value of :math:`\mathrm{r}[i-1]`. If :math:`\mathrm{rowcnd}\geq 0.1` and :math:`\mathrm{amax}` is neither too large nor too small, it is not worth scaling by :math:`D_R`.
**colcnd** : float
If no exception or warning is raised, :math:`\mathrm{colcnd}` contains the ratio of the smallest value of :math:`\mathrm{c}[i-1]` to the largest value of :math:`\mathrm{c}[i-1]`.
If :math:`\mathrm{colcnd}\geq 0.1`, it is not worth scaling by :math:`D_C`.
**amax** : float
:math:`\mathrm{max}\left\lvert a_{{ij}}\right\rvert`. If :math:`\mathrm{amax}` is very close to overflow or underflow, the matrix :math:`A` should be scaled.
.. _f07bf-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{m}`.
Constraint: :math:`\mathrm{m}\geq 0`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{kl}`.
Constraint: :math:`\mathrm{kl}\geq 0`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\mathrm{ku}`.
Constraint: :math:`\mathrm{ku}\geq 0`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq \mathrm{m}\right)`)
Row :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is exactly zero.
(`errno` :math:`i > \mathrm{m}`)
Column :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is exactly zero.
.. _f07bf-py2-py-notes:
**Notes**
``dgbequ`` computes the diagonal scaling matrices.
The diagonal scaling matrices are chosen to try to make the elements of largest absolute value in each row and column of the matrix :math:`B` given by
.. math::
B = D_RAD_C
have absolute value :math:`1`.
The diagonal elements of :math:`D_R` and :math:`D_C` are restricted to lie in the safe range :math:`\left(\delta, {1/\delta }\right)`, where :math:`\delta` is the value returned by function :meth:`machine.real_safe <naginterfaces.library.machine.real_safe>`.
Use of these scaling factors is not guaranteed to reduce the condition number of :math:`A` but works well in practice.
"""
raise NotImplementedError
[docs]def dgbcon(norm, kl, ku, ab, ipiv, anorm):
r"""
``dgbcon`` estimates the condition number of a real band matrix :math:`A`, where :math:`A` has been factorized by :meth:`dgbtrf`.
.. _f07bg-py2-py-doc:
For full information please refer to the NAG Library document for f07bg
https://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07bnf.html#fcomments>`__ for further details.
**b** : complex, array-like, shape :math:`\left(n, \textit{nrhs}\right)`
The :math:`n\times r` right-hand side matrix :math:`B`.
**Returns**
**ab** : complex, ndarray, shape :math:`\left(2\times \mathrm{kl}+\mathrm{ku}+1, n\right)`
If :math:`\mathrm{errno}` >= 0, :math:`\mathrm{ab}` is overwritten by details of the factorization.
**ipiv** : int, ndarray, shape :math:`\left(n\right)`
If no constraints are violated, the pivot indices that define the permutation matrix :math:`P`; at the :math:`i`\ th step row :math:`i` of the matrix was interchanged with row :math:`\mathrm{ipiv}[i-1]`. :math:`\mathrm{ipiv}[i-1] = i` indicates a row interchange was not required.
**b** : complex, ndarray, shape :math:`\left(n, \textit{nrhs}\right)`
If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`.
.. _f07bn-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\mathrm{kl}`.
Constraint: :math:`\mathrm{kl}\geq 0`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{ku}`.
Constraint: :math:`\mathrm{ku}\geq 0`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\textit{nrhs}`.
Constraint: :math:`\textit{nrhs}\geq 0`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`i > 0`)
Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`U` is exactly singular, so the solution could not be computed.
.. _f07bn-py2-py-notes:
**Notes**
``zgbsv`` uses the :math:`LU` decomposition with partial pivoting and row interchanges to factor :math:`A` as :math:`A = PLU`, where :math:`P` is a permutation matrix, :math:`L` is a product of permutation and unit lower triangular matrices with :math:`k_l` subdiagonals, and :math:`U` is upper triangular with :math:`\left(k_l+k_u\right)` superdiagonals.
The factored form of :math:`A` is then used to solve the system of equations :math:`AX = B`.
.. _f07bn-py2-py-references:
**References**
Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError
[docs]def zgbsvx(fact, trans, kl, ku, nrhs, ab, afb, ipiv, equed, r, c, b):
r"""
``zgbsvx`` uses the :math:`LU` factorization to compute the solution to a complex system of linear equations
.. math::
AX = B\text{, }\quad A^\mathrm{T}X = B\quad \text{ or }\quad A^\mathrm{H}X = B\text{,}
where :math:`A` is an :math:`n\times n` band matrix with :math:`k_l` subdiagonals and :math:`k_u` superdiagonals, and :math:`X` and :math:`B` are :math:`n\times r` matrices.
Error bounds on the solution and a condition estimate are also provided.
.. _f07bp-py2-py-doc:
For full information please refer to the NAG Library document for f07bp
https://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07bpf.html#fcomments>`__ for further details.
If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} \neq \texttt{'N'}`, :math:`A` must have been equilibrated by the scaling factors in :math:`\mathrm{r}` and/or :math:`\mathrm{c}`.
**afb** : complex, array-like, shape :math:`\left(2\times \mathrm{kl}+\mathrm{ku}+1, n\right)`
If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{afb}` need not be set.
If :math:`\mathrm{fact} = \texttt{'F'}`, details of the :math:`LU` factorization of the :math:`n\times n` band matrix :math:`A`, as computed by :meth:`zgbtrf`.
If :math:`\mathrm{equed} \neq \texttt{'N'}`, :math:`\mathrm{afb}` is the factorized form of the equilibrated matrix :math:`A`.
**ipiv** : int, array-like, shape :math:`\left(n\right)`
If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{ipiv}` need not be set.
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{ipiv}` contains the pivot indices from the factorization :math:`A = LU`, as computed by :meth:`dgbtrf`; row :math:`i` of the matrix was interchanged with row :math:`\mathrm{ipiv}[i-1]`.
**equed** : str, length 1
If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{equed}` need not be set.
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` must specify the form of the equilibration that was performed as follows:
if :math:`\mathrm{equed} = \texttt{'N'}`, no equilibration;
if :math:`\mathrm{equed} = \texttt{'R'}`, row equilibration, i.e., :math:`A` has been premultiplied by :math:`D_R`;
if :math:`\mathrm{equed} = \texttt{'C'}`, column equilibration, i.e., :math:`A` has been postmultiplied by :math:`D_C`;
if :math:`\mathrm{equed} = \texttt{'B'}`, both row and column equilibration, i.e., :math:`A` has been replaced by :math:`D_RAD_C`.
**r** : float, array-like, shape :math:`\left(n\right)`
If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{r}` need not be set.
If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{r}` must contain the row scale factors for :math:`A`, :math:`D_R`; each element of :math:`\mathrm{r}` must be positive.
**c** : float, array-like, shape :math:`\left(n\right)`
If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{c}` need not be set.
If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'C'}` or :math:`\texttt{'B'}`, :math:`\mathrm{c}` must contain the column scale factors for :math:`A`, :math:`D_C`; each element of :math:`\mathrm{c}` must be positive.
**b** : complex, array-like, shape :math:`\left(n, \mathrm{nrhs}\right)`
The :math:`n\times r` right-hand side matrix :math:`B`.
**Returns**
**ab** : complex, ndarray, shape :math:`\left(\mathrm{kl}+\mathrm{ku}+1, n\right)`
If :math:`\mathrm{fact} = \texttt{'F'}` or :math:`\texttt{'N'}`, or if :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{ab}` is not modified.
If :math:`\mathrm{equed} \neq \texttt{'N'}` then, if no constraints are violated, :math:`A` is scaled as follows:
if :math:`\mathrm{equed} = \texttt{'R'}`, :math:`A = D_rA`;
if :math:`\mathrm{equed} = \texttt{'C'}`, :math:`A = AD_c`;
if :math:`\mathrm{equed} = \texttt{'B'}`, :math:`A = D_rAD_c`.
**afb** : complex, ndarray, shape :math:`\left(2\times \mathrm{kl}+\mathrm{ku}+1, n\right)`
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{afb}` is unchanged from entry.
Otherwise, if no constraints are violated, then if :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{afb}` returns details of the :math:`LU` factorization of the band matrix :math:`A`, and if :math:`\mathrm{fact} = \texttt{'E'}`, :math:`\mathrm{afb}` returns details of the :math:`LU` factorization of the equilibrated band matrix :math:`A` (see the description of :math:`\mathrm{ab}` for the form of the equilibrated matrix).
**ipiv** : int, ndarray, shape :math:`\left(n\right)`
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{ipiv}` is unchanged from entry.
Otherwise, if no constraints are violated, :math:`\mathrm{ipiv}` contains the pivot indices that define the permutation matrix :math:`P`; at the :math:`i`\ th step row :math:`i` of the matrix was interchanged with row :math:`\mathrm{ipiv}[i-1]`. :math:`\mathrm{ipiv}[i-1] = i` indicates a row interchange was not required.
If :math:`\mathrm{fact} = \texttt{'N'}`, the pivot indices are those corresponding to the factorization :math:`A = LU` of the original matrix :math:`A`.
If :math:`\mathrm{fact} = \texttt{'E'}`, the pivot indices are those corresponding to the factorization of :math:`A = LU` of the equilibrated matrix :math:`A`.
**equed** : str, length 1
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` is unchanged from entry.
Otherwise, if no constraints are violated, :math:`\mathrm{equed}` specifies the form of equilibration that was performed as specified above.
**r** : float, ndarray, shape :math:`\left(n\right)`
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{r}` is unchanged from entry.
Otherwise, if no constraints are violated and :math:`\mathrm{equed} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{r}` contains the row scale factors for :math:`A`, :math:`D_R`, such that :math:`A` is multiplied on the left by :math:`D_R`; each element of :math:`\mathrm{r}` is positive.
**c** : float, ndarray, shape :math:`\left(n\right)`
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{c}` is unchanged from entry.
Otherwise, if no constraints are violated and :math:`\mathrm{equed} = \texttt{'C'}` or :math:`\texttt{'B'}`, :math:`\mathrm{c}` contains the row scale factors for :math:`A`, :math:`D_C`; each element of :math:`\mathrm{c}` is positive.
**b** : complex, ndarray, shape :math:`\left(n, \mathrm{nrhs}\right)`
If :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{b}` is not modified.
If :math:`\mathrm{trans} = \texttt{'N'}` and :math:`\mathrm{equed} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{b}` is overwritten by :math:`D_RB`.
If :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}` and :math:`\mathrm{equed} = \texttt{'C'}` or :math:`\texttt{'B'}`, :math:`\mathrm{b}` is overwritten by :math:`D_CB`.
**x** : complex, ndarray, shape :math:`\left(n, \mathrm{nrhs}\right)`
If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, the :math:`n\times r` solution matrix :math:`X` to the original system of equations. Note that the arrays :math:`A` and :math:`B` are modified on exit if :math:`\mathrm{equed} \neq \texttt{'N'}`, and the solution to the equilibrated system is :math:`D_C^{-1}X` if :math:`\mathrm{trans} = \texttt{'N'}` and :math:`\mathrm{equed} = \texttt{'C'}` or :math:`\texttt{'B'}`, or :math:`D_R^{-1}X` if :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}` and :math:`\mathrm{equed} = \texttt{'R'}` or :math:`\texttt{'B'}`.
**rcond** : float
If no constraints are violated, an estimate of the reciprocal condition number of the matrix :math:`A` (after equilibration if that is performed), computed as :math:`\mathrm{rcond} = 1.0/\left(\left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\right)`.
**ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)`
If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the forward error bound for each computed solution vector, such that :math:`\left\lVert \hat{x}_j-x_j\right\rVert_\infty/\left\lVert x_j\right\rVert_\infty\leq \mathrm{ferr}[j-1]` where :math:`\hat{x}_j` is the :math:`j`\ th column of the computed solution returned in the array :math:`\mathrm{x}` and :math:`x_j` is the corresponding column of the exact solution :math:`X`. The estimate is as reliable as the estimate for :math:`\mathrm{rcond}`, and is almost always a slight overestimate of the true error.
**berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)`
If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the component-wise relative backward error of each computed solution vector :math:`\hat{x}_j` (i.e., the smallest relative change in any element of :math:`A` or :math:`B` that makes :math:`\hat{x}_j` an exact solution).
**recip_growth_factor** : float
If no exception or warning is raised, the reciprocal pivot growth factor :math:`\left\lVert A\right\rVert /\left\lVert U\right\rVert`, where :math:`\left\lVert.\right\rVert` denotes the maximum absolute element norm. If :math:`\mathrm{recip\_growth\_factor}≪1`, the stability of the :math:`LU` factorization of (equilibrated) :math:`A` could be poor. This also means that the solution :math:`\mathrm{x}`, condition estimate :math:`\mathrm{rcond}`, and forward error bound :math:`\mathrm{ferr}` could be unreliable. If the factorization fails with :math:`\mathrm{errno}` in 1 ... :math:`\mathrm{n}`, then :math:`\mathrm{recip\_growth\_factor}` contains the reciprocal pivot growth factor for the leading :math:`\textit{errno}` columns of :math:`A`.
.. _f07bp-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{fact}`.
Constraint: :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\texttt{'N'}` or :math:`\texttt{'E'}`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\mathrm{trans}`.
Constraint: :math:`\mathrm{trans} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\mathrm{kl}`.
Constraint: :math:`\mathrm{kl}\geq 0`.
(`errno` :math:`-5`)
On entry, error in parameter :math:`\mathrm{ku}`.
Constraint: :math:`\mathrm{ku}\geq 0`.
(`errno` :math:`-6`)
On entry, error in parameter :math:`\mathrm{nrhs}`.
Constraint: :math:`\mathrm{nrhs}\geq 0`.
(`errno` :math:`-12`)
On entry, error in parameter :math:`\mathrm{equed}`.
Constraint: :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\texttt{'R'}`, :math:`\texttt{'C'}` or :math:`\texttt{'B'}`.
(`errno` :math:`-13`)
On entry, error in parameter :math:`\mathrm{r}`.
(`errno` :math:`-14`)
On entry, error in parameter :math:`\mathrm{c}`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq n\right)`)
Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`U` is exactly singular, so the solution and error bounds could not be computed. :math:`\mathrm{rcond} = 0.0` is returned.
(`errno` :math:`n+1`)
:math:`U` is nonsingular, but :math:`\mathrm{rcond}` is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of :math:`\mathrm{rcond}` would suggest.
.. _f07bp-py2-py-notes:
**Notes**
``zgbsvx`` performs the following steps:
(1) **Equilibration**
The linear system to be solved may be badly scaled.
However, the system can be equilibrated as a first stage by setting :math:`\mathrm{fact} = \texttt{'E'}`.
In this case, real scaling factors are computed and these factors then determine whether the system is to be equilibrated.
Equilibrated forms of the systems :math:`AX = B`, :math:`A^\mathrm{T}X = B` and :math:`A^\mathrm{H}X = B` are
.. math::
\left(D_RAD_C\right)\left(D_C^{-1}X\right) = D_RB\text{,}
.. math::
\left(D_RAD_C\right)^\mathrm{T}\left(D_R^{-1}X\right) = D_CB\text{,}
and
.. math::
\left(D_RAD_C\right)^\mathrm{H}\left(D_R^{-1}X\right) = D_CB\text{,}
respectively, where :math:`D_R` and :math:`D_C` are diagonal matrices, with positive diagonal elements, formed from the computed scaling factors.
When equilibration is used, :math:`A` will be overwritten by :math:`D_RAD_C` and :math:`B` will be overwritten by :math:`D_RB` (or :math:`D_CB` when the solution of :math:`A^\mathrm{T}X = B` or :math:`A^\mathrm{H}X = B` is sought).
(#) **Factorization**
The matrix :math:`A`, or its scaled form, is copied and factored using the :math:`LU` decomposition
.. math::
A = PLU\text{,}
where :math:`P` is a permutation matrix, :math:`L` is a unit lower triangular matrix, and :math:`U` is upper triangular.
This stage can be by-passed when a factored matrix (with scaled matrices and scaling factors) are supplied; for example, as provided by a previous call to ``zgbsvx`` with the same matrix :math:`A`.
(#) **Condition Number Estimation**
The :math:`LU` factorization of :math:`A` determines whether a solution to the linear system exists.
If some diagonal element of :math:`U` is zero, then :math:`U` is exactly singular, no solution exists and the function returns with a failure.
Otherwise the factorized form of :math:`A` is used to estimate the condition number of the matrix :math:`A`.
If the reciprocal of the condition number is less than machine precision then a warning code is returned on final exit.
(#) **Solution**
The (equilibrated) system is solved for :math:`X` (:math:`D_C^{-1}X` or :math:`D_R^{-1}X`) using the factored form of :math:`A` (:math:`D_RAD_C`).
(#) **Iterative Refinement**
Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for the computed solution.
(#) **Construct Solution Matrix** :math:`X`
If equilibration was used, the matrix :math:`X` is premultiplied by :math:`D_C` (if :math:`\mathrm{trans} = \texttt{'N'}`) or :math:`D_R` (if :math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}`) so that it solves the original system before equilibration.
.. _f07bp-py2-py-references:
**References**
Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia
"""
raise NotImplementedError
[docs]def zgbtrf(m, kl, ku, ab):
r"""
``zgbtrf`` computes the :math:`LU` factorization of a complex :math:`m\times n` band matrix.
.. _f07br-py2-py-doc:
For full information please refer to the NAG Library document for f07br
https://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07bnf.html#fcomments>`__ for further details.
**Returns**
**ab** : complex, ndarray, shape :math:`\left(2\times \mathrm{kl}+\mathrm{ku}+1, n\right)`
If :math:`\mathrm{errno}` >= 0, :math:`\mathrm{ab}` is overwritten by details of the factorization.
**ipiv** : int, ndarray, shape :math:`\left(\min\left(\mathrm{m},n\right)\right)`
The pivot indices that define the permutation matrix. At the :math:`\textit{i}`\ th step, if :math:`\mathrm{ipiv}[\textit{i}-1] > \textit{i}` then row :math:`\textit{i}` of the matrix :math:`A` was interchanged with row :math:`\mathrm{ipiv}[\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,\mathrm{min}\left(m, n\right)`. :math:`\mathrm{ipiv}[i-1]\leq i` indicates that, at the :math:`i`\ th step, a row interchange was not required.
.. _f07br-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{m}`.
Constraint: :math:`\mathrm{m}\geq 0`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{kl}`.
Constraint: :math:`\mathrm{kl}\geq 0`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\mathrm{ku}`.
Constraint: :math:`\mathrm{ku}\geq 0`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`i > 0`)
Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the factor :math:`U` is exactly singular, and division by zero will occur if it is used to solve a system of equations.
.. _f07br-py2-py-notes:
**Notes**
``zgbtrf`` forms the :math:`LU` factorization of a complex :math:`m\times n` band matrix :math:`A` using partial pivoting, with row interchanges.
Usually :math:`m = n`, and then, if :math:`A` has :math:`k_l` nonzero subdiagonals and :math:`k_u` nonzero superdiagonals, the factorization has the form :math:`A = PLU`, where :math:`P` is a permutation matrix, :math:`L` is a lower triangular matrix with unit diagonal elements and at most :math:`k_l` nonzero elements in each column, and :math:`U` is an upper triangular band matrix with :math:`k_l+k_u` superdiagonals.
Note that :math:`L` is not a band matrix, but the nonzero elements of :math:`L` can be stored in the same space as the subdiagonal elements of :math:`A`. :math:`U` is a band matrix but with :math:`k_l` additional superdiagonals compared with :math:`A`.
These additional superdiagonals are created by the row interchanges.
.. _f07br-py2-py-references:
**References**
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError
[docs]def zgbtrs(trans, kl, ku, ab, ipiv, b):
r"""
``zgbtrs`` solves a complex band system of linear equations with multiple right-hand sides,
.. math::
AX = B\text{, }\quad A^\mathrm{T}X = B\quad \text{ or }\quad A^\mathrm{H}X = B\text{,}
where :math:`A` has been factorized by :meth:`zgbtrf`.
.. _f07bs-py2-py-doc:
For full information please refer to the NAG Library document for f07bs
https://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07bnf.html#fcomments>`__ for further details.
**Returns**
**r** : float, ndarray, shape :math:`\left(\mathrm{m}\right)`
If no exception or warning is raised or :math:`\mathrm{errno}` > :math:`\mathrm{m}`, :math:`\mathrm{r}` contains the row scale factors, the diagonal elements of :math:`D_R`. The elements of :math:`\mathrm{r}` will be positive.
**c** : float, ndarray, shape :math:`\left(n\right)`
If no exception or warning is raised, :math:`\mathrm{c}` contains the column scale factors, the diagonal elements of :math:`D_C`. The elements of :math:`\mathrm{c}` will be positive.
**rowcnd** : float
If no exception or warning is raised or :math:`\mathrm{errno}` > :math:`\mathrm{m}`, :math:`\mathrm{rowcnd}` contains the ratio of the smallest value of :math:`\mathrm{r}[i-1]` to the largest value of :math:`\mathrm{r}[i-1]`. If :math:`\mathrm{rowcnd}\geq 0.1` and :math:`\mathrm{amax}` is neither too large nor too small, it is not worth scaling by :math:`D_R`.
**colcnd** : float
If no exception or warning is raised, :math:`\mathrm{colcnd}` contains the ratio of the smallest value of :math:`\mathrm{c}[i-1]` to the largest value of :math:`\mathrm{c}[i-1]`.
If :math:`\mathrm{colcnd}\geq 0.1`, it is not worth scaling by :math:`D_C`.
**amax** : float
:math:`\mathrm{max}\left\lvert a_{{ij}}\right\rvert`. If :math:`\mathrm{amax}` is very close to overflow or underflow, the matrix :math:`A` should be scaled.
.. _f07bt-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{m}`.
Constraint: :math:`\mathrm{m}\geq 0`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{kl}`.
Constraint: :math:`\mathrm{kl}\geq 0`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\mathrm{ku}`.
Constraint: :math:`\mathrm{ku}\geq 0`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq \mathrm{m}\right)`)
Row :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is exactly zero.
(`errno` :math:`i > \mathrm{m}`)
Column :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is exactly zero.
.. _f07bt-py2-py-notes:
**Notes**
``zgbequ`` computes the diagonal scaling matrices.
The diagonal scaling matrices are chosen to try to make the elements of largest absolute value in each row and column of the matrix :math:`B` given by
.. math::
B = D_RAD_C
have absolute value :math:`1`.
The diagonal elements of :math:`D_R` and :math:`D_C` are restricted to lie in the safe range :math:`\left(\delta, {1/\delta }\right)`, where :math:`\delta` is the value returned by function :meth:`machine.real_safe <naginterfaces.library.machine.real_safe>`.
Use of these scaling factors is not guaranteed to reduce the condition number of :math:`A` but works well in practice.
"""
raise NotImplementedError
[docs]def zgbcon(norm, kl, ku, ab, ipiv, anorm):
r"""
``zgbcon`` estimates the condition number of a complex band matrix :math:`A`, where :math:`A` has been factorized by :meth:`zgbtrf`.
.. _f07bu-py2-py-doc:
For full information please refer to the NAG Library document for f07bu
https://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07caf.html
.. _f07ca-py2-py-parameters:
**Parameters**
**dl** : float, array-like, shape :math:`\left(n-1\right)`
Must contain the :math:`\left(n-1\right)` subdiagonal elements of the matrix :math:`A`.
**d** : float, array-like, shape :math:`\left(n\right)`
Must contain the :math:`n` diagonal elements of the matrix :math:`A`.
**du** : float, array-like, shape :math:`\left(n-1\right)`
Must contain the :math:`\left(n-1\right)` superdiagonal elements of the matrix :math:`A`.
**b** : float, array-like, shape :math:`\left(n, \textit{nrhs}\right)`
The :math:`n\times r` right-hand side matrix :math:`B`.
**Returns**
**dl** : float, ndarray, shape :math:`\left(n-1\right)`
If no constraints are violated, :math:`\mathrm{dl}` is overwritten by the (:math:`n-2`) elements of the second superdiagonal of the upper triangular matrix :math:`U` from the :math:`LU` factorization of :math:`A`, in :math:`\mathrm{dl}[0],\mathrm{dl}[1],\ldots,\mathrm{dl}[n-3]`.
**d** : float, ndarray, shape :math:`\left(n\right)`
If no constraints are violated, :math:`\mathrm{d}` is overwritten by the :math:`n` diagonal elements of the upper triangular matrix :math:`U` from the :math:`LU` factorization of :math:`A`.
**du** : float, ndarray, shape :math:`\left(n-1\right)`
If no constraints are violated, :math:`\mathrm{du}` is overwritten by the :math:`\left(n-1\right)` elements of the first superdiagonal of :math:`U`.
**b** : float, ndarray, shape :math:`\left(n, \textit{nrhs}\right)`
If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`.
.. _f07ca-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\textit{nrhs}`.
Constraint: :math:`\textit{nrhs}\geq 0`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`i > 0`)
Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero, and the solution has not been computed. The factorization has not been completed unless :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
.. _f07ca-py2-py-notes:
**Notes**
``dgtsv`` uses Gaussian elimination with partial pivoting and row interchanges to solve the equations :math:`AX = B`.
The matrix :math:`A` is factorized as :math:`A = PLU`, where :math:`P` is a permutation matrix, :math:`L` is unit lower triangular with at most one nonzero subdiagonal element per column, and :math:`U` is an upper triangular band matrix, with two superdiagonals.
Note that equations :math:`A^\mathrm{T}X = B` may be solved by interchanging the order of the arguments :math:`\mathrm{du}` and :math:`\mathrm{dl}`.
.. _f07ca-py2-py-references:
**References**
Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug
"""
raise NotImplementedError
[docs]def dgtsvx(fact, trans, n, nrhs, dl, d, du, dlf, df, duf, du2, ipiv, b):
r"""
``dgtsvx`` uses the :math:`LU` factorization to compute the solution to a real system of linear equations
.. math::
AX = B\quad \text{ or }\quad A^\mathrm{T}X = B\text{,}
where :math:`A` is a tridiagonal matrix of order :math:`n` and :math:`X` and :math:`B` are :math:`n\times r` matrices.
Error bounds on the solution and a condition estimate are also provided.
.. _f07cb-py2-py-doc:
For full information please refer to the NAG Library document for f07cb
https://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07cnf.html
.. _f07cn-py2-py-parameters:
**Parameters**
**dl** : complex, array-like, shape :math:`\left(n-1\right)`
Must contain the :math:`\left(n-1\right)` subdiagonal elements of the matrix :math:`A`.
**d** : complex, array-like, shape :math:`\left(n\right)`
Must contain the :math:`n` diagonal elements of the matrix :math:`A`.
**du** : complex, array-like, shape :math:`\left(n-1\right)`
Must contain the :math:`\left(n-1\right)` superdiagonal elements of the matrix :math:`A`.
**b** : complex, array-like, shape :math:`\left(n, \textit{nrhs}\right)`
The :math:`n\times r` right-hand side matrix :math:`B`.
**Returns**
**dl** : complex, ndarray, shape :math:`\left(n-1\right)`
If no constraints are violated, :math:`\mathrm{dl}` is overwritten by the (:math:`n-2`) elements of the second superdiagonal of the upper triangular matrix :math:`U` from the :math:`LU` factorization of :math:`A`, in :math:`\mathrm{dl}[0],\mathrm{dl}[1],\ldots,\mathrm{dl}[n-3]`.
**d** : complex, ndarray, shape :math:`\left(n\right)`
If no constraints are violated, :math:`\mathrm{d}` is overwritten by the :math:`n` diagonal elements of the upper triangular matrix :math:`U` from the :math:`LU` factorization of :math:`A`.
**du** : complex, ndarray, shape :math:`\left(n-1\right)`
If no constraints are violated, :math:`\mathrm{du}` is overwritten by the :math:`\left(n-1\right)` elements of the first superdiagonal of :math:`U`.
**b** : complex, ndarray, shape :math:`\left(n, \textit{nrhs}\right)`
If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`.
.. _f07cn-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\textit{nrhs}`.
Constraint: :math:`\textit{nrhs}\geq 0`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`i > 0`)
Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero, and the solution has not been computed. The factorization has not been completed unless :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
.. _f07cn-py2-py-notes:
**Notes**
``zgtsv`` uses Gaussian elimination with partial pivoting and row interchanges to solve the equations :math:`AX = B`.
The matrix :math:`A` is factorized as :math:`A = PLU`, where :math:`P` is a permutation matrix, :math:`L` is unit lower triangular with at most one nonzero subdiagonal element per column, and :math:`U` is an upper triangular band matrix, with two superdiagonals.
Note that the equations :math:`A^\mathrm{T}X = B` may be solved by interchanging the order of the arguments :math:`\mathrm{du}` and :math:`\mathrm{dl}`.
.. _f07cn-py2-py-references:
**References**
Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug
"""
raise NotImplementedError
[docs]def zgtsvx(fact, trans, n, nrhs, dl, d, du, dlf, df, duf, du2, ipiv, b):
r"""
``zgtsvx`` uses the :math:`LU` factorization to compute the solution to a complex system of linear equations
.. math::
AX = B\text{, }\quad A^\mathrm{T}X = B\quad \text{ or }\quad A^\mathrm{H}X = B\text{,}
where :math:`A` is a tridiagonal matrix of order :math:`n` and :math:`X` and :math:`B` are :math:`n\times r` matrices.
Error bounds on the solution and a condition estimate are also provided.
.. _f07cp-py2-py-doc:
For full information please refer to the NAG Library document for f07cp
https://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07faf.html
.. _f07fa-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored.
If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored.
**a** : float, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` symmetric matrix :math:`A`.
**b** : float, array-like, shape :math:`\left(n, \textit{nrhs}\right)`
The :math:`n\times r` right-hand side matrix :math:`B`.
**Returns**
**a** : float, ndarray, shape :math:`\left(n, n\right)`
If no exception or warning is raised, the factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{T}U` or :math:`A = LL^\mathrm{T}`.
**b** : float, ndarray, shape :math:`\left(n, \textit{nrhs}\right)`
If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`.
.. _f07fa-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{uplo}`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\textit{nrhs}`.
Constraint: :math:`\textit{nrhs}\geq 0`.
(`errno` :math:`i > 0`)
The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is not positive definite, so the factorization could not be completed, and the solution has not been computed.
.. _f07fa-py2-py-notes:
**Notes**
``dposv`` uses the Cholesky decomposition to factor :math:`A` as :math:`A = U^\mathrm{T}U` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LL^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` is an upper triangular matrix and :math:`L` is a lower triangular matrix.
The factored form of :math:`A` is then used to solve the system of equations :math:`AX = B`.
.. _f07fa-py2-py-references:
**References**
Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError
[docs]def dposvx(fact, uplo, n, nrhs, a, af, equed, s, b):
r"""
``dposvx`` uses the Cholesky factorization
.. math::
A = U^\mathrm{T}U\quad \text{ or }\quad A = LL^\mathrm{T}
to compute the solution to a real system of linear equations
.. math::
AX = B\text{,}
where :math:`A` is an :math:`n\times n` symmetric positive definite matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices.
Error bounds on the solution and a condition estimate are also provided.
.. _f07fb-py2-py-doc:
For full information please refer to the NAG Library document for f07fb
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07fbf.html
.. _f07fb-py2-py-parameters:
**Parameters**
**fact** : str, length 1
Specifies whether or not the factorized form of the matrix :math:`A` is supplied on entry, and if not, whether the matrix :math:`A` should be equilibrated before it is factorized.
:math:`\mathrm{fact} = \texttt{'F'}`
:math:`\mathrm{af}` contains the factorized form of :math:`A`. If :math:`\mathrm{equed} = \texttt{'Y'}`, the matrix :math:`A` has been equilibrated with scaling factors given by :math:`\mathrm{s}`. :math:`\mathrm{a}` and :math:`\mathrm{af}` will not be modified.
:math:`\mathrm{fact} = \texttt{'N'}`
The matrix :math:`A` will be copied to :math:`\mathrm{af}` and factorized.
:math:`\mathrm{fact} = \texttt{'E'}`
The matrix :math:`A` will be equilibrated if necessary, then copied to :math:`\mathrm{af}` and factorized.
**uplo** : str, length 1
If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored.
If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored.
**n** : int
:math:`n`, the number of linear equations, i.e., the order of the matrix :math:`A`.
**nrhs** : int
:math:`r`, the number of right-hand sides, i.e., the number of columns of the matrix :math:`B`.
**a** : float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)`
The :math:`n\times n` symmetric matrix :math:`A`.
If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{a}` must have been equilibrated by the scaling factor in :math:`\mathrm{s}` as :math:`D_SAD_S`.
**af** : float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{af}` contains the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{T}U` or :math:`A = LL^\mathrm{T}`, in the same storage format as :math:`\mathrm{a}`. If :math:`\mathrm{equed} \neq \texttt{'N'}`, :math:`\mathrm{af}` is the factorized form of the equilibrated matrix :math:`D_SAD_S`.
**equed** : str, length 1
If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{equed}` need not be set.
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` must specify the form of the equilibration that was performed as follows:
if :math:`\mathrm{equed} = \texttt{'N'}`, no equilibration;
if :math:`\mathrm{equed} = \texttt{'Y'}`, equilibration was performed, i.e., :math:`A` has been replaced by :math:`D_SAD_S`.
**s** : float, array-like, shape :math:`\left(\mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{s}` need not be set.
If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{s}` must contain the scale factors, :math:`D_S`, for :math:`A`; each element of :math:`\mathrm{s}` must be positive.
**b** : float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)`
The :math:`n\times r` right-hand side matrix :math:`B`.
**Returns**
**a** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'F'}` or :math:`\texttt{'N'}`, or if :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{a}` is not modified.
If :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{a}` is overwritten by :math:`D_SAD_S`.
**af** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{af}` returns the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{T}U` or :math:`A = LL^\mathrm{T}` of the original matrix :math:`A`.
If :math:`\mathrm{fact} = \texttt{'E'}`, :math:`\mathrm{af}` returns the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{T}U` or :math:`A = LL^\mathrm{T}` of the equilibrated matrix :math:`A` (see the description of :math:`\mathrm{a}` for the form of the equilibrated matrix).
**equed** : str, length 1
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` is unchanged from entry.
Otherwise, if no constraints are violated, :math:`\mathrm{equed}` specifies the form of the equilibration that was performed as specified above.
**s** : float, ndarray, shape :math:`\left(\mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{s}` is unchanged from entry.
Otherwise, if no constraints are violated and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{s}` contains the scale factors, :math:`D_S`, for :math:`A`; each element of :math:`\mathrm{s}` is positive.
**b** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)`
If :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{b}` is not modified.
If :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{b}` is overwritten by :math:`D_SB`.
**x** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)`
If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, the :math:`n\times r` solution matrix :math:`X` to the original system of equations. Note that the arrays :math:`A` and :math:`B` are modified on exit if :math:`\mathrm{equed} = \texttt{'Y'}`, and the solution to the equilibrated system is :math:`D_S^{-1}X`.
**rcond** : float
If no constraints are violated, an estimate of the reciprocal condition number of the matrix :math:`A` (after equilibration if that is performed), computed as :math:`\mathrm{rcond} = 1.0/\left(\left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\right)`.
**ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)`
If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the forward error bound for each computed solution vector, such that :math:`\left\lVert \hat{x}_j-x_j\right\rVert_\infty/\left\lVert x_j\right\rVert_\infty\leq \mathrm{ferr}[j-1]` where :math:`\hat{x}_j` is the :math:`j`\ th column of the computed solution returned in the array :math:`\mathrm{x}` and :math:`x_j` is the corresponding column of the exact solution :math:`X`. The estimate is as reliable as the estimate for :math:`\mathrm{rcond}`, and is almost always a slight overestimate of the true error.
**berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)`
If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the component-wise relative backward error of each computed solution vector :math:`\hat{x}_j` (i.e., the smallest relative change in any element of :math:`A` or :math:`B` that makes :math:`\hat{x}_j` an exact solution).
.. _f07fb-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{fact}`.
Constraint: :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\texttt{'N'}` or :math:`\texttt{'E'}`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\mathrm{uplo}`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{n}`.
Constraint: :math:`\mathrm{n}\geq 0`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\mathrm{nrhs}`.
Constraint: :math:`\mathrm{nrhs}\geq 0`.
(`errno` :math:`-9`)
On entry, error in parameter :math:`\mathrm{equed}`.
Constraint: :math:`\mathrm{equed} = \texttt{'N'}` or :math:`\texttt{'Y'}`.
(`errno` :math:`-10`)
On entry, error in parameter :math:`\mathrm{s}`.
(`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq \mathrm{n}\right)`)
The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is not positive definite, so the factorization could not be completed, and the solution has not been computed. :math:`\mathrm{rcond} = 0.0` is returned.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`\mathrm{n}+1`)
:math:`U` (or :math:`L`) is nonsingular, but :math:`\mathrm{rcond}` is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of :math:`\mathrm{rcond}` would suggest.
.. _f07fb-py2-py-notes:
**Notes**
``dposvx`` performs the following steps:
(1) If :math:`\mathrm{fact} = \texttt{'E'}`, real diagonal scaling factors, :math:`D_S`, are computed to equilibrate the system:
.. math::
\left(D_SAD_S\right)\left(D_S^{-1}X\right) = D_SB\text{.}
Whether or not the system will be equilibrated depends on the scaling of the matrix :math:`A`, but if equilibration is used, :math:`A` is overwritten by :math:`D_SAD_S` and :math:`B\times D_SB`.
(#) If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, the Cholesky decomposition is used to factor the matrix :math:`A` (after equilibration if :math:`\mathrm{fact} = \texttt{'E'}`) as :math:`A = U^\mathrm{T}U` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LL^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` is an upper triangular matrix and :math:`L` is a lower triangular matrix.
(#) If the leading :math:`i\times i` principal minor of :math:`A` is not positive definite, then the function returns with :math:`\textit{errno} = i`. Otherwise, the factored form of :math:`A` is used to estimate the condition number of the matrix :math:`A`. If the reciprocal of the condition number is less than machine precision, :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1 is returned as a warning, but the function still goes on to solve for :math:`X` and compute error bounds as described below.
(#) The system of equations is solved for :math:`X` using the factored form of :math:`A`.
(#) Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for it.
(#) If equilibration was used, the matrix :math:`X` is premultiplied by :math:`D_S` so that it solves the original system before equilibration.
.. _f07fb-py2-py-references:
**References**
Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia
"""
raise NotImplementedError
[docs]def dsposv(uplo, n, nrhs, a, b):
r"""
``dsposv`` uses the Cholesky factorization
.. math::
A = U^\mathrm{T}U\quad \text{ or }\quad A = LL^\mathrm{T}
to compute the solution to a real system of linear equations
.. math::
AX = B\text{,}
where :math:`A` is an :math:`n\times n` symmetric positive definite matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices.
.. _f07fc-py2-py-doc:
For full information please refer to the NAG Library document for f07fc
https://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07fnf.html
.. _f07fn-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored.
If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored.
**a** : complex, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` Hermitian matrix :math:`A`.
**b** : complex, array-like, shape :math:`\left(n, \textit{nrhs}\right)`
The :math:`n\times r` right-hand side matrix :math:`B`.
**Returns**
**a** : complex, ndarray, shape :math:`\left(n, n\right)`
If no exception or warning is raised, the factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{H}U` or :math:`A = LL^\mathrm{H}`.
**b** : complex, ndarray, shape :math:`\left(n, \textit{nrhs}\right)`
If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`.
.. _f07fn-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{uplo}`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\textit{nrhs}`.
Constraint: :math:`\textit{nrhs}\geq 0`.
(`errno` :math:`i > 0`)
The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is not positive definite, so the factorization could not be completed, and the solution has not been computed.
.. _f07fn-py2-py-notes:
**Notes**
``zposv`` uses the Cholesky decomposition to factor :math:`A` as :math:`A = U^\mathrm{H}U` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LL^\mathrm{H}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` is an upper triangular matrix and :math:`L` is a lower triangular matrix.
The factored form of :math:`A` is then used to solve the system of equations :math:`AX = B`.
.. _f07fn-py2-py-references:
**References**
Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError
[docs]def zposvx(fact, uplo, n, nrhs, a, af, equed, s, b):
r"""
``zposvx`` uses the Cholesky factorization
.. math::
A = U^\mathrm{H}U\quad \text{ or }\quad A = LL^\mathrm{H}
to compute the solution to a complex system of linear equations
.. math::
AX = B\text{,}
where :math:`A` is an :math:`n\times n` Hermitian positive definite matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices.
Error bounds on the solution and a condition estimate are also provided.
.. _f07fp-py2-py-doc:
For full information please refer to the NAG Library document for f07fp
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07fpf.html
.. _f07fp-py2-py-parameters:
**Parameters**
**fact** : str, length 1
Specifies whether or not the factorized form of the matrix :math:`A` is supplied on entry, and if not, whether the matrix :math:`A` should be equilibrated before it is factorized.
:math:`\mathrm{fact} = \texttt{'F'}`
:math:`\mathrm{af}` contains the factorized form of :math:`A`. If :math:`\mathrm{equed} = \texttt{'Y'}`, the matrix :math:`A` has been equilibrated with scaling factors given by :math:`\mathrm{s}`. :math:`\mathrm{a}` and :math:`\mathrm{af}` will not be modified.
:math:`\mathrm{fact} = \texttt{'N'}`
The matrix :math:`A` will be copied to :math:`\mathrm{af}` and factorized.
:math:`\mathrm{fact} = \texttt{'E'}`
The matrix :math:`A` will be equilibrated if necessary, then copied to :math:`\mathrm{af}` and factorized.
**uplo** : str, length 1
If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored.
If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored.
**n** : int
:math:`n`, the number of linear equations, i.e., the order of the matrix :math:`A`.
**nrhs** : int
:math:`r`, the number of right-hand sides, i.e., the number of columns of the matrix :math:`B`.
**a** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)`
The :math:`n\times n` Hermitian matrix :math:`A`.
If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{a}` must have been equilibrated by the scaling factor in :math:`\mathrm{s}` as :math:`D_SAD_S`.
**af** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{af}` contains the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{H}U` or :math:`A = LL^\mathrm{H}`, in the same storage format as :math:`\mathrm{a}`. If :math:`\mathrm{equed} \neq \texttt{'N'}`, :math:`\mathrm{af}` is the factorized form of the equilibrated matrix :math:`D_SAD_S`.
**equed** : str, length 1
If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{equed}` need not be set.
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` must specify the form of the equilibration that was performed as follows:
if :math:`\mathrm{equed} = \texttt{'N'}`, no equilibration;
if :math:`\mathrm{equed} = \texttt{'Y'}`, equilibration was performed, i.e., :math:`A` has been replaced by :math:`D_SAD_S`.
**s** : float, array-like, shape :math:`\left(\mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{s}` need not be set.
If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{s}` must contain the scale factors, :math:`D_S`, for :math:`A`; each element of :math:`\mathrm{s}` must be positive.
**b** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)`
The :math:`n\times r` right-hand side matrix :math:`B`.
**Returns**
**a** : complex, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'F'}` or :math:`\texttt{'N'}`, or if :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{a}` is not modified.
If :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{a}` is overwritten by :math:`D_SAD_S`.
**af** : complex, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{af}` returns the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{H}U` or :math:`A = LL^\mathrm{H}` of the original matrix :math:`A`.
If :math:`\mathrm{fact} = \texttt{'E'}`, :math:`\mathrm{af}` returns the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{H}U` or :math:`A = LL^\mathrm{H}` of the equilibrated matrix :math:`A` (see the description of :math:`\mathrm{a}` for the form of the equilibrated matrix).
**equed** : str, length 1
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` is unchanged from entry.
Otherwise, if no constraints are violated, :math:`\mathrm{equed}` specifies the form of the equilibration that was performed as specified above.
**s** : float, ndarray, shape :math:`\left(\mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{s}` is unchanged from entry.
Otherwise, if no constraints are violated and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{s}` contains the scale factors, :math:`D_S`, for :math:`A`; each element of :math:`\mathrm{s}` is positive.
**b** : complex, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)`
If :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{b}` is not modified.
If :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{b}` is overwritten by :math:`D_SB`.
**x** : complex, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)`
If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, the :math:`n\times r` solution matrix :math:`X` to the original system of equations. Note that the arrays :math:`A` and :math:`B` are modified on exit if :math:`\mathrm{equed} = \texttt{'Y'}`, and the solution to the equilibrated system is :math:`D_S^{-1}X`.
**rcond** : float
If no constraints are violated, an estimate of the reciprocal condition number of the matrix :math:`A` (after equilibration if that is performed), computed as :math:`\mathrm{rcond} = 1.0/\left(\left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\right)`.
**ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)`
If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the forward error bound for each computed solution vector, such that :math:`\left\lVert \hat{x}_j-x_j\right\rVert_\infty/\left\lVert x_j\right\rVert_\infty\leq \mathrm{ferr}[j-1]` where :math:`\hat{x}_j` is the :math:`j`\ th column of the computed solution returned in the array :math:`\mathrm{x}` and :math:`x_j` is the corresponding column of the exact solution :math:`X`. The estimate is as reliable as the estimate for :math:`\mathrm{rcond}`, and is almost always a slight overestimate of the true error.
**berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)`
If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the component-wise relative backward error of each computed solution vector :math:`\hat{x}_j` (i.e., the smallest relative change in any element of :math:`A` or :math:`B` that makes :math:`\hat{x}_j` an exact solution).
.. _f07fp-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{fact}`.
Constraint: :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\texttt{'N'}` or :math:`\texttt{'E'}`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\mathrm{uplo}`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{n}`.
Constraint: :math:`\mathrm{n}\geq 0`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\mathrm{nrhs}`.
Constraint: :math:`\mathrm{nrhs}\geq 0`.
(`errno` :math:`-9`)
On entry, error in parameter :math:`\mathrm{equed}`.
Constraint: :math:`\mathrm{equed} = \texttt{'N'}` or :math:`\texttt{'Y'}`.
(`errno` :math:`-10`)
On entry, error in parameter :math:`\mathrm{s}`.
(`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq \mathrm{n}\right)`)
The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is not positive definite, so the factorization could not be completed, and the solution has not been computed. :math:`\mathrm{rcond} = 0.0` is returned.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`\mathrm{n}+1`)
:math:`U` (or :math:`L`) is nonsingular, but :math:`\mathrm{rcond}` is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of :math:`\mathrm{rcond}` would suggest.
.. _f07fp-py2-py-notes:
**Notes**
``zposvx`` performs the following steps:
(1) If :math:`\mathrm{fact} = \texttt{'E'}`, real diagonal scaling factors, :math:`D_S`, are computed to equilibrate the system:
.. math::
\left(D_SAD_S\right)\left(D_S^{-1}X\right) = D_SB\text{.}
Whether or not the system will be equilibrated depends on the scaling of the matrix :math:`A`, but if equilibration is used, :math:`A` is overwritten by :math:`D_SAD_S` and :math:`B\times D_SB`.
(#) If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, the Cholesky decomposition is used to factor the matrix :math:`A` (after equilibration if :math:`\mathrm{fact} = \texttt{'E'}`) as :math:`A = U^\mathrm{H}U` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LL^\mathrm{H}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` is an upper triangular matrix and :math:`L` is a lower triangular matrix.
(#) If the leading :math:`i\times i` principal minor of :math:`A` is not positive definite, then the function returns with :math:`\textit{errno} = i`. Otherwise, the factored form of :math:`A` is used to estimate the condition number of the matrix :math:`A`. If the reciprocal of the condition number is less than machine precision, :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1 is returned as a warning, but the function still goes on to solve for :math:`X` and compute error bounds as described below.
(#) The system of equations is solved for :math:`X` using the factored form of :math:`A`.
(#) Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for it.
(#) If equilibration was used, the matrix :math:`X` is premultiplied by :math:`D_S` so that it solves the original system before equilibration.
.. _f07fp-py2-py-references:
**References**
Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia
"""
raise NotImplementedError
[docs]def zcposv(uplo, n, nrhs, a, b):
r"""
``zcposv`` uses the Cholesky factorization
.. math::
A = U^\mathrm{H}U\quad \text{ or }\quad A = LL^\mathrm{H}
to compute the solution to a complex system of linear equations
.. math::
AX = B\text{,}
where :math:`A` is an :math:`n\times n` Hermitian positive definite matrix and :math:`X` and :math:`B` are :math:`n\times r` matrices.
.. _f07fq-py2-py-doc:
For full information please refer to the NAG Library document for f07fq
https://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07gaf.html
.. _f07ga-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored.
If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored.
**ap** : float, array-like, shape :math:`\left(n\times \left(n+1\right)/2\right)`
The :math:`n\times n` symmetric matrix :math:`A`, packed by columns.
**b** : float, array-like, shape :math:`\left(n, \textit{nrhs}\right)`
The :math:`n\times r` right-hand side matrix :math:`B`.
**Returns**
**ap** : float, ndarray, shape :math:`\left(n\times \left(n+1\right)/2\right)`
If no exception or warning is raised, the factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{T}U` or :math:`A = LL^\mathrm{T}`, in the same storage format as :math:`A`.
**b** : float, ndarray, shape :math:`\left(n, \textit{nrhs}\right)`
If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`.
.. _f07ga-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{uplo}`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\textit{nrhs}`.
Constraint: :math:`\textit{nrhs}\geq 0`.
(`errno` :math:`i > 0`)
The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is not positive definite, so the factorization could not be completed, and the solution has not been computed.
.. _f07ga-py2-py-notes:
**Notes**
``dppsv`` uses the Cholesky decomposition to factor :math:`A` as :math:`A = U^\mathrm{T}U` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LL^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` is an upper triangular matrix and :math:`L` is a lower triangular matrix.
The factored form of :math:`A` is then used to solve the system of equations :math:`AX = B`.
.. _f07ga-py2-py-references:
**References**
Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError
[docs]def dppsvx(fact, uplo, n, nrhs, ap, afp, equed, s, b):
r"""
``dppsvx`` uses the Cholesky factorization
.. math::
A = U^\mathrm{T}U\quad \text{ or }\quad A = LL^\mathrm{T}
to compute the solution to a real system of linear equations
.. math::
AX = B\text{,}
where :math:`A` is an :math:`n\times n` symmetric positive definite matrix stored in packed format and :math:`X` and :math:`B` are :math:`n\times r` matrices.
Error bounds on the solution and a condition estimate are also provided.
.. _f07gb-py2-py-doc:
For full information please refer to the NAG Library document for f07gb
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07gbf.html
.. _f07gb-py2-py-parameters:
**Parameters**
**fact** : str, length 1
Specifies whether or not the factorized form of the matrix :math:`A` is supplied on entry, and if not, whether the matrix :math:`A` should be equilibrated before it is factorized.
:math:`\mathrm{fact} = \texttt{'F'}`
:math:`\mathrm{afp}` contains the factorized form of :math:`A`. If :math:`\mathrm{equed} = \texttt{'Y'}`, the matrix :math:`A` has been equilibrated with scaling factors given by :math:`\mathrm{s}`. :math:`\mathrm{ap}` and :math:`\mathrm{afp}` will not be modified.
:math:`\mathrm{fact} = \texttt{'N'}`
The matrix :math:`A` will be copied to :math:`\mathrm{afp}` and factorized.
:math:`\mathrm{fact} = \texttt{'E'}`
The matrix :math:`A` will be equilibrated if necessary, then copied to :math:`\mathrm{afp}` and factorized.
**uplo** : str, length 1
If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored.
If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored.
**n** : int
:math:`n`, the number of linear equations, i.e., the order of the matrix :math:`A`.
**nrhs** : int
:math:`r`, the number of right-hand sides, i.e., the number of columns of the matrix :math:`B`.
**ap** : float, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{ap}` must contain the equilibrated matrix :math:`D_SAD_S`; otherwise, :math:`\mathrm{ap}` must contain the :math:`n\times n` symmetric matrix :math:`A`, packed by columns.
**afp** : float, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{afp}` contains the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{T}U` or :math:`A = LL^\mathrm{T}`, in the same storage format as :math:`\mathrm{ap}`. If :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{afp}` is the factorized form of the equilibrated matrix :math:`D_SAD_S`.
**equed** : str, length 1
If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{equed}` need not be set.
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` must specify the form of the equilibration that was performed as follows:
if :math:`\mathrm{equed} = \texttt{'N'}`, no equilibration;
if :math:`\mathrm{equed} = \texttt{'Y'}`, equilibration was performed, i.e., :math:`A` has been replaced by :math:`D_SAD_S`.
**s** : float, array-like, shape :math:`\left(\mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{s}` need not be set.
If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{s}` must contain the scale factors, :math:`D_S`, for :math:`A`; each element of :math:`\mathrm{s}` must be positive.
**b** : float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)`
The :math:`n\times r` right-hand side matrix :math:`B`.
**Returns**
**ap** : float, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
If :math:`\mathrm{fact} = \texttt{'F'}` or :math:`\texttt{'N'}`, or if :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{ap}` is not modified.
If :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{ap}` is overwritten by :math:`D_SAD_S`.
**afp** : float, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
If :math:`\mathrm{fact} = \texttt{'N'}` or if :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{afp}` returns the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{T}U` or :math:`A = LL^\mathrm{T}` of the original matrix :math:`A`.
If :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{afp}` returns the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{T}U` or :math:`A = LL^\mathrm{T}` of the equilibrated matrix :math:`A` (see the description of :math:`\mathrm{ap}` for the form of the equilibrated matrix).
**equed** : str, length 1
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` is unchanged from entry.
Otherwise, if no constraints are violated, :math:`\mathrm{equed}` specifies the form of the equilibration that was performed as specified above.
**s** : float, ndarray, shape :math:`\left(\mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{s}` is unchanged from entry.
Otherwise, if no constraints are violated and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{s}` contains the scale factors, :math:`D_S`, for :math:`A`; each element of :math:`\mathrm{s}` is positive.
**b** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)`
If :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{b}` is not modified.
If :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{b}` is overwritten by :math:`D_SB`.
**x** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)`
If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, the :math:`n\times r` solution matrix :math:`X` to the original system of equations. Note that the arrays :math:`A` and :math:`B` are modified on exit if :math:`\mathrm{equed} = \texttt{'Y'}`, and the solution to the equilibrated system is :math:`D_S^{-1}X`.
**rcond** : float
If no constraints are violated, an estimate of the reciprocal condition number of the matrix :math:`A` (after equilibration if that is performed), computed as :math:`\mathrm{rcond} = 1.0/\left(\left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\right)`.
**ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)`
If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the forward error bound for each computed solution vector, such that :math:`\left\lVert \hat{x}_j-x_j\right\rVert_\infty/\left\lVert x_j\right\rVert_\infty\leq \mathrm{ferr}[j-1]` where :math:`\hat{x}_j` is the :math:`j`\ th column of the computed solution returned in the array :math:`\mathrm{x}` and :math:`x_j` is the corresponding column of the exact solution :math:`X`. The estimate is as reliable as the estimate for :math:`\mathrm{rcond}`, and is almost always a slight overestimate of the true error.
**berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)`
If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the component-wise relative backward error of each computed solution vector :math:`\hat{x}_j` (i.e., the smallest relative change in any element of :math:`A` or :math:`B` that makes :math:`\hat{x}_j` an exact solution).
.. _f07gb-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{fact}`.
Constraint: :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\texttt{'N'}` or :math:`\texttt{'E'}`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\mathrm{uplo}`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{n}`.
Constraint: :math:`\mathrm{n}\geq 0`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\mathrm{nrhs}`.
Constraint: :math:`\mathrm{nrhs}\geq 0`.
(`errno` :math:`-7`)
On entry, error in parameter :math:`\mathrm{equed}`.
Constraint: :math:`\mathrm{equed} = \texttt{'N'}` or :math:`\texttt{'Y'}`.
(`errno` :math:`-8`)
On entry, error in parameter :math:`\mathrm{s}`.
(`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq \mathrm{n}\right)`)
The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is not positive definite, so the factorization could not be completed, and the solution has not been computed. :math:`\mathrm{rcond} = 0.0` is returned.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`\mathrm{n}+1`)
:math:`U` (or :math:`L`) is nonsingular, but :math:`\mathrm{rcond}` is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of :math:`\mathrm{rcond}` would suggest.
.. _f07gb-py2-py-notes:
**Notes**
``dppsvx`` performs the following steps:
(1) If :math:`\mathrm{fact} = \texttt{'E'}`, real diagonal scaling factors, :math:`D_S`, are computed to equilibrate the system:
.. math::
\left(D_SAD_S\right)\left(D_S^{-1}X\right) = D_SB\text{.}
Whether or not the system will be equilibrated depends on the scaling of the matrix :math:`A`, but if equilibration is used, :math:`A` is overwritten by :math:`D_SAD_S` and :math:`B\times D_SB`.
(#) If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, the Cholesky decomposition is used to factor the matrix :math:`A` (after equilibration if :math:`\mathrm{fact} = \texttt{'E'}`) as :math:`A = U^\mathrm{T}U` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LL^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` is an upper triangular matrix and :math:`L` is a lower triangular matrix.
(#) If the leading :math:`i\times i` principal minor of :math:`A` is not positive definite, then the function returns with :math:`\textit{errno} = i`. Otherwise, the factored form of :math:`A` is used to estimate the condition number of the matrix :math:`A`. If the reciprocal of the condition number is less than machine precision, :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1 is returned as a warning, but the function still goes on to solve for :math:`X` and compute error bounds as described below.
(#) The system of equations is solved for :math:`X` using the factored form of :math:`A`.
(#) Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for it.
(#) If equilibration was used, the matrix :math:`X` is premultiplied by :math:`D_S` so that it solves the original system before equilibration.
.. _f07gb-py2-py-references:
**References**
Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia
"""
raise NotImplementedError
[docs]def dpptrf(uplo, n, ap):
r"""
``dpptrf`` computes the Cholesky factorization of a real symmetric positive definite matrix, using packed storage.
.. _f07gd-py2-py-doc:
For full information please refer to the NAG Library document for f07gd
https://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07gnf.html
.. _f07gn-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored.
If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored.
**ap** : complex, array-like, shape :math:`\left(n\times \left(n+1\right)/2\right)`
The :math:`n\times n` Hermitian matrix :math:`A`, packed by columns.
**b** : complex, array-like, shape :math:`\left(n, \textit{nrhs}\right)`
The :math:`n\times r` right-hand side matrix :math:`B`.
**Returns**
**ap** : complex, ndarray, shape :math:`\left(n\times \left(n+1\right)/2\right)`
If no exception or warning is raised, the factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{H}U` or :math:`A = LL^\mathrm{H}`, in the same storage format as :math:`A`.
**b** : complex, ndarray, shape :math:`\left(n, \textit{nrhs}\right)`
If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`.
.. _f07gn-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{uplo}`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\textit{nrhs}`.
Constraint: :math:`\textit{nrhs}\geq 0`.
(`errno` :math:`i > 0`)
The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is not positive definite, so the factorization could not be completed, and the solution has not been computed.
.. _f07gn-py2-py-notes:
**Notes**
``zppsv`` uses the Cholesky decomposition to factor :math:`A` as :math:`A = U^\mathrm{H}U` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LL^\mathrm{H}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` is an upper triangular matrix and :math:`L` is a lower triangular matrix.
The factored form of :math:`A` is then used to solve the system of equations :math:`AX = B`.
.. _f07gn-py2-py-references:
**References**
Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError
[docs]def zppsvx(fact, uplo, n, nrhs, ap, afp, equed, s, b):
r"""
``zppsvx`` uses the Cholesky factorization
.. math::
A = U^\mathrm{H}U\quad \text{ or }\quad A = LL^\mathrm{H}
to compute the solution to a complex system of linear equations
.. math::
AX = B\text{,}
where :math:`A` is an :math:`n\times n` Hermitian positive definite matrix stored in packed format and :math:`X` and :math:`B` are :math:`n\times r` matrices.
Error bounds on the solution and a condition estimate are also provided.
.. _f07gp-py2-py-doc:
For full information please refer to the NAG Library document for f07gp
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07gpf.html
.. _f07gp-py2-py-parameters:
**Parameters**
**fact** : str, length 1
Specifies whether or not the factorized form of the matrix :math:`A` is supplied on entry, and if not, whether the matrix :math:`A` should be equilibrated before it is factorized.
:math:`\mathrm{fact} = \texttt{'F'}`
:math:`\mathrm{afp}` contains the factorized form of :math:`A`. If :math:`\mathrm{equed} = \texttt{'Y'}`, the matrix :math:`A` has been equilibrated with scaling factors given by :math:`\mathrm{s}`. :math:`\mathrm{ap}` and :math:`\mathrm{afp}` will not be modified.
:math:`\mathrm{fact} = \texttt{'N'}`
The matrix :math:`A` will be copied to :math:`\mathrm{afp}` and factorized.
:math:`\mathrm{fact} = \texttt{'E'}`
The matrix :math:`A` will be equilibrated if necessary, then copied to :math:`\mathrm{afp}` and factorized.
**uplo** : str, length 1
If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored.
If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored.
**n** : int
:math:`n`, the number of linear equations, i.e., the order of the matrix :math:`A`.
**nrhs** : int
:math:`r`, the number of right-hand sides, i.e., the number of columns of the matrix :math:`B`.
**ap** : complex, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{ap}` must contain the equilibrated matrix :math:`D_SAD_S`; otherwise, :math:`\mathrm{ap}` must contain the :math:`n\times n` Hermitian matrix :math:`A`, packed by columns.
**afp** : complex, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{afp}` contains the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{H}U` or :math:`A = LL^\mathrm{H}`, in the same storage format as :math:`\mathrm{ap}`. If :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{afp}` is the factorized form of the equilibrated matrix :math:`D_SAD_S`.
**equed** : str, length 1
If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{equed}` need not be set.
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` must specify the form of the equilibration that was performed as follows:
if :math:`\mathrm{equed} = \texttt{'N'}`, no equilibration;
if :math:`\mathrm{equed} = \texttt{'Y'}`, equilibration was performed, i.e., :math:`A` has been replaced by :math:`D_SAD_S`.
**s** : float, array-like, shape :math:`\left(\mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{s}` need not be set.
If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{s}` must contain the scale factors, :math:`D_S`, for :math:`A`; each element of :math:`\mathrm{s}` must be positive.
**b** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)`
The :math:`n\times r` right-hand side matrix :math:`B`.
**Returns**
**ap** : complex, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
If :math:`\mathrm{fact} = \texttt{'F'}` or :math:`\texttt{'N'}`, or if :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{ap}` is not modified.
If :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{ap}` is overwritten by :math:`D_SAD_S`.
**afp** : complex, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
If :math:`\mathrm{fact} = \texttt{'N'}` or if :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{afp}` returns the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{H}U` or :math:`A = LL^\mathrm{H}` of the original matrix :math:`A`.
If :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{afp}` returns the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{H}U` or :math:`A = LL^\mathrm{H}` of the equilibrated matrix :math:`A` (see the description of :math:`\mathrm{ap}` for the form of the equilibrated matrix).
**equed** : str, length 1
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` is unchanged from entry.
Otherwise, if no constraints are violated, :math:`\mathrm{equed}` specifies the form of the equilibration that was performed as specified above.
**s** : float, ndarray, shape :math:`\left(\mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{s}` is unchanged from entry.
Otherwise, if no constraints are violated and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{s}` contains the scale factors, :math:`D_S`, for :math:`A`; each element of :math:`\mathrm{s}` is positive.
**b** : complex, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)`
If :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{b}` is not modified.
If :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{b}` is overwritten by :math:`D_SB`.
**x** : complex, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)`
If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, the :math:`n\times r` solution matrix :math:`X` to the original system of equations. Note that the arrays :math:`A` and :math:`B` are modified on exit if :math:`\mathrm{equed} = \texttt{'Y'}`, and the solution to the equilibrated system is :math:`D_S^{-1}X`.
**rcond** : float
If no constraints are violated, an estimate of the reciprocal condition number of the matrix :math:`A` (after equilibration if that is performed), computed as :math:`\mathrm{rcond} = 1.0/\left(\left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\right)`.
**ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)`
If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the forward error bound for each computed solution vector, such that :math:`\left\lVert \hat{x}_j-x_j\right\rVert_\infty/\left\lVert x_j\right\rVert_\infty\leq \mathrm{ferr}[j-1]` where :math:`\hat{x}_j` is the :math:`j`\ th column of the computed solution returned in the array :math:`\mathrm{x}` and :math:`x_j` is the corresponding column of the exact solution :math:`X`. The estimate is as reliable as the estimate for :math:`\mathrm{rcond}`, and is almost always a slight overestimate of the true error.
**berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)`
If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the component-wise relative backward error of each computed solution vector :math:`\hat{x}_j` (i.e., the smallest relative change in any element of :math:`A` or :math:`B` that makes :math:`\hat{x}_j` an exact solution).
.. _f07gp-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{fact}`.
Constraint: :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\texttt{'N'}` or :math:`\texttt{'E'}`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\mathrm{uplo}`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{n}`.
Constraint: :math:`\mathrm{n}\geq 0`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\mathrm{nrhs}`.
Constraint: :math:`\mathrm{nrhs}\geq 0`.
(`errno` :math:`-7`)
On entry, error in parameter :math:`\mathrm{equed}`.
Constraint: :math:`\mathrm{equed} = \texttt{'N'}` or :math:`\texttt{'Y'}`.
(`errno` :math:`-8`)
On entry, error in parameter :math:`\mathrm{s}`.
(`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq \mathrm{n}\right)`)
The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is not positive definite, so the factorization could not be completed, and the solution has not been computed. :math:`\mathrm{rcond} = 0.0` is returned.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`\mathrm{n}+1`)
:math:`U` (or :math:`L`) is nonsingular, but :math:`\mathrm{rcond}` is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of :math:`\mathrm{rcond}` would suggest.
.. _f07gp-py2-py-notes:
**Notes**
``zppsvx`` performs the following steps:
(1) If :math:`\mathrm{fact} = \texttt{'E'}`, real diagonal scaling factors, :math:`D_S`, are computed to equilibrate the system:
.. math::
\left(D_SAD_S\right)\left(D_S^{-1}X\right) = D_SB\text{.}
Whether or not the system will be equilibrated depends on the scaling of the matrix :math:`A`, but if equilibration is used, :math:`A` is overwritten by :math:`D_SAD_S` and :math:`B\times D_SB`.
(#) If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, the Cholesky decomposition is used to factor the matrix :math:`A` (after equilibration if :math:`\mathrm{fact} = \texttt{'E'}`) as :math:`A = U^\mathrm{H}U` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LL^\mathrm{H}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` is an upper triangular matrix and :math:`L` is a lower triangular matrix.
(#) If the leading :math:`i\times i` principal minor of :math:`A` is not positive definite, then the function returns with :math:`\textit{errno} = i`. Otherwise, the factored form of :math:`A` is used to estimate the condition number of the matrix :math:`A`. If the reciprocal of the condition number is less than machine precision, :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1 is returned as a warning, but the function still goes on to solve for :math:`X` and compute error bounds as described below.
(#) The system of equations is solved for :math:`X` using the factored form of :math:`A`.
(#) Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for it.
(#) If equilibration was used, the matrix :math:`X` is premultiplied by :math:`D_S` so that it solves the original system before equilibration.
.. _f07gp-py2-py-references:
**References**
Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia
"""
raise NotImplementedError
[docs]def zpptrf(uplo, n, ap):
r"""
``zpptrf`` computes the Cholesky factorization of a complex Hermitian positive definite matrix, using packed storage.
.. _f07gr-py2-py-doc:
For full information please refer to the NAG Library document for f07gr
https://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07haf.html
.. _f07ha-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored.
If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored.
**kd** : int
:math:`k_d`, the number of superdiagonals of the matrix :math:`A` if :math:`\mathrm{uplo} = \texttt{'U'}`, or the number of subdiagonals if :math:`\mathrm{uplo} = \texttt{'L'}`.
**ab** : float, array-like, shape :math:`\left(\mathrm{kd}+1, n\right)`
The upper or lower triangle of the symmetric band matrix :math:`A`.
**b** : float, array-like, shape :math:`\left(n, \textit{nrhs}\right)`
The :math:`n\times r` right-hand side matrix :math:`B`.
**Returns**
**ab** : float, ndarray, shape :math:`\left(\mathrm{kd}+1, n\right)`
If no exception or warning is raised, the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{T}U` or :math:`A = LL^\mathrm{T}` of the band matrix :math:`A`, in the same storage format as :math:`A`.
**b** : float, ndarray, shape :math:`\left(n, \textit{nrhs}\right)`
If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`.
.. _f07ha-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{uplo}`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{kd}`.
Constraint: :math:`\mathrm{kd}\geq 0`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\textit{nrhs}`.
Constraint: :math:`\textit{nrhs}\geq 0`.
(`errno` :math:`i > 0`)
The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is not positive definite, so the factorization could not be completed, and the solution has not been computed.
.. _f07ha-py2-py-notes:
**Notes**
``dpbsv`` uses the Cholesky decomposition to factor :math:`A` as :math:`A = U^\mathrm{T}U` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LL^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` is an upper triangular band matrix, and :math:`L` is a lower triangular band matrix, with the same number of superdiagonals or subdiagonals as :math:`A`.
The factored form of :math:`A` is then used to solve the system of equations :math:`AX = B`.
.. _f07ha-py2-py-references:
**References**
Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError
[docs]def dpbsvx(fact, uplo, n, kd, nrhs, ab, afb, equed, s, b):
r"""
``dpbsvx`` uses the Cholesky factorization
.. math::
A = U^\mathrm{T}U\quad \text{ or }\quad A = LL^\mathrm{T}
to compute the solution to a real system of linear equations
.. math::
AX = B\text{,}
where :math:`A` is an :math:`n\times n` symmetric positive definite band matrix of bandwidth :math:`\left(2k_d+1\right)` and :math:`X` and :math:`B` are :math:`n\times r` matrices.
Error bounds on the solution and a condition estimate are also provided.
.. _f07hb-py2-py-doc:
For full information please refer to the NAG Library document for f07hb
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07hbf.html
.. _f07hb-py2-py-parameters:
**Parameters**
**fact** : str, length 1
Specifies whether or not the factorized form of the matrix :math:`A` is supplied on entry, and if not, whether the matrix :math:`A` should be equilibrated before it is factorized.
:math:`\mathrm{fact} = \texttt{'F'}`
:math:`\mathrm{afb}` contains the factorized form of :math:`A`. If :math:`\mathrm{equed} = \texttt{'Y'}`, the matrix :math:`A` has been equilibrated with scaling factors given by :math:`\mathrm{s}`. :math:`\mathrm{ab}` and :math:`\mathrm{afb}` will not be modified.
:math:`\mathrm{fact} = \texttt{'N'}`
The matrix :math:`A` will be copied to :math:`\mathrm{afb}` and factorized.
:math:`\mathrm{fact} = \texttt{'E'}`
The matrix :math:`A` will be equilibrated if necessary, then copied to :math:`\mathrm{afb}` and factorized.
**uplo** : str, length 1
If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored.
If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored.
**n** : int
:math:`n`, the number of linear equations, i.e., the order of the matrix :math:`A`.
**kd** : int
:math:`k_d`, the number of superdiagonals of the matrix :math:`A` if :math:`\mathrm{uplo} = \texttt{'U'}`, or the number of subdiagonals if :math:`\mathrm{uplo} = \texttt{'L'}`.
**nrhs** : int
:math:`r`, the number of right-hand sides, i.e., the number of columns of the matrix :math:`B`.
**ab** : float, array-like, shape :math:`\left(\mathrm{kd}+1, \mathrm{n}\right)`
The upper or lower triangle of the symmetric band matrix :math:`A`, except if :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, in which case :math:`\mathrm{ab}` must contain the equilibrated matrix :math:`D_SAD_S`.
**afb** : float, array-like, shape :math:`\left(\mathrm{kd}+1, \mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{afb}` contains the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{T}U` or :math:`A = LL^\mathrm{T}` of the band matrix :math:`A`, in the same storage format as :math:`A`. If :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{afb}` is the factorized form of the equilibrated matrix :math:`A`.
**equed** : str, length 1
If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{equed}` need not be set.
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` must specify the form of the equilibration that was performed as follows:
if :math:`\mathrm{equed} = \texttt{'N'}`, no equilibration;
if :math:`\mathrm{equed} = \texttt{'Y'}`, equilibration was performed, i.e., :math:`A` has been replaced by :math:`D_SAD_S`.
**s** : float, array-like, shape :math:`\left(\mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{s}` need not be set.
If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{s}` must contain the scale factors, :math:`D_S`, for :math:`A`; each element of :math:`\mathrm{s}` must be positive.
**b** : float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)`
The :math:`n\times r` right-hand side matrix :math:`B`.
**Returns**
**ab** : float, ndarray, shape :math:`\left(\mathrm{kd}+1, \mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{ab}` is overwritten by :math:`D_SAD_S`.
**afb** : float, ndarray, shape :math:`\left(\mathrm{kd}+1, \mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{afb}` returns the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{T}U` or :math:`A = LL^\mathrm{T}`.
If :math:`\mathrm{fact} = \texttt{'E'}`, :math:`\mathrm{afb}` returns the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{T}U` or :math:`A = LL^\mathrm{T}` of the equilibrated matrix :math:`A` (see the description of :math:`\mathrm{ab}` for the form of the equilibrated matrix).
**equed** : str, length 1
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` is unchanged from entry.
Otherwise, if no constraints are violated, :math:`\mathrm{equed}` specifies the form of the equilibration that was performed as specified above.
**s** : float, ndarray, shape :math:`\left(\mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{s}` is unchanged from entry.
Otherwise, if no constraints are violated and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{s}` contains the scale factors, :math:`D_S`, for :math:`A`; each element of :math:`\mathrm{s}` is positive.
**b** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)`
If :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{b}` is not modified.
If :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{b}` is overwritten by :math:`D_SB`.
**x** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)`
If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, the :math:`n\times r` solution matrix :math:`X` to the original system of equations. Note that the arrays :math:`A` and :math:`B` are modified on exit if :math:`\mathrm{equed} = \texttt{'Y'}`, and the solution to the equilibrated system is :math:`D_S^{-1}X`.
**rcond** : float
If no constraints are violated, an estimate of the reciprocal condition number of the matrix :math:`A` (after equilibration if that is performed), computed as :math:`\mathrm{rcond} = 1.0/\left(\left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\right)`.
**ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)`
If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the forward error bound for each computed solution vector, such that :math:`\left\lVert \hat{x}_j-x_j\right\rVert_\infty/\left\lVert x_j\right\rVert_\infty\leq \mathrm{ferr}[j-1]` where :math:`\hat{x}_j` is the :math:`j`\ th column of the computed solution returned in the array :math:`\mathrm{x}` and :math:`x_j` is the corresponding column of the exact solution :math:`X`. The estimate is as reliable as the estimate for :math:`\mathrm{rcond}`, and is almost always a slight overestimate of the true error.
**berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)`
If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the component-wise relative backward error of each computed solution vector :math:`\hat{x}_j` (i.e., the smallest relative change in any element of :math:`A` or :math:`B` that makes :math:`\hat{x}_j` an exact solution).
.. _f07hb-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{fact}`.
Constraint: :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\texttt{'N'}` or :math:`\texttt{'E'}`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\mathrm{uplo}`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{n}`.
Constraint: :math:`\mathrm{n}\geq 0`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\mathrm{kd}`.
Constraint: :math:`\mathrm{kd}\geq 0`.
(`errno` :math:`-5`)
On entry, error in parameter :math:`\mathrm{nrhs}`.
Constraint: :math:`\mathrm{nrhs}\geq 0`.
(`errno` :math:`-10`)
On entry, error in parameter :math:`\mathrm{equed}`.
Constraint: :math:`\mathrm{equed} = \texttt{'N'}` or :math:`\texttt{'Y'}`.
(`errno` :math:`-11`)
On entry, error in parameter :math:`\mathrm{s}`.
(`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq \mathrm{n}\right)`)
The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is not positive definite, so the factorization could not be completed, and the solution has not been computed. :math:`\mathrm{rcond} = 0.0` is returned.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`\mathrm{n}+1`)
:math:`U` (or :math:`L`) is nonsingular, but :math:`\mathrm{rcond}` is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of :math:`\mathrm{rcond}` would suggest.
.. _f07hb-py2-py-notes:
**Notes**
``dpbsvx`` performs the following steps:
(1) If :math:`\mathrm{fact} = \texttt{'E'}`, real diagonal scaling factors, :math:`D_S`, are computed to equilibrate the system:
.. math::
\left(D_SAD_S\right)\left(D_S^{-1}X\right) = D_SB\text{.}
Whether or not the system will be equilibrated depends on the scaling of the matrix :math:`A`, but if equilibration is used, :math:`A` is overwritten by :math:`D_SAD_S` and :math:`B\times D_SB`.
(#) If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, the Cholesky decomposition is used to factor the matrix :math:`A` (after equilibration if :math:`\mathrm{fact} = \texttt{'E'}`) as :math:`A = U^\mathrm{T}U` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LL^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` is an upper triangular matrix and :math:`L` is a lower triangular matrix.
(#) If the leading :math:`i\times i` principal minor of :math:`A` is not positive definite, then the function returns with :math:`\textit{errno} = i`. Otherwise, the factored form of :math:`A` is used to estimate the condition number of the matrix :math:`A`. If the reciprocal of the condition number is less than machine precision, :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1 is returned as a warning, but the function still goes on to solve for :math:`X` and compute error bounds as described below.
(#) The system of equations is solved for :math:`X` using the factored form of :math:`A`.
(#) Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for it.
(#) If equilibration was used, the matrix :math:`X` is premultiplied by :math:`D_S` so that it solves the original system before equilibration.
.. _f07hb-py2-py-references:
**References**
Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia
"""
raise NotImplementedError
[docs]def dpbtrf(uplo, kd, ab):
r"""
``dpbtrf`` computes the Cholesky factorization of a real symmetric positive definite band matrix.
.. _f07hd-py2-py-doc:
For full information please refer to the NAG Library document for f07hd
https://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07hnf.html
.. _f07hn-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored.
If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored.
**kd** : int
:math:`k_d`, the number of superdiagonals of the matrix :math:`A` if :math:`\mathrm{uplo} = \texttt{'U'}`, or the number of subdiagonals if :math:`\mathrm{uplo} = \texttt{'L'}`.
**ab** : complex, array-like, shape :math:`\left(\mathrm{kd}+1, n\right)`
The upper or lower triangle of the Hermitian band matrix :math:`A`.
**b** : complex, array-like, shape :math:`\left(n, \textit{nrhs}\right)`
The :math:`n\times r` right-hand side matrix :math:`B`.
**Returns**
**ab** : complex, ndarray, shape :math:`\left(\mathrm{kd}+1, n\right)`
If no exception or warning is raised, the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{H}U` or :math:`A = LL^\mathrm{H}` of the band matrix :math:`A`, in the same storage format as :math:`A`.
**b** : complex, ndarray, shape :math:`\left(n, \textit{nrhs}\right)`
If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`.
.. _f07hn-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{uplo}`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{kd}`.
Constraint: :math:`\mathrm{kd}\geq 0`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\textit{nrhs}`.
Constraint: :math:`\textit{nrhs}\geq 0`.
(`errno` :math:`i > 0`)
The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is not positive definite, so the factorization could not be completed, and the solution has not been computed.
.. _f07hn-py2-py-notes:
**Notes**
``zpbsv`` uses the Cholesky decomposition to factor :math:`A` as :math:`A = U^\mathrm{H}U` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LL^\mathrm{H}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` is an upper triangular band matrix, and :math:`L` is a lower triangular band matrix, with the same number of superdiagonals or subdiagonals as :math:`A`.
The factored form of :math:`A` is then used to solve the system of equations :math:`AX = B`.
.. _f07hn-py2-py-references:
**References**
Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError
[docs]def zpbsvx(fact, uplo, n, kd, nrhs, ab, afb, equed, s, b):
r"""
``zpbsvx`` uses the Cholesky factorization
.. math::
A = U^\mathrm{H}U\quad \text{ or }\quad A = LL^\mathrm{H}
to compute the solution to a complex system of linear equations
.. math::
AX = B\text{,}
where :math:`A` is an :math:`n\times n` Hermitian positive definite band matrix of bandwidth :math:`\left(2k_d+1\right)` and :math:`X` and :math:`B` are :math:`n\times r` matrices.
Error bounds on the solution and a condition estimate are also provided.
.. _f07hp-py2-py-doc:
For full information please refer to the NAG Library document for f07hp
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07hpf.html
.. _f07hp-py2-py-parameters:
**Parameters**
**fact** : str, length 1
Specifies whether or not the factorized form of the matrix :math:`A` is supplied on entry, and if not, whether the matrix :math:`A` should be equilibrated before it is factorized.
:math:`\mathrm{fact} = \texttt{'F'}`
:math:`\mathrm{afb}` contains the factorized form of :math:`A`. If :math:`\mathrm{equed} = \texttt{'Y'}`, the matrix :math:`A` has been equilibrated with scaling factors given by :math:`\mathrm{s}`. :math:`\mathrm{ab}` and :math:`\mathrm{afb}` will not be modified.
:math:`\mathrm{fact} = \texttt{'N'}`
The matrix :math:`A` will be copied to :math:`\mathrm{afb}` and factorized.
:math:`\mathrm{fact} = \texttt{'E'}`
The matrix :math:`A` will be equilibrated if necessary, then copied to :math:`\mathrm{afb}` and factorized.
**uplo** : str, length 1
If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored.
If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored.
**n** : int
:math:`n`, the number of linear equations, i.e., the order of the matrix :math:`A`.
**kd** : int
:math:`k_d`, the number of superdiagonals of the matrix :math:`A` if :math:`\mathrm{uplo} = \texttt{'U'}`, or the number of subdiagonals if :math:`\mathrm{uplo} = \texttt{'L'}`.
**nrhs** : int
:math:`r`, the number of right-hand sides, i.e., the number of columns of the matrix :math:`B`.
**ab** : complex, array-like, shape :math:`\left(\mathrm{kd}+1, \mathrm{n}\right)`
The upper or lower triangle of the Hermitian band matrix :math:`A`, except if :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, in which case :math:`\mathrm{ab}` must contain the equilibrated matrix :math:`D_SAD_S`.
**afb** : complex, array-like, shape :math:`\left(\mathrm{kd}+1, \mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{afb}` contains the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{H}U` or :math:`A = LL^\mathrm{H}` of the band matrix :math:`A`, in the same storage format as :math:`A`. If :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{afb}` is the factorized form of the equilibrated matrix :math:`A`.
**equed** : str, length 1
If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{equed}` need not be set.
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` must specify the form of the equilibration that was performed as follows:
if :math:`\mathrm{equed} = \texttt{'N'}`, no equilibration;
if :math:`\mathrm{equed} = \texttt{'Y'}`, equilibration was performed, i.e., :math:`A` has been replaced by :math:`D_SAD_S`.
**s** : float, array-like, shape :math:`\left(\mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{s}` need not be set.
If :math:`\mathrm{fact} = \texttt{'F'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{s}` must contain the scale factors, :math:`D_S`, for :math:`A`; each element of :math:`\mathrm{s}` must be positive.
**b** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)`
The :math:`n\times r` right-hand side matrix :math:`B`.
**Returns**
**ab** : complex, ndarray, shape :math:`\left(\mathrm{kd}+1, \mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'E'}` and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{ab}` is overwritten by :math:`D_SAD_S`.
**afb** : complex, ndarray, shape :math:`\left(\mathrm{kd}+1, \mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'N'}`, :math:`\mathrm{afb}` returns the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{H}U` or :math:`A = LL^\mathrm{H}`.
If :math:`\mathrm{fact} = \texttt{'E'}`, :math:`\mathrm{afb}` returns the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`A = U^\mathrm{H}U` or :math:`A = LL^\mathrm{H}` of the equilibrated matrix :math:`A` (see the description of :math:`\mathrm{ab}` for the form of the equilibrated matrix).
**equed** : str, length 1
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{equed}` is unchanged from entry.
Otherwise, if no constraints are violated, :math:`\mathrm{equed}` specifies the form of the equilibration that was performed as specified above.
**s** : float, ndarray, shape :math:`\left(\mathrm{n}\right)`
If :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\mathrm{s}` is unchanged from entry.
Otherwise, if no constraints are violated and :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{s}` contains the scale factors, :math:`D_S`, for :math:`A`; each element of :math:`\mathrm{s}` is positive.
**b** : complex, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)`
If :math:`\mathrm{equed} = \texttt{'N'}`, :math:`\mathrm{b}` is not modified.
If :math:`\mathrm{equed} = \texttt{'Y'}`, :math:`\mathrm{b}` is overwritten by :math:`D_SB`.
**x** : complex, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{nrhs}\right)`
If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, the :math:`n\times r` solution matrix :math:`X` to the original system of equations. Note that the arrays :math:`A` and :math:`B` are modified on exit if :math:`\mathrm{equed} = \texttt{'Y'}`, and the solution to the equilibrated system is :math:`D_S^{-1}X`.
**rcond** : float
If no constraints are violated, an estimate of the reciprocal condition number of the matrix :math:`A` (after equilibration if that is performed), computed as :math:`\mathrm{rcond} = 1.0/\left(\left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\right)`.
**ferr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)`
If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the forward error bound for each computed solution vector, such that :math:`\left\lVert \hat{x}_j-x_j\right\rVert_\infty/\left\lVert x_j\right\rVert_\infty\leq \mathrm{ferr}[j-1]` where :math:`\hat{x}_j` is the :math:`j`\ th column of the computed solution returned in the array :math:`\mathrm{x}` and :math:`x_j` is the corresponding column of the exact solution :math:`X`. The estimate is as reliable as the estimate for :math:`\mathrm{rcond}`, and is almost always a slight overestimate of the true error.
**berr** : float, ndarray, shape :math:`\left(\mathrm{nrhs}\right)`
If the function exits successfully or :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1, an estimate of the component-wise relative backward error of each computed solution vector :math:`\hat{x}_j` (i.e., the smallest relative change in any element of :math:`A` or :math:`B` that makes :math:`\hat{x}_j` an exact solution).
.. _f07hp-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{fact}`.
Constraint: :math:`\mathrm{fact} = \texttt{'F'}`, :math:`\texttt{'N'}` or :math:`\texttt{'E'}`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\mathrm{uplo}`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{n}`.
Constraint: :math:`\mathrm{n}\geq 0`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\mathrm{kd}`.
Constraint: :math:`\mathrm{kd}\geq 0`.
(`errno` :math:`-5`)
On entry, error in parameter :math:`\mathrm{nrhs}`.
Constraint: :math:`\mathrm{nrhs}\geq 0`.
(`errno` :math:`-10`)
On entry, error in parameter :math:`\mathrm{equed}`.
Constraint: :math:`\mathrm{equed} = \texttt{'N'}` or :math:`\texttt{'Y'}`.
(`errno` :math:`-11`)
On entry, error in parameter :math:`\mathrm{s}`.
(`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq \mathrm{n}\right)`)
The leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`A` is not positive definite, so the factorization could not be completed, and the solution has not been computed. :math:`\mathrm{rcond} = 0.0` is returned.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`\mathrm{n}+1`)
:math:`U` (or :math:`L`) is nonsingular, but :math:`\mathrm{rcond}` is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of :math:`\mathrm{rcond}` would suggest.
.. _f07hp-py2-py-notes:
**Notes**
``zpbsvx`` performs the following steps:
(1) If :math:`\mathrm{fact} = \texttt{'E'}`, real diagonal scaling factors, :math:`D_S`, are computed to equilibrate the system:
.. math::
\left(D_SAD_S\right)\left(D_S^{-1}X\right) = D_SB\text{.}
Whether or not the system will be equilibrated depends on the scaling of the matrix :math:`A`, but if equilibration is used, :math:`A` is overwritten by :math:`D_SAD_S` and :math:`B\times D_SB`.
(#) If :math:`\mathrm{fact} = \texttt{'N'}` or :math:`\texttt{'E'}`, the Cholesky decomposition is used to factor the matrix :math:`A` (after equilibration if :math:`\mathrm{fact} = \texttt{'E'}`) as :math:`A = U^\mathrm{H}U` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LL^\mathrm{H}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` is an upper triangular matrix and :math:`L` is a lower triangular matrix.
(#) If the leading :math:`i\times i` principal minor of :math:`A` is not positive definite, then the function returns with :math:`\textit{errno} = i`. Otherwise, the factored form of :math:`A` is used to estimate the condition number of the matrix :math:`A`. If the reciprocal of the condition number is less than machine precision, :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 1 is returned as a warning, but the function still goes on to solve for :math:`X` and compute error bounds as described below.
(#) The system of equations is solved for :math:`X` using the factored form of :math:`A`.
(#) Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for it.
(#) If equilibration was used, the matrix :math:`X` is premultiplied by :math:`D_S` so that it solves the original system before equilibration.
.. _f07hp-py2-py-references:
**References**
Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia
"""
raise NotImplementedError
[docs]def zpbtrf(uplo, kd, ab):
r"""
``zpbtrf`` computes the Cholesky factorization of a complex Hermitian positive definite band matrix.
.. _f07hr-py2-py-doc:
For full information please refer to the NAG Library document for f07hr
https://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07paf.html
.. _f07pa-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored.
If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored.
**ap** : float, array-like, shape :math:`\left(n\times \left(n+1\right)/2\right)`
The :math:`n\times n` symmetric matrix :math:`A`, packed by columns.
**b** : float, array-like, shape :math:`\left(n, \textit{nrhs}\right)`
The :math:`n\times r` right-hand side matrix :math:`B`.
**Returns**
**ap** : float, ndarray, shape :math:`\left(n\times \left(n+1\right)/2\right)`
The block diagonal matrix :math:`D` and the multipliers used to obtain the factor :math:`U` or :math:`L` from the factorization :math:`A = UDU^\mathrm{T}` or :math:`A = LDL^\mathrm{T}` as computed by :meth:`dsptrf`, stored as a packed triangular matrix in the same storage format as :math:`A`.
**ipiv** : int, ndarray, shape :math:`\left(n\right)`
Details of the interchanges and the block structure of :math:`D`. More precisely,
if :math:`\mathrm{ipiv}[i-1] = k > 0`, :math:`d_{{ii}}` is a :math:`1\times 1` pivot block and the :math:`i`\ th row and column of :math:`A` were interchanged with the :math:`k`\ th row and column;
if :math:`\mathrm{uplo} = \texttt{'U'}` and :math:`\mathrm{ipiv}[i-2] = \mathrm{ipiv}[i-1] = -l < 0`, :math:`\begin{pmatrix}d_{{i-1,i-1}}&\bar{d}_{{i,i-1}}\\\bar{d}_{{i,i-1}}&d_{{ii}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i-1\right)`\ th row and column of :math:`A` were interchanged with the :math:`l`\ th row and column;
if :math:`\mathrm{uplo} = \texttt{'L'}` and :math:`\mathrm{ipiv}[i-1] = \mathrm{ipiv}[i] = -m < 0`, :math:`\begin{pmatrix}d_{{ii}}&d_{{i+1,i}}\\d_{{i+1,i}}&d_{{i+1,i+1}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i+1\right)`\ th row and column of :math:`A` were interchanged with the :math:`m`\ th row and column.
**b** : float, ndarray, shape :math:`\left(n, \textit{nrhs}\right)`
If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`.
.. _f07pa-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{uplo}`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\textit{nrhs}`.
Constraint: :math:`\textit{nrhs}\geq 0`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`i > 0`)
Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the block diagonal matrix :math:`D` is exactly singular, so the solution could not be computed.
.. _f07pa-py2-py-notes:
**Notes**
``dspsv`` uses the diagonal pivoting method to factor :math:`A` as :math:`A = UDU^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LDL^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` (or :math:`L`) is a product of permutation and unit upper (lower) triangular matrices, :math:`D` is symmetric and block diagonal with :math:`1\times 1` and :math:`2\times 2` diagonal blocks.
The factored form of :math:`A` is then used to solve the system of equations :math:`AX = B`.
.. _f07pa-py2-py-references:
**References**
Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia
"""
raise NotImplementedError
[docs]def dspsvx(fact, uplo, nrhs, ap, afp, ipiv, b):
r"""
``dspsvx`` uses the diagonal pivoting factorization
.. math::
A = UDU^\mathrm{T}\quad \text{ or }\quad A = LDL^\mathrm{T}
to compute the solution to a real system of linear equations
.. math::
AX = B\text{,}
where :math:`A` is an :math:`n\times n` symmetric matrix stored in packed format and :math:`X` and :math:`B` are :math:`n\times r` matrices.
Error bounds on the solution and a condition estimate are also provided.
.. _f07pb-py2-py-doc:
For full information please refer to the NAG Library document for f07pb
https://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07pnf.html
.. _f07pn-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored.
If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored.
**ap** : complex, array-like, shape :math:`\left(n\times \left(n+1\right)/2\right)`
The :math:`n\times n` Hermitian matrix :math:`A`, packed by columns.
**b** : complex, array-like, shape :math:`\left(n, \textit{nrhs}\right)`
The :math:`n\times r` right-hand side matrix :math:`B`.
**Returns**
**ap** : complex, ndarray, shape :math:`\left(n\times \left(n+1\right)/2\right)`
The block diagonal matrix :math:`D` and the multipliers used to obtain the factor :math:`U` or :math:`L` from the factorization :math:`A = UDU^\mathrm{H}` or :math:`A = LDL^\mathrm{H}` as computed by :meth:`zhptrf`, stored as a packed triangular matrix in the same storage format as :math:`A`.
**ipiv** : int, ndarray, shape :math:`\left(n\right)`
Details of the interchanges and the block structure of :math:`D`. More precisely,
if :math:`\mathrm{ipiv}[i-1] = k > 0`, :math:`d_{{ii}}` is a :math:`1\times 1` pivot block and the :math:`i`\ th row and column of :math:`A` were interchanged with the :math:`k`\ th row and column;
if :math:`\mathrm{uplo} = \texttt{'U'}` and :math:`\mathrm{ipiv}[i-2] = \mathrm{ipiv}[i-1] = -l < 0`, :math:`\begin{pmatrix}d_{{i-1,i-1}}&\bar{d}_{{i,i-1}}\\\bar{d}_{{i,i-1}}&d_{{ii}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i-1\right)`\ th row and column of :math:`A` were interchanged with the :math:`l`\ th row and column;
if :math:`\mathrm{uplo} = \texttt{'L'}` and :math:`\mathrm{ipiv}[i-1] = \mathrm{ipiv}[i] = -m < 0`, :math:`\begin{pmatrix}d_{{ii}}&d_{{i+1,i}}\\d_{{i+1,i}}&d_{{i+1,i+1}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i+1\right)`\ th row and column of :math:`A` were interchanged with the :math:`m`\ th row and column.
**b** : complex, ndarray, shape :math:`\left(n, \textit{nrhs}\right)`
If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`.
.. _f07pn-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{uplo}`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\textit{nrhs}`.
Constraint: :math:`\textit{nrhs}\geq 0`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`i > 0`)
Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the block diagonal matrix :math:`D` is exactly singular, so the solution could not be computed.
.. _f07pn-py2-py-notes:
**Notes**
``zhpsv`` uses the diagonal pivoting method to factor :math:`A` as :math:`A = UDU^\mathrm{H}` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LDL^\mathrm{H}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` (or :math:`L`) is a product of permutation and unit upper (lower) triangular matrices, :math:`D` is Hermitian and block diagonal with :math:`1\times 1` and :math:`2\times 2` diagonal blocks.
The factored form of :math:`A` is then used to solve the system of equations :math:`AX = B`.
.. _f07pn-py2-py-references:
**References**
Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia
"""
raise NotImplementedError
[docs]def zhpsvx(fact, uplo, nrhs, ap, afp, ipiv, b):
r"""
``zhpsvx`` uses the diagonal pivoting factorization
.. math::
A = UDU^\mathrm{H}\quad \text{ or }\quad A = LDL^\mathrm{H}
to compute the solution to a complex system of linear equations
.. math::
AX = B\text{,}
where :math:`A` is an :math:`n\times n` Hermitian matrix stored in packed format and :math:`X` and :math:`B` are :math:`n\times r` matrices.
Error bounds on the solution and a condition estimate are also provided.
.. _f07pp-py2-py-doc:
For full information please refer to the NAG Library document for f07pp
https://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07qnf.html
.. _f07qn-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
If :math:`\mathrm{uplo} = \texttt{'U'}`, the upper triangle of :math:`A` is stored.
If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangle of :math:`A` is stored.
**ap** : complex, array-like, shape :math:`\left(n\times \left(n+1\right)/2\right)`
The :math:`n\times n` symmetric matrix :math:`A`, packed by columns.
**b** : complex, array-like, shape :math:`\left(n, \textit{nrhs}\right)`
The :math:`n\times r` right-hand side matrix :math:`B`.
**Returns**
**ap** : complex, ndarray, shape :math:`\left(n\times \left(n+1\right)/2\right)`
The block diagonal matrix :math:`D` and the multipliers used to obtain the factor :math:`U` or :math:`L` from the factorization :math:`A = UDU^\mathrm{H}` or :math:`A = LDL^\mathrm{H}` as computed by :meth:`zsptrf`, stored as a packed triangular matrix in the same storage format as :math:`A`.
**ipiv** : int, ndarray, shape :math:`\left(n\right)`
Details of the interchanges and the block structure of :math:`D`. More precisely,
if :math:`\mathrm{ipiv}[i-1] = k > 0`, :math:`d_{{ii}}` is a :math:`1\times 1` pivot block and the :math:`i`\ th row and column of :math:`A` were interchanged with the :math:`k`\ th row and column;
if :math:`\mathrm{uplo} = \texttt{'U'}` and :math:`\mathrm{ipiv}[i-2] = \mathrm{ipiv}[i-1] = -l < 0`, :math:`\begin{pmatrix}d_{{i-1,i-1}}&\bar{d}_{{i,i-1}}\\\bar{d}_{{i,i-1}}&d_{{ii}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i-1\right)`\ th row and column of :math:`A` were interchanged with the :math:`l`\ th row and column;
if :math:`\mathrm{uplo} = \texttt{'L'}` and :math:`\mathrm{ipiv}[i-1] = \mathrm{ipiv}[i] = -m < 0`, :math:`\begin{pmatrix}d_{{ii}}&d_{{i+1,i}}\\d_{{i+1,i}}&d_{{i+1,i+1}}\end{pmatrix}` is a :math:`2\times 2` pivot block and the :math:`\left(i+1\right)`\ th row and column of :math:`A` were interchanged with the :math:`m`\ th row and column.
**b** : complex, ndarray, shape :math:`\left(n, \textit{nrhs}\right)`
If no exception or warning is raised, the :math:`n\times r` solution matrix :math:`X`.
.. _f07qn-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{uplo}`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`-2`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\textit{nrhs}`.
Constraint: :math:`\textit{nrhs}\geq 0`.
**Warns**
**NagAlgorithmicWarning**
(`errno` :math:`i > 0`)
Element :math:`\langle\mathit{\boldsymbol{value}}\rangle` of the diagonal is exactly zero. The factorization has been completed, but the block diagonal matrix :math:`D` is exactly singular, so the solution could not be computed.
.. _f07qn-py2-py-notes:
**Notes**
``zspsv`` uses the diagonal pivoting method to factor :math:`A` as :math:`A = UDU^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`A = LDL^\mathrm{T}` if :math:`\mathrm{uplo} = \texttt{'L'}`, where :math:`U` (or :math:`L`) is a product of permutation and unit upper (lower) triangular matrices, :math:`D` is symmetric and block diagonal with :math:`1\times 1` and :math:`2\times 2` diagonal blocks.
The factored form of :math:`A` is then used to solve the system of equations :math:`AX = B`.
.. _f07qn-py2-py-references:
**References**
Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
Higham, N J, 2002, `Accuracy and Stability of Numerical Algorithms`, (2nd Edition), SIAM, Philadelphia
"""
raise NotImplementedError
[docs]def zspsvx(fact, uplo, nrhs, ap, afp, ipiv, b):
r"""
``zspsvx`` uses the diagonal pivoting factorization
.. math::
A = UDU^\mathrm{T}\quad \text{ or }\quad A = LDL^\mathrm{T}
to compute the solution to a complex system of linear equations
.. math::
AX = B\text{,}
where :math:`A` is an :math:`n\times n` symmetric matrix stored in packed format and :math:`X` and :math:`B` are :math:`n\times r` matrices.
Error bounds on the solution and a condition estimate are also provided.
.. _f07qp-py2-py-doc:
For full information please refer to the NAG Library document for f07qp
https://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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://support.nag.com/numeric/nl/nagdoc_30.1/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
"""
raise NotImplementedError
[docs]def zspcon(uplo, ap, ipiv, anorm):
r"""
``zspcon`` estimates the condition number of a complex symmetric matrix :math:`A`, where :math:`A` has been factorized by :meth:`zsptrf`, using packed storage.
.. _f07qu-py2-py-doc:
For full information please refer to the NAG Library document for f07qu
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07quf.html
.. _f07qu-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:`zsptrf`.
**ipiv** : int, array-like, shape :math:`\left(n\right)`
Details of the interchanges and the block structure of :math:`D`, as returned by :meth:`zsptrf`.
**anorm** : float
The :math:`1`-norm of the **original** matrix :math:`A`, which may be computed by calling :meth:`blas.zlansp <naginterfaces.library.blas.zlansp>` with its argument :math:`{\textit{norm}} = \texttt{'1'}`. :math:`\mathrm{anorm}` must be computed either **before** calling :meth:`zsptrf` 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.
.. _f07qu-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`.
.. _f07qu-py2-py-notes:
**Notes**
``zspcon`` 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.zlansp <naginterfaces.library.blas.zlansp>` to compute :math:`\left\lVert A\right\rVert_1` and a call to :meth:`zsptrf` 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`.
.. _f07qu-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 zsprfs(uplo, n, ap, afp, ipiv, b, x):
r"""
``zsprfs`` returns error bounds for the solution of a complex symmetric 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.
.. _f07qv-py2-py-doc:
For full information please refer to the NAG Library document for f07qv
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07qvf.html
.. _f07qv-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 symmetric matrix :math:`A` as supplied to :meth:`zsptrf`.
**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:`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`.
**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:`zsptrs`.
**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`.
.. _f07qv-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`.
.. _f07qv-py2-py-notes:
**Notes**
``zsprfs`` 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`, 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 ``zsprfs`` 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://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07intro.html>`__.
.. _f07qv-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 zsptri(uplo, n, ap, ipiv):
r"""
``zsptri`` computes the inverse of a complex symmetric matrix :math:`A`, where :math:`A` has been factorized by :meth:`zsptrf`, using packed storage.
.. _f07qw-py2-py-doc:
For full information please refer to the NAG Library document for f07qw
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07qwf.html
.. _f07qw-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`.
**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}`.
.. _f07qw-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.
.. _f07qw-py2-py-notes:
**Notes**
``zsptri`` is used to compute the inverse of a complex symmetric matrix :math:`A`, 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}` 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}`.
.. _f07qw-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 dtrtrs(uplo, trans, diag, a, b):
r"""
``dtrtrs`` solves a real triangular system of linear equations with multiple right-hand sides, :math:`AX = B` or :math:`A^\mathrm{T}X = B`.
.. _f07te-py2-py-doc:
For full information please refer to the NAG Library document for f07te
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07tef.html
.. _f07te-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**trans** : str, length 1
Indicates the form of the equations.
:math:`\mathrm{trans} = \texttt{'N'}`
The equations are of the form :math:`AX = B`.
:math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}`
The equations are of the form :math:`A^\mathrm{T}X = B`.
**diag** : str, length 1
Indicates whether :math:`A` is a nonunit or unit triangular matrix.
:math:`\mathrm{diag} = \texttt{'N'}`
:math:`A` is a nonunit triangular matrix.
:math:`\mathrm{diag} = \texttt{'U'}`
:math:`A` is a unit triangular matrix; the diagonal elements are not referenced and are assumed to be :math:`1`.
**a** : float, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` triangular 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**
**b** : float, ndarray, shape :math:`\left(n, \textit{nrhs}\right)`
The :math:`n\times r` solution matrix :math:`X`.
.. _f07te-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{trans}`.
Constraint: :math:`\mathrm{trans} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{diag}`.
Constraint: :math:`\mathrm{diag} = \texttt{'N'}` or :math:`\texttt{'U'}`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-5`)
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. :math:`A` is singular and the solution has not been computed.
.. _f07te-py2-py-notes:
**Notes**
``dtrtrs`` solves a real triangular system of linear equations :math:`AX = B` or :math:`A^\mathrm{T}X = B`.
.. _f07te-py2-py-references:
**References**
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
Higham, N J, 1989, `The accuracy of solutions to triangular systems`, SIAM J. Numer. Anal. (26), 1252--1265
"""
raise NotImplementedError
[docs]def dtrcon(norm, uplo, diag, n, a):
r"""
``dtrcon`` estimates the condition number of a real triangular matrix.
.. _f07tg-py2-py-doc:
For full information please refer to the NAG Library document for f07tg
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07tgf.html
.. _f07tg-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.
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**diag** : str, length 1
Indicates whether :math:`A` is a nonunit or unit triangular matrix.
:math:`\mathrm{diag} = \texttt{'N'}`
:math:`A` is a nonunit triangular matrix.
:math:`\mathrm{diag} = \texttt{'U'}`
:math:`A` is a unit triangular matrix; the diagonal elements are not referenced and are assumed to be :math:`1`.
**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` triangular 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 if the estimate underflows. If :math:`\mathrm{rcond}` is less than machine precision, :math:`A` is singular to working precision.
.. _f07tg-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{uplo}`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{diag}`.
Constraint: :math:`\mathrm{diag} = \texttt{'N'}` or :math:`\texttt{'U'}`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\mathrm{n}`.
Constraint: :math:`\mathrm{n}\geq 0`.
.. _f07tg-py2-py-notes:
**Notes**
``dtrcon`` estimates the condition number of a real triangular 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 computes :math:`\left\lVert A\right\rVert_1` or :math:`\left\lVert A\right\rVert_\infty` exactly, and 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`.
.. _f07tg-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 dtrrfs(uplo, trans, diag, n, a, b, x):
r"""
``dtrrfs`` returns error bounds for the solution of a real triangular system of linear equations with multiple right-hand sides, :math:`AX = B` or :math:`A^\mathrm{T}X = B`.
.. _f07th-py2-py-doc:
For full information please refer to the NAG Library document for f07th
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07thf.html
.. _f07th-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**trans** : str, length 1
Indicates the form of the equations.
:math:`\mathrm{trans} = \texttt{'N'}`
The equations are of the form :math:`AX = B`.
:math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}`
The equations are of the form :math:`A^\mathrm{T}X = B`.
**diag** : str, length 1
Indicates whether :math:`A` is a nonunit or unit triangular matrix.
:math:`\mathrm{diag} = \texttt{'N'}`
:math:`A` is a nonunit triangular matrix.
:math:`\mathrm{diag} = \texttt{'U'}`
:math:`A` is a unit triangular matrix; the diagonal elements are not referenced and are assumed to be :math:`1`.
**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` triangular matrix :math:`A`.
**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:`dtrtrs`.
**Returns**
**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`.
.. _f07th-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{trans}`.
Constraint: :math:`\mathrm{trans} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{diag}`.
Constraint: :math:`\mathrm{diag} = \texttt{'N'}` or :math:`\texttt{'U'}`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\mathrm{n}`.
Constraint: :math:`\mathrm{n}\geq 0`.
(`errno` :math:`-5`)
On entry, error in parameter :math:`\textit{nrhs}`.
Constraint: :math:`\textit{nrhs}\geq 0`.
.. _f07th-py2-py-notes:
**Notes**
``dtrrfs`` returns the backward errors and estimated bounds on the forward errors for the solution of a real triangular 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 ``dtrrfs`` 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://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07intro.html>`__.
.. _f07th-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 dtrtri(uplo, diag, a):
r"""
``dtrtri`` computes the inverse of a real triangular matrix.
.. _f07tj-py2-py-doc:
For full information please refer to the NAG Library document for f07tj
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07tjf.html
.. _f07tj-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**diag** : str, length 1
Indicates whether :math:`A` is a nonunit or unit triangular matrix.
:math:`\mathrm{diag} = \texttt{'N'}`
:math:`A` is a nonunit triangular matrix.
:math:`\mathrm{diag} = \texttt{'U'}`
:math:`A` is a unit triangular matrix; the diagonal elements are not referenced and are assumed to be :math:`1`.
**a** : float, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` triangular matrix :math:`A`.
**Returns**
**a** : float, ndarray, shape :math:`\left(n, n\right)`
:math:`A` is overwritten by :math:`A^{-1}`, using the same storage format as described above.
.. _f07tj-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{diag}`.
Constraint: :math:`\mathrm{diag} = \texttt{'N'}` or :math:`\texttt{'U'}`.
(`errno` :math:`-3`)
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:`A` is singular its inverse cannot be computed.
.. _f07tj-py2-py-notes:
**Notes**
``dtrtri`` forms the inverse of a real triangular matrix :math:`A`.
Note that the inverse of an upper (lower) triangular matrix is also upper (lower) triangular.
.. _f07tj-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 ztrtrs(uplo, trans, diag, a, b):
r"""
``ztrtrs`` solves a complex triangular 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`.
.. _f07ts-py2-py-doc:
For full information please refer to the NAG Library document for f07ts
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07tsf.html
.. _f07ts-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**trans** : str, length 1
Indicates the form of the equations.
:math:`\mathrm{trans} = \texttt{'N'}`
The equations are of the form :math:`AX = B`.
:math:`\mathrm{trans} = \texttt{'T'}`
The equations are of the form :math:`A^\mathrm{T}X = B`.
:math:`\mathrm{trans} = \texttt{'C'}`
The equations are of the form :math:`A^\mathrm{H}X = B`.
**diag** : str, length 1
Indicates whether :math:`A` is a nonunit or unit triangular matrix.
:math:`\mathrm{diag} = \texttt{'N'}`
:math:`A` is a nonunit triangular matrix.
:math:`\mathrm{diag} = \texttt{'U'}`
:math:`A` is a unit triangular matrix; the diagonal elements are not referenced and are assumed to be :math:`1`.
**a** : complex, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` triangular 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**
**b** : complex, ndarray, shape :math:`\left(n, \textit{nrhs}\right)`
The :math:`n\times r` solution matrix :math:`X`.
.. _f07ts-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{trans}`.
Constraint: :math:`\mathrm{trans} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{diag}`.
Constraint: :math:`\mathrm{diag} = \texttt{'N'}` or :math:`\texttt{'U'}`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-5`)
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. :math:`A` is singular and the solution has not been computed.
.. _f07ts-py2-py-notes:
**Notes**
``ztrtrs`` solves a complex triangular system of linear equations :math:`AX = B`, :math:`A^\mathrm{T}X = B` or :math:`A^\mathrm{H}X = B`.
.. _f07ts-py2-py-references:
**References**
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
Higham, N J, 1989, `The accuracy of solutions to triangular systems`, SIAM J. Numer. Anal. (26), 1252--1265
"""
raise NotImplementedError
[docs]def ztrcon(norm, uplo, diag, n, a):
r"""
``ztrcon`` estimates the condition number of a complex triangular matrix.
.. _f07tu-py2-py-doc:
For full information please refer to the NAG Library document for f07tu
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07tuf.html
.. _f07tu-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.
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**diag** : str, length 1
Indicates whether :math:`A` is a nonunit or unit triangular matrix.
:math:`\mathrm{diag} = \texttt{'N'}`
:math:`A` is a nonunit triangular matrix.
:math:`\mathrm{diag} = \texttt{'U'}`
:math:`A` is a unit triangular matrix; the diagonal elements are not referenced and are assumed to be :math:`1`.
**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` triangular 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.
.. _f07tu-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{uplo}`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{diag}`.
Constraint: :math:`\mathrm{diag} = \texttt{'N'}` or :math:`\texttt{'U'}`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\mathrm{n}`.
Constraint: :math:`\mathrm{n}\geq 0`.
.. _f07tu-py2-py-notes:
**Notes**
``ztrcon`` estimates the condition number of a complex triangular 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 computes :math:`\left\lVert A\right\rVert_1` or :math:`\left\lVert A\right\rVert_\infty` exactly, and 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`.
.. _f07tu-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 ztrrfs(uplo, trans, diag, n, a, b, x):
r"""
``ztrrfs`` returns error bounds for the solution of a complex triangular 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`.
.. _f07tv-py2-py-doc:
For full information please refer to the NAG Library document for f07tv
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07tvf.html
.. _f07tv-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**trans** : str, length 1
Indicates the form of the equations.
:math:`\mathrm{trans} = \texttt{'N'}`
The equations are of the form :math:`AX = B`.
:math:`\mathrm{trans} = \texttt{'T'}`
The equations are of the form :math:`A^\mathrm{T}X = B`.
:math:`\mathrm{trans} = \texttt{'C'}`
The equations are of the form :math:`A^\mathrm{H}X = B`.
**diag** : str, length 1
Indicates whether :math:`A` is a nonunit or unit triangular matrix.
:math:`\mathrm{diag} = \texttt{'N'}`
:math:`A` is a nonunit triangular matrix.
:math:`\mathrm{diag} = \texttt{'U'}`
:math:`A` is a unit triangular matrix; the diagonal elements are not referenced and are assumed to be :math:`1`.
**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` triangular matrix :math:`A`.
**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:`ztrtrs`.
**Returns**
**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`.
.. _f07tv-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{trans}`.
Constraint: :math:`\mathrm{trans} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{diag}`.
Constraint: :math:`\mathrm{diag} = \texttt{'N'}` or :math:`\texttt{'U'}`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\mathrm{n}`.
Constraint: :math:`\mathrm{n}\geq 0`.
(`errno` :math:`-5`)
On entry, error in parameter :math:`\textit{nrhs}`.
Constraint: :math:`\textit{nrhs}\geq 0`.
.. _f07tv-py2-py-notes:
**Notes**
``ztrrfs`` returns the backward errors and estimated bounds on the forward errors for the solution of a complex triangular 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 ``ztrrfs`` 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://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07intro.html>`__.
.. _f07tv-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 ztrtri(uplo, diag, a):
r"""
``ztrtri`` computes the inverse of a complex triangular matrix.
.. _f07tw-py2-py-doc:
For full information please refer to the NAG Library document for f07tw
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07twf.html
.. _f07tw-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**diag** : str, length 1
Indicates whether :math:`A` is a nonunit or unit triangular matrix.
:math:`\mathrm{diag} = \texttt{'N'}`
:math:`A` is a nonunit triangular matrix.
:math:`\mathrm{diag} = \texttt{'U'}`
:math:`A` is a unit triangular matrix; the diagonal elements are not referenced and are assumed to be :math:`1`.
**a** : complex, array-like, shape :math:`\left(n, n\right)`
The :math:`n\times n` triangular matrix :math:`A`.
**Returns**
**a** : complex, ndarray, shape :math:`\left(n, n\right)`
:math:`A` is overwritten by :math:`A^{-1}`, using the same storage format as described above.
.. _f07tw-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{diag}`.
Constraint: :math:`\mathrm{diag} = \texttt{'N'}` or :math:`\texttt{'U'}`.
(`errno` :math:`-3`)
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:`A` is singular its inverse cannot be computed.
.. _f07tw-py2-py-notes:
**Notes**
``ztrtri`` forms the inverse of a complex triangular matrix :math:`A`.
Note that the inverse of an upper (lower) triangular matrix is also upper (lower) triangular.
.. _f07tw-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 dtptrs(uplo, trans, diag, n, ap, b):
r"""
``dtptrs`` solves a real triangular system of linear equations with multiple right-hand sides, :math:`AX = B` or :math:`A^\mathrm{T}X = B`, using packed storage.
.. _f07ue-py2-py-doc:
For full information please refer to the NAG Library document for f07ue
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07uef.html
.. _f07ue-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**trans** : str, length 1
Indicates the form of the equations.
:math:`\mathrm{trans} = \texttt{'N'}`
The equations are of the form :math:`AX = B`.
:math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}`
The equations are of the form :math:`A^\mathrm{T}X = B`.
**diag** : str, length 1
Indicates whether :math:`A` is a nonunit or unit triangular matrix.
:math:`\mathrm{diag} = \texttt{'N'}`
:math:`A` is a nonunit triangular matrix.
:math:`\mathrm{diag} = \texttt{'U'}`
:math:`A` is a unit triangular matrix; the diagonal elements are not referenced and are assumed to be :math:`1`.
**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` triangular matrix :math:`A`, packed by columns.
**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`.
.. _f07ue-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{trans}`.
Constraint: :math:`\mathrm{trans} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{diag}`.
Constraint: :math:`\mathrm{diag} = \texttt{'N'}` or :math:`\texttt{'U'}`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\mathrm{n}`.
Constraint: :math:`\mathrm{n}\geq 0`.
(`errno` :math:`-5`)
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. :math:`A` is singular and the solution has not been computed.
.. _f07ue-py2-py-notes:
**Notes**
``dtptrs`` solves a real triangular system of linear equations :math:`AX = B` or :math:`A^\mathrm{T}X = B`, using packed storage.
.. _f07ue-py2-py-references:
**References**
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
Higham, N J, 1989, `The accuracy of solutions to triangular systems`, SIAM J. Numer. Anal. (26), 1252--1265
"""
raise NotImplementedError
[docs]def dtpcon(norm, uplo, diag, n, ap):
r"""
``dtpcon`` estimates the condition number of a real triangular matrix, using packed storage.
.. _f07ug-py2-py-doc:
For full information please refer to the NAG Library document for f07ug
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07ugf.html
.. _f07ug-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.
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**diag** : str, length 1
Indicates whether :math:`A` is a nonunit or unit triangular matrix.
:math:`\mathrm{diag} = \texttt{'N'}`
:math:`A` is a nonunit triangular matrix.
:math:`\mathrm{diag} = \texttt{'U'}`
:math:`A` is a unit triangular matrix; the diagonal elements are not referenced and are assumed to be :math:`1`.
**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` triangular matrix :math:`A`, packed by columns.
**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.
.. _f07ug-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{uplo}`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{diag}`.
Constraint: :math:`\mathrm{diag} = \texttt{'N'}` or :math:`\texttt{'U'}`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\mathrm{n}`.
Constraint: :math:`\mathrm{n}\geq 0`.
.. _f07ug-py2-py-notes:
**Notes**
``dtpcon`` estimates the condition number of a real triangular matrix :math:`A`, in either the :math:`1`-norm or the :math:`\infty`-norm, using packed storage:
.. 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 computes :math:`\left\lVert A\right\rVert_1` or :math:`\left\lVert A\right\rVert_\infty` exactly, and 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`.
.. _f07ug-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 dtprfs(uplo, trans, diag, n, ap, b, x):
r"""
``dtprfs`` returns error bounds for the solution of a real triangular system of linear equations with multiple right-hand sides, :math:`AX = B` or :math:`A^\mathrm{T}X = B`, using packed storage.
.. _f07uh-py2-py-doc:
For full information please refer to the NAG Library document for f07uh
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07uhf.html
.. _f07uh-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**trans** : str, length 1
Indicates the form of the equations.
:math:`\mathrm{trans} = \texttt{'N'}`
The equations are of the form :math:`AX = B`.
:math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}`
The equations are of the form :math:`A^\mathrm{T}X = B`.
**diag** : str, length 1
Indicates whether :math:`A` is a nonunit or unit triangular matrix.
:math:`\mathrm{diag} = \texttt{'N'}`
:math:`A` is a nonunit triangular matrix.
:math:`\mathrm{diag} = \texttt{'U'}`
:math:`A` is a unit triangular matrix; the diagonal elements are not referenced and are assumed to be :math:`1`.
**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` triangular matrix :math:`A`, packed by columns.
**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:`dtptrs`.
**Returns**
**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`.
.. _f07uh-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{trans}`.
Constraint: :math:`\mathrm{trans} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{diag}`.
Constraint: :math:`\mathrm{diag} = \texttt{'N'}` or :math:`\texttt{'U'}`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\mathrm{n}`.
Constraint: :math:`\mathrm{n}\geq 0`.
(`errno` :math:`-5`)
On entry, error in parameter :math:`\textit{nrhs}`.
Constraint: :math:`\textit{nrhs}\geq 0`.
.. _f07uh-py2-py-notes:
**Notes**
``dtprfs`` returns the backward errors and estimated bounds on the forward errors for the solution of a real triangular system of linear equations with multiple right-hand sides :math:`AX = B` or :math:`A^\mathrm{T}X = 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 ``dtprfs`` 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://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07intro.html>`__.
.. _f07uh-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 dtptri(uplo, diag, n, ap):
r"""
``dtptri`` computes the inverse of a real triangular matrix, using packed storage.
.. _f07uj-py2-py-doc:
For full information please refer to the NAG Library document for f07uj
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07ujf.html
.. _f07uj-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**diag** : str, length 1
Indicates whether :math:`A` is a nonunit or unit triangular matrix.
:math:`\mathrm{diag} = \texttt{'N'}`
:math:`A` is a nonunit triangular matrix.
:math:`\mathrm{diag} = \texttt{'U'}`
:math:`A` is a unit triangular matrix; the diagonal elements are not referenced and are assumed to be :math:`1`.
**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` triangular 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 :math:`A^{-1}`, using the same storage format as described above.
.. _f07uj-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{diag}`.
Constraint: :math:`\mathrm{diag} = \texttt{'N'}` or :math:`\texttt{'U'}`.
(`errno` :math:`-3`)
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:`A` is singular its inverse cannot be computed.
.. _f07uj-py2-py-notes:
**Notes**
``dtptri`` forms the inverse of a real triangular matrix :math:`A`, using packed storage.
Note that the inverse of an upper (lower) triangular matrix is also upper (lower) triangular.
.. _f07uj-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 ztptrs(uplo, trans, diag, n, ap, b):
r"""
``ztptrs`` solves a complex triangular 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`, using packed storage.
.. _f07us-py2-py-doc:
For full information please refer to the NAG Library document for f07us
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07usf.html
.. _f07us-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**trans** : str, length 1
Indicates the form of the equations.
:math:`\mathrm{trans} = \texttt{'N'}`
The equations are of the form :math:`AX = B`.
:math:`\mathrm{trans} = \texttt{'T'}`
The equations are of the form :math:`A^\mathrm{T}X = B`.
:math:`\mathrm{trans} = \texttt{'C'}`
The equations are of the form :math:`A^\mathrm{H}X = B`.
**diag** : str, length 1
Indicates whether :math:`A` is a nonunit or unit triangular matrix.
:math:`\mathrm{diag} = \texttt{'N'}`
:math:`A` is a nonunit triangular matrix.
:math:`\mathrm{diag} = \texttt{'U'}`
:math:`A` is a unit triangular matrix; the diagonal elements are not referenced and are assumed to be :math:`1`.
**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` triangular matrix :math:`A`, packed by columns.
**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`.
.. _f07us-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{trans}`.
Constraint: :math:`\mathrm{trans} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{diag}`.
Constraint: :math:`\mathrm{diag} = \texttt{'N'}` or :math:`\texttt{'U'}`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\mathrm{n}`.
Constraint: :math:`\mathrm{n}\geq 0`.
(`errno` :math:`-5`)
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. :math:`A` is singular and the solution has not been computed.
.. _f07us-py2-py-notes:
**Notes**
``ztptrs`` solves a complex triangular system of linear equations :math:`AX = B`, :math:`A^\mathrm{T}X = B` or :math:`A^\mathrm{H}X = B`, using packed storage.
.. _f07us-py2-py-references:
**References**
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
Higham, N J, 1989, `The accuracy of solutions to triangular systems`, SIAM J. Numer. Anal. (26), 1252--1265
"""
raise NotImplementedError
[docs]def ztpcon(norm, uplo, diag, n, ap):
r"""
``ztpcon`` estimates the condition number of a complex triangular matrix, using packed storage.
.. _f07uu-py2-py-doc:
For full information please refer to the NAG Library document for f07uu
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07uuf.html
.. _f07uu-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.
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**diag** : str, length 1
Indicates whether :math:`A` is a nonunit or unit triangular matrix.
:math:`\mathrm{diag} = \texttt{'N'}`
:math:`A` is a nonunit triangular matrix.
:math:`\mathrm{diag} = \texttt{'U'}`
:math:`A` is a unit triangular matrix; the diagonal elements are not referenced and are assumed to be :math:`1`.
**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` triangular matrix :math:`A`, packed by columns.
**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.
.. _f07uu-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{uplo}`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{diag}`.
Constraint: :math:`\mathrm{diag} = \texttt{'N'}` or :math:`\texttt{'U'}`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\mathrm{n}`.
Constraint: :math:`\mathrm{n}\geq 0`.
.. _f07uu-py2-py-notes:
**Notes**
``ztpcon`` estimates the condition number of a complex triangular matrix :math:`A`, in either the :math:`1`-norm or the :math:`\infty`-norm, using packed storage:
.. 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 computes :math:`\left\lVert A\right\rVert_1` or :math:`\left\lVert A\right\rVert_\infty` exactly, and 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`.
.. _f07uu-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 ztprfs(uplo, trans, diag, n, ap, b, x):
r"""
``ztprfs`` returns error bounds for the solution of a complex triangular 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`, using packed storage.
.. _f07uv-py2-py-doc:
For full information please refer to the NAG Library document for f07uv
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07uvf.html
.. _f07uv-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**trans** : str, length 1
Indicates the form of the equations.
:math:`\mathrm{trans} = \texttt{'N'}`
The equations are of the form :math:`AX = B`.
:math:`\mathrm{trans} = \texttt{'T'}`
The equations are of the form :math:`A^\mathrm{T}X = B`.
:math:`\mathrm{trans} = \texttt{'C'}`
The equations are of the form :math:`A^\mathrm{H}X = B`.
**diag** : str, length 1
Indicates whether :math:`A` is a nonunit or unit triangular matrix.
:math:`\mathrm{diag} = \texttt{'N'}`
:math:`A` is a nonunit triangular matrix.
:math:`\mathrm{diag} = \texttt{'U'}`
:math:`A` is a unit triangular matrix; the diagonal elements are not referenced and are assumed to be :math:`1`.
**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` triangular matrix :math:`A`, packed by columns.
**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:`ztptrs`.
**Returns**
**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`.
.. _f07uv-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{trans}`.
Constraint: :math:`\mathrm{trans} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{diag}`.
Constraint: :math:`\mathrm{diag} = \texttt{'N'}` or :math:`\texttt{'U'}`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\mathrm{n}`.
Constraint: :math:`\mathrm{n}\geq 0`.
(`errno` :math:`-5`)
On entry, error in parameter :math:`\textit{nrhs}`.
Constraint: :math:`\textit{nrhs}\geq 0`.
.. _f07uv-py2-py-notes:
**Notes**
``ztprfs`` returns the backward errors and estimated bounds on the forward errors for the solution of a complex triangular 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`, 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 ``ztprfs`` 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://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07intro.html>`__.
.. _f07uv-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 ztptri(uplo, diag, n, ap):
r"""
``ztptri`` computes the inverse of a complex triangular matrix, using packed storage.
.. _f07uw-py2-py-doc:
For full information please refer to the NAG Library document for f07uw
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07uwf.html
.. _f07uw-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**diag** : str, length 1
Indicates whether :math:`A` is a nonunit or unit triangular matrix.
:math:`\mathrm{diag} = \texttt{'N'}`
:math:`A` is a nonunit triangular matrix.
:math:`\mathrm{diag} = \texttt{'U'}`
:math:`A` is a unit triangular matrix; the diagonal elements are not referenced and are assumed to be :math:`1`.
**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` triangular 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 :math:`A^{-1}`, using the same storage format as described above.
.. _f07uw-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{diag}`.
Constraint: :math:`\mathrm{diag} = \texttt{'N'}` or :math:`\texttt{'U'}`.
(`errno` :math:`-3`)
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:`A` is singular its inverse cannot be computed.
.. _f07uw-py2-py-notes:
**Notes**
``ztptri`` forms the inverse of a complex triangular matrix :math:`A`, using packed storage.
Note that the inverse of an upper (lower) triangular matrix is also upper (lower) triangular.
.. _f07uw-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 dtbtrs(uplo, trans, diag, kd, ab, b):
r"""
``dtbtrs`` solves a real triangular band system of linear equations with multiple right-hand sides, :math:`AX = B` or :math:`A^\mathrm{T}X = B`.
.. _f07ve-py2-py-doc:
For full information please refer to the NAG Library document for f07ve
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07vef.html
.. _f07ve-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**trans** : str, length 1
Indicates the form of the equations.
:math:`\mathrm{trans} = \texttt{'N'}`
The equations are of the form :math:`AX = B`.
:math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}`
The equations are of the form :math:`A^\mathrm{T}X = B`.
**diag** : str, length 1
Indicates whether :math:`A` is a nonunit or unit triangular matrix.
:math:`\mathrm{diag} = \texttt{'N'}`
:math:`A` is a nonunit triangular matrix.
:math:`\mathrm{diag} = \texttt{'U'}`
:math:`A` is a unit triangular matrix; the diagonal elements are not referenced and are assumed to be :math:`1`.
**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 :math:`n\times n` triangular 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**
**b** : float, ndarray, shape :math:`\left(n, \textit{nrhs}\right)`
The :math:`n\times r` solution matrix :math:`X`.
.. _f07ve-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{trans}`.
Constraint: :math:`\mathrm{trans} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{diag}`.
Constraint: :math:`\mathrm{diag} = \texttt{'N'}` or :math:`\texttt{'U'}`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-5`)
On entry, error in parameter :math:`\mathrm{kd}`.
Constraint: :math:`\mathrm{kd}\geq 0`.
(`errno` :math:`-6`)
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. :math:`A` is singular and the solution has not been computed.
.. _f07ve-py2-py-notes:
**Notes**
``dtbtrs`` solves a real triangular band system of linear equations :math:`AX = B` or :math:`A^\mathrm{T}X = B`.
.. _f07ve-py2-py-references:
**References**
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
Higham, N J, 1989, `The accuracy of solutions to triangular systems`, SIAM J. Numer. Anal. (26), 1252--1265
"""
raise NotImplementedError
[docs]def dtbcon(norm, uplo, diag, kd, ab):
r"""
``dtbcon`` estimates the condition number of a real triangular band matrix.
.. _f07vg-py2-py-doc:
For full information please refer to the NAG Library document for f07vg
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07vgf.html
.. _f07vg-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.
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**diag** : str, length 1
Indicates whether :math:`A` is a nonunit or unit triangular matrix.
:math:`\mathrm{diag} = \texttt{'N'}`
:math:`A` is a nonunit triangular matrix.
:math:`\mathrm{diag} = \texttt{'U'}`
:math:`A` is a unit triangular matrix; the diagonal elements are not referenced and are assumed to be :math:`1`.
**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 :math:`n\times n` triangular band 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.
.. _f07vg-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{uplo}`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{diag}`.
Constraint: :math:`\mathrm{diag} = \texttt{'N'}` or :math:`\texttt{'U'}`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-5`)
On entry, error in parameter :math:`\mathrm{kd}`.
Constraint: :math:`\mathrm{kd}\geq 0`.
.. _f07vg-py2-py-notes:
**Notes**
``dtbcon`` estimates the condition number of a real triangular 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 computes :math:`\left\lVert A\right\rVert_1` or :math:`\left\lVert A\right\rVert_\infty` exactly, and 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`.
.. _f07vg-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 dtbrfs(uplo, trans, diag, kd, nrhs, ab, b, x):
r"""
``dtbrfs`` returns error bounds for the solution of a real triangular band system of linear equations with multiple right-hand sides, :math:`AX = B` or :math:`A^\mathrm{T}X = B`.
.. _f07vh-py2-py-doc:
For full information please refer to the NAG Library document for f07vh
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07vhf.html
.. _f07vh-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**trans** : str, length 1
Indicates the form of the equations.
:math:`\mathrm{trans} = \texttt{'N'}`
The equations are of the form :math:`AX = B`.
:math:`\mathrm{trans} = \texttt{'T'}` or :math:`\texttt{'C'}`
The equations are of the form :math:`A^\mathrm{T}X = B`.
**diag** : str, length 1
Indicates whether :math:`A` is a nonunit or unit triangular matrix.
:math:`\mathrm{diag} = \texttt{'N'}`
:math:`A` is a nonunit triangular matrix.
:math:`\mathrm{diag} = \texttt{'U'}`
:math:`A` is a unit triangular matrix; the diagonal elements are not referenced and are assumed to be :math:`1`.
**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.
**ab** : float, array-like, shape :math:`\left(\mathrm{kd}+1, n\right)`
The :math:`n\times n` triangular band matrix :math:`A`.
**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:`dtbtrs`.
**Returns**
**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`.
.. _f07vh-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{trans}`.
Constraint: :math:`\mathrm{trans} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{diag}`.
Constraint: :math:`\mathrm{diag} = \texttt{'N'}` or :math:`\texttt{'U'}`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-5`)
On entry, error in parameter :math:`\mathrm{kd}`.
Constraint: :math:`\mathrm{kd}\geq 0`.
(`errno` :math:`-6`)
On entry, error in parameter :math:`\mathrm{nrhs}`.
Constraint: :math:`\mathrm{nrhs}\geq 0`.
.. _f07vh-py2-py-notes:
**Notes**
``dtbrfs`` returns the backward errors and estimated bounds on the forward errors for the solution of a real triangular 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 ``dtbrfs`` 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://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07intro.html>`__.
.. _f07vh-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 ztbtrs(uplo, trans, diag, kd, ab, b):
r"""
``ztbtrs`` solves a complex triangular 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`.
.. _f07vs-py2-py-doc:
For full information please refer to the NAG Library document for f07vs
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07vsf.html
.. _f07vs-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**trans** : str, length 1
Indicates the form of the equations.
:math:`\mathrm{trans} = \texttt{'N'}`
The equations are of the form :math:`AX = B`.
:math:`\mathrm{trans} = \texttt{'T'}`
The equations are of the form :math:`A^\mathrm{T}X = B`.
:math:`\mathrm{trans} = \texttt{'C'}`
The equations are of the form :math:`A^\mathrm{H}X = B`.
**diag** : str, length 1
Indicates whether :math:`A` is a nonunit or unit triangular matrix.
:math:`\mathrm{diag} = \texttt{'N'}`
:math:`A` is a nonunit triangular matrix.
:math:`\mathrm{diag} = \texttt{'U'}`
:math:`A` is a unit triangular matrix; the diagonal elements are not referenced and are assumed to be :math:`1`.
**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 :math:`n\times n` triangular 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**
**b** : complex, ndarray, shape :math:`\left(n, \textit{nrhs}\right)`
The :math:`n\times r` solution matrix :math:`X`.
.. _f07vs-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{trans}`.
Constraint: :math:`\mathrm{trans} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{diag}`.
Constraint: :math:`\mathrm{diag} = \texttt{'N'}` or :math:`\texttt{'U'}`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-5`)
On entry, error in parameter :math:`\mathrm{kd}`.
Constraint: :math:`\mathrm{kd}\geq 0`.
(`errno` :math:`-6`)
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. :math:`A` is singular and the solution has not been computed.
.. _f07vs-py2-py-notes:
**Notes**
``ztbtrs`` solves a complex triangular band system of linear equations :math:`AX = B`, :math:`A^\mathrm{T}X = B` or :math:`A^\mathrm{H}X = B`.
.. _f07vs-py2-py-references:
**References**
Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
Higham, N J, 1989, `The accuracy of solutions to triangular systems`, SIAM J. Numer. Anal. (26), 1252--1265
"""
raise NotImplementedError
[docs]def ztbcon(norm, uplo, diag, kd, ab):
r"""
``ztbcon`` estimates the condition number of a complex triangular band matrix.
.. _f07vu-py2-py-doc:
For full information please refer to the NAG Library document for f07vu
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07vuf.html
.. _f07vu-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.
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**diag** : str, length 1
Indicates whether :math:`A` is a nonunit or unit triangular matrix.
:math:`\mathrm{diag} = \texttt{'N'}`
:math:`A` is a nonunit triangular matrix.
:math:`\mathrm{diag} = \texttt{'U'}`
:math:`A` is a unit triangular matrix; the diagonal elements are not referenced and are assumed to be :math:`1`.
**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 :math:`n\times n` triangular band 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.
.. _f07vu-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{uplo}`.
Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{diag}`.
Constraint: :math:`\mathrm{diag} = \texttt{'N'}` or :math:`\texttt{'U'}`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-5`)
On entry, error in parameter :math:`\mathrm{kd}`.
Constraint: :math:`\mathrm{kd}\geq 0`.
.. _f07vu-py2-py-notes:
**Notes**
``ztbcon`` estimates the condition number of a complex triangular 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 computes :math:`\left\lVert A\right\rVert_1` or :math:`\left\lVert A\right\rVert_\infty` exactly, and 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`.
.. _f07vu-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 ztbrfs(uplo, trans, diag, kd, nrhs, ab, b, x):
r"""
``ztbrfs`` returns error bounds for the solution of a complex triangular 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`.
.. _f07vv-py2-py-doc:
For full information please refer to the NAG Library document for f07vv
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07vvf.html
.. _f07vv-py2-py-parameters:
**Parameters**
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**trans** : str, length 1
Indicates the form of the equations.
:math:`\mathrm{trans} = \texttt{'N'}`
The equations are of the form :math:`AX = B`.
:math:`\mathrm{trans} = \texttt{'T'}`
The equations are of the form :math:`A^\mathrm{T}X = B`.
:math:`\mathrm{trans} = \texttt{'C'}`
The equations are of the form :math:`A^\mathrm{H}X = B`.
**diag** : str, length 1
Indicates whether :math:`A` is a nonunit or unit triangular matrix.
:math:`\mathrm{diag} = \texttt{'N'}`
:math:`A` is a nonunit triangular matrix.
:math:`\mathrm{diag} = \texttt{'U'}`
:math:`A` is a unit triangular matrix; the diagonal elements are not referenced and are assumed to be :math:`1`.
**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.
**ab** : complex, array-like, shape :math:`\left(\mathrm{kd}+1, n\right)`
The :math:`n\times n` triangular band matrix :math:`A`.
**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:`ztbtrs`.
**Returns**
**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`.
.. _f07vv-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{trans}`.
Constraint: :math:`\mathrm{trans} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`.
(`errno` :math:`-3`)
On entry, error in parameter :math:`\mathrm{diag}`.
Constraint: :math:`\mathrm{diag} = \texttt{'N'}` or :math:`\texttt{'U'}`.
(`errno` :math:`-4`)
On entry, error in parameter :math:`\textit{n}`.
Constraint: :math:`n\geq 0`.
(`errno` :math:`-5`)
On entry, error in parameter :math:`\mathrm{kd}`.
Constraint: :math:`\mathrm{kd}\geq 0`.
(`errno` :math:`-6`)
On entry, error in parameter :math:`\mathrm{nrhs}`.
Constraint: :math:`\mathrm{nrhs}\geq 0`.
.. _f07vv-py2-py-notes:
**Notes**
``ztbrfs`` returns the backward errors and estimated bounds on the forward errors for the solution of a complex triangular 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 ``ztbrfs`` 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://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07intro.html>`__.
.. _f07vv-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 dpftrf(transr, uplo, n, ar):
r"""
``dpftrf`` computes the Cholesky factorization of a real symmetric positive definite matrix stored in Rectangular Full Packed (RFP) format.
.. _f07wd-py2-py-doc:
For full information please refer to the NAG Library document for f07wd
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07wdf.html
.. _f07wd-py2-py-parameters:
**Parameters**
**transr** : str, length 1
Specifies whether the RFP representation of :math:`A` is normal or transposed.
:math:`\mathrm{transr} = \texttt{'N'}`
The matrix :math:`A` is stored in normal RFP format.
:math:`\mathrm{transr} = \texttt{'T'}`
The matrix :math:`A` is stored in transposed RFP format.
**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, 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`.
**ar** : float, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
The upper or lower triangular part (as specified by :math:`\mathrm{uplo}`) of the :math:`n\times n` symmetric matrix :math:`A`, in either normal or transposed RFP format (as specified by :math:`\mathrm{transr}`). The storage format is described in detail in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07intro.html#recomm_32a>`__.
**Returns**
**ar** : 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`.
.. _f07wd-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{transr}`.
Constraint: :math:`\mathrm{transr} = \texttt{'N'}` or :math:`\texttt{'T'}`.
(`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`.
**Warns**
**NagAlgorithmicWarning**
(`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 matrix stored in RFP format which is not positive definite; the matrix must be treated as a full symmetric matrix, by calling :meth:`dsytrf`.
.. _f07wd-py2-py-notes:
**Notes**
``dpftrf`` 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 a lower triangular, stored in RFP format. The RFP storage format is described in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07intro.html#recomm_32a>`__.
.. _f07wd-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
Gustavson, F G, Waśniewski, J, Dongarra, J J and Langou, J, 2010, `Rectangular full packed format for Cholesky's algorithm: factorization, solution, and inversion`, ACM Trans. Math. Software (37, 2)
"""
raise NotImplementedError
[docs]def dpftrs(transr, uplo, n, ar, b):
r"""
``dpftrs`` solves a real symmetric positive definite system of linear equations with multiple right-hand sides,
.. math::
AX = B\text{,}
using the Cholesky factorization computed by :meth:`dpftrf` stored in Rectangular Full Packed (RFP) format.
.. _f07we-py2-py-doc:
For full information please refer to the NAG Library document for f07we
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07wef.html
.. _f07we-py2-py-parameters:
**Parameters**
**transr** : str, length 1
Specifies whether the RFP representation of :math:`A` is normal or transposed.
:math:`\mathrm{transr} = \texttt{'N'}`
The matrix :math:`A` is stored in normal RFP format.
:math:`\mathrm{transr} = \texttt{'T'}`
The matrix :math:`A` is stored in transposed RFP format.
**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`.
**ar** : float, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
The Cholesky factorization of :math:`A` stored in RFP format, as returned by :meth:`dpftrf`.
**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`.
.. _f07we-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{transr}`.
Constraint: :math:`\mathrm{transr} = \texttt{'N'}` or :math:`\texttt{'T'}`.
(`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:`\textit{nrhs}`.
Constraint: :math:`\textit{nrhs}\geq 0`.
.. _f07we-py2-py-notes:
**Notes**
``dpftrs`` 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:`dpftrf` which computes the Cholesky factorization of :math:`A`, stored in RFP format. The RFP storage format is described in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07intro.html#recomm_32a>`__. 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`.
.. _f07we-py2-py-references:
**References**
Gustavson, F G, Waśniewski, J, Dongarra, J J and Langou, J, 2010, `Rectangular full packed format for Cholesky's algorithm: factorization, solution, and inversion`, ACM Trans. Math. Software (37, 2)
"""
raise NotImplementedError
[docs]def dpftri(transr, uplo, n, ar):
r"""
``dpftri`` computes the inverse of a real symmetric positive definite matrix using the Cholesky factorization computed by :meth:`dpftrf` stored in Rectangular Full Packed (RFP) format.
.. _f07wj-py2-py-doc:
For full information please refer to the NAG Library document for f07wj
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07wjf.html
.. _f07wj-py2-py-parameters:
**Parameters**
**transr** : str, length 1
Specifies whether the RFP representation of :math:`A` is normal or transposed.
:math:`\mathrm{transr} = \texttt{'N'}`
The matrix :math:`A` is stored in normal RFP format.
:math:`\mathrm{transr} = \texttt{'T'}`
The matrix :math:`A` is stored in transposed RFP format.
**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`.
**ar** : float, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
The Cholesky factorization of :math:`A` stored in RFP format, as returned by :meth:`dpftrf`.
**Returns**
**ar** : 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}` stored in RFP format.
.. _f07wj-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{transr}`.
Constraint: :math:`\mathrm{transr} = \texttt{'N'}` or :math:`\texttt{'T'}`.
(`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`.
**Warns**
**NagAlgorithmicWarning**
(`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 invert a symmetric matrix stored in RFP format which is not positive definite; the matrix must be treated as a full symmetric matrix, by calling :meth:`dsytri`.
.. _f07wj-py2-py-notes:
**Notes**
``dpftri`` is used to compute the inverse of a real symmetric positive definite matrix :math:`A`, stored in RFP format. The RFP storage format is described in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07intro.html#recomm_32a>`__. The function must be preceded by a call to :meth:`dpftrf`, 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)`.
.. _f07wj-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
Gustavson, F G, Waśniewski, J, Dongarra, J J and Langou, J, 2010, `Rectangular full packed format for Cholesky's algorithm: factorization, solution, and inversion`, ACM Trans. Math. Software (37, 2)
"""
raise NotImplementedError
[docs]def dtftri(transr, uplo, diag, n, ar):
r"""
``dtftri`` computes the inverse of a real triangular matrix stored in Rectangular Full Packed (RFP) format.
.. _f07wk-py2-py-doc:
For full information please refer to the NAG Library document for f07wk
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07wkf.html
.. _f07wk-py2-py-parameters:
**Parameters**
**transr** : str, length 1
Specifies whether the RFP representation of :math:`A` is normal or transposed.
:math:`\mathrm{transr} = \texttt{'N'}`
The matrix :math:`A` is stored in normal RFP format.
:math:`\mathrm{transr} = \texttt{'T'}`
The matrix :math:`A` is stored in transposed RFP format.
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**diag** : str, length 1
Indicates whether :math:`A` is a nonunit or unit triangular matrix.
:math:`\mathrm{diag} = \texttt{'N'}`
:math:`A` is a nonunit triangular matrix.
:math:`\mathrm{diag} = \texttt{'U'}`
:math:`A` is a unit triangular matrix; the diagonal elements are not referenced and are assumed to be :math:`1`.
**n** : int
:math:`n`, the order of the matrix :math:`A`.
**ar** : float, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
The upper or lower triangular part (as specified by :math:`\mathrm{uplo}`) of the :math:`n\times n` symmetric matrix :math:`A`, in either normal or transposed RFP format (as specified by :math:`\mathrm{transr}`). The storage format is described in detail in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07intro.html#recomm_32a>`__.
**Returns**
**ar** : float, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
:math:`A` is overwritten by :math:`A^{-1}`, in the same storage format as :math:`A`.
.. _f07wk-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{transr}`.
Constraint: :math:`\mathrm{transr} = \texttt{'N'}` or :math:`\texttt{'T'}`.
(`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{diag}`.
Constraint: :math:`\mathrm{diag} = \texttt{'N'}` or :math:`\texttt{'U'}`.
(`errno` :math:`-4`)
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 :math:`A` is exactly zero. :math:`A` is singular its inverse cannot be computed.
.. _f07wk-py2-py-notes:
**Notes**
``dtftri`` forms the inverse of a real triangular matrix :math:`A`, stored using RFP format. The RFP storage format is described in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07intro.html#recomm_32a>`__. Note that the inverse of an upper (lower) triangular matrix is also upper (lower) triangular.
.. _f07wk-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
Gustavson, F G, Waśniewski, J, Dongarra, J J and Langou, J, 2010, `Rectangular full packed format for Cholesky's algorithm: factorization, solution, and inversion`, ACM Trans. Math. Software (37, 2)
"""
raise NotImplementedError
[docs]def zpftrf(transr, uplo, n, ar):
r"""
``zpftrf`` computes the Cholesky factorization of a complex Hermitian positive definite matrix stored in Rectangular Full Packed (RFP) format.
.. _f07wr-py2-py-doc:
For full information please refer to the NAG Library document for f07wr
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07wrf.html
.. _f07wr-py2-py-parameters:
**Parameters**
**transr** : str, length 1
Specifies whether the normal RFP representation of :math:`A` or its conjugate transpose is stored.
:math:`\mathrm{transr} = \texttt{'N'}`
The matrix :math:`A` is stored in normal RFP format.
:math:`\mathrm{transr} = \texttt{'C'}`
The conjugate transpose of the RFP representation of the matrix :math:`A` is stored.
**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, 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`.
**ar** : complex, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
The upper or lower triangular part (as specified by :math:`\mathrm{uplo}`) of the :math:`n\times n` Hermitian matrix :math:`A`, in either normal or transposed RFP format (as specified by :math:`\mathrm{transr}`). The storage format is described in detail in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07intro.html#recomm_32a>`__.
**Returns**
**ar** : 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`.
.. _f07wr-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{transr}`.
Constraint: :math:`\mathrm{transr} = \texttt{'N'}` or :math:`\texttt{'C'}`.
(`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:`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 matrix stored in RFP format which is not positive definite; the matrix must be treated as a full Hermitian matrix, by calling :meth:`zhetrf`.
.. _f07wr-py2-py-notes:
**Notes**
``zpftrf`` 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 a lower triangular, stored in RFP format. The RFP storage format is described in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07intro.html#recomm_32a>`__.
.. _f07wr-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
Gustavson, F G, Waśniewski, J, Dongarra, J J and Langou, J, 2010, `Rectangular full packed format for Cholesky's algorithm: factorization, solution, and inversion`, ACM Trans. Math. Software (37, 2)
"""
raise NotImplementedError
[docs]def zpftrs(transr, uplo, n, ar, b):
r"""
``zpftrs`` solves a complex Hermitian positive definite system of linear equations with multiple right-hand sides,
.. math::
AX = B\text{,}
using the Cholesky factorization computed by :meth:`zpftrf` stored in Rectangular Full Packed (RFP) format.
.. _f07ws-py2-py-doc:
For full information please refer to the NAG Library document for f07ws
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07wsf.html
.. _f07ws-py2-py-parameters:
**Parameters**
**transr** : str, length 1
Specifies whether the normal RFP representation of :math:`A` or its conjugate transpose is stored.
:math:`\mathrm{transr} = \texttt{'N'}`
The matrix :math:`A` is stored in normal RFP format.
:math:`\mathrm{transr} = \texttt{'C'}`
The conjugate transpose of the RFP representation of the matrix :math:`A` is stored.
**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`.
**ar** : complex, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
The Cholesky factorization of :math:`A` stored in RFP format, as returned by :meth:`zpftrf`.
**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`.
.. _f07ws-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{transr}`.
Constraint: :math:`\mathrm{transr} = \texttt{'N'}` or :math:`\texttt{'C'}`.
(`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:`\textit{nrhs}`.
Constraint: :math:`\textit{nrhs}\geq 0`.
.. _f07ws-py2-py-notes:
**Notes**
``zpftrs`` 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:`zpftrf` which computes the Cholesky factorization of :math:`A`, stored in RFP format. The RFP storage format is described in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07intro.html#recomm_32a>`__. 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`.
.. _f07ws-py2-py-references:
**References**
Gustavson, F G, Waśniewski, J, Dongarra, J J and Langou, J, 2010, `Rectangular full packed format for Cholesky's algorithm: factorization, solution, and inversion`, ACM Trans. Math. Software (37, 2)
"""
raise NotImplementedError
[docs]def zpftri(transr, uplo, n, ar):
r"""
``zpftri`` computes the inverse of a complex Hermitian positive definite matrix using the Cholesky factorization computed by :meth:`zpftrf` stored in Rectangular Full Packed (RFP) format.
.. _f07ww-py2-py-doc:
For full information please refer to the NAG Library document for f07ww
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07wwf.html
.. _f07ww-py2-py-parameters:
**Parameters**
**transr** : str, length 1
Specifies whether the normal RFP representation of :math:`A` or its conjugate transpose is stored.
:math:`\mathrm{transr} = \texttt{'N'}`
The matrix :math:`A` is stored in normal RFP format.
:math:`\mathrm{transr} = \texttt{'C'}`
The conjugate transpose of the RFP representation of the matrix :math:`A` is stored.
**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`.
**ar** : complex, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
The Cholesky factorization of :math:`A` stored in RFP format, as returned by :meth:`zpftrf`.
**Returns**
**ar** : 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}` stored in RFP format.
.. _f07ww-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{transr}`.
Constraint: :math:`\mathrm{transr} = \texttt{'N'}` or :math:`\texttt{'C'}`.
(`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:`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 invert a Hermitian matrix stored in RFP format which is not positive definite; the matrix must be treated as a full Hermitian matrix, by calling :meth:`zhetri`.
.. _f07ww-py2-py-notes:
**Notes**
``zpftri`` is used to compute the inverse of a complex Hermitian positive definite matrix :math:`A`, stored in RFP format. The RFP storage format is described in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07intro.html#recomm_32a>`__. The function must be preceded by a call to :meth:`zpftrf`, 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)`.
.. _f07ww-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
Gustavson, F G, Waśniewski, J, Dongarra, J J and Langou, J, 2010, `Rectangular full packed format for Cholesky's algorithm: factorization, solution, and inversion`, ACM Trans. Math. Software (37, 2)
"""
raise NotImplementedError
[docs]def ztftri(transr, uplo, diag, n, ar):
r"""
``ztftri`` computes the inverse of a complex triangular matrix stored in Rectangular Full Packed (RFP) format.
.. _f07wx-py2-py-doc:
For full information please refer to the NAG Library document for f07wx
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07wxf.html
.. _f07wx-py2-py-parameters:
**Parameters**
**transr** : str, length 1
Specifies whether the normal RFP representation of :math:`A` or its conjugate transpose is stored.
:math:`\mathrm{transr} = \texttt{'N'}`
The matrix :math:`A` is stored in normal RFP format.
:math:`\mathrm{transr} = \texttt{'C'}`
The conjugate transpose of the RFP representation of the matrix :math:`A` is stored.
**uplo** : str, length 1
Specifies whether :math:`A` is upper or lower triangular.
:math:`\mathrm{uplo} = \texttt{'U'}`
:math:`A` is upper triangular.
:math:`\mathrm{uplo} = \texttt{'L'}`
:math:`A` is lower triangular.
**diag** : str, length 1
Indicates whether :math:`A` is a nonunit or unit triangular matrix.
:math:`\mathrm{diag} = \texttt{'N'}`
:math:`A` is a nonunit triangular matrix.
:math:`\mathrm{diag} = \texttt{'U'}`
:math:`A` is a unit triangular matrix; the diagonal elements are not referenced and are assumed to be :math:`1`.
**n** : int
:math:`n`, the order of the matrix :math:`A`.
**ar** : complex, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
The upper or lower triangular part (as specified by :math:`\mathrm{uplo}`) of the :math:`n\times n` Hermitian matrix :math:`A`, in either normal or transposed RFP format (as specified by :math:`\mathrm{transr}`). The storage format is described in detail in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07intro.html#recomm_32a>`__.
**Returns**
**ar** : complex, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
:math:`A` is overwritten by :math:`A^{-1}`, in the same storage format as :math:`A`.
.. _f07wx-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`-1`)
On entry, error in parameter :math:`\mathrm{transr}`.
Constraint: :math:`\mathrm{transr} = \texttt{'N'}` or :math:`\texttt{'C'}`.
(`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{diag}`.
Constraint: :math:`\mathrm{diag} = \texttt{'N'}` or :math:`\texttt{'U'}`.
(`errno` :math:`-4`)
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 :math:`A` is exactly zero. :math:`A` is singular its inverse cannot be computed.
.. _f07wx-py2-py-notes:
**Notes**
``ztftri`` forms the inverse of a complex triangular matrix :math:`A`, stored using RFP format. The RFP storage format is described in `the F07 Introduction <https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f07/f07intro.html#recomm_32a>`__. Note that the inverse of an upper (lower) triangular matrix is also upper (lower) triangular.
.. _f07wx-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
Gustavson, F G, Waśniewski, J, Dongarra, J J and Langou, J, 2010, `Rectangular full packed format for Cholesky's algorithm: factorization, solution, and inversion`, ACM Trans. Math. Software (37, 2)
"""
raise NotImplementedError