# Source code for naginterfaces.library.lapackeig

# -*- coding: utf-8 -*-
r"""
Module Summary
--------------
Interfaces for the NAG Mark 29.2 lapackeig Chapter.

lapackeig - Least Squares and Eigenvalue Problems (LAPACK)

This module provides functions for the solution of linear least squares problems, eigenvalue problems and singular value problems, as well as associated computations.
It provides functions for:

solution of linear least squares problems;

solution of symmetric eigenvalue problems;

solution of nonsymmetric eigenvalue problems;

solution of singular value problems;

solution of generalized linear least squares problems;

solution of generalized symmetric-definite eigenvalue problems;

solution of generalized nonsymmetric eigenvalue problems;

solution of generalized singular value problems;

matrix factorizations associated with the above problems;

estimating condition numbers of eigenvalue and eigenvector problems;

estimating the numerical rank of a matrix;

solution of the Sylvester matrix equation.

Functions are provided for both real and complex data.

For a general introduction to the solution of linear least squares problems, you should turn first to submodule :mod:~naginterfaces.library.linsys.
The decision trees, at the end of submodule :mod:~naginterfaces.library.linsys, direct you to the most appropriate functions in submodule :mod:~naginterfaces.library.linsys or submodule lapackeig. Submodule :mod:~naginterfaces.library.linsys and submodule lapackeig contain Black Box (or driver) functions which enable standard linear least squares problems to be solved by a call to a single function.

For a general introduction to eigenvalue and singular value problems, you should turn first to submodule :mod:~naginterfaces.library.eigen.
The decision trees, at the end of submodule :mod:~naginterfaces.library.eigen, direct you to the most appropriate functions in submodule :mod:~naginterfaces.library.eigen or submodule lapackeig. Submodule :mod:~naginterfaces.library.eigen and submodule lapackeig contain Black Box (or driver) functions which enable standard types of problem to be solved by a call to a single function.
Often functions in submodule :mod:~naginterfaces.library.eigen call submodule lapackeig functions to perform the necessary computational tasks.

The functions in this module (submodule lapackeig) handle only dense, band, tridiagonal and Hessenberg matrices (not matrices with more specialised structures, or general sparse matrices).
The tables in Available Functions <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html#available>__ and the decision trees in Decision Trees <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html#dtree>__ direct you to the most appropriate functions in submodule lapackeig.

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.

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

**Back transformation of eigenvectors from those of balanced forms**

complex matrix: :meth:zgebak

real matrix: :meth:dgebak

**Back transformation of generalized eigenvectors from those of balanced forms**

complex matrix: :meth:zggbak

real matrix: :meth:dggbak

**Balancing**

complex general matrix: :meth:zgebal

complex general matrix pair: :meth:zggbal

real general matrix: :meth:dgebal

real general matrix pair: :meth:dggbal

**Eigenvalue problems for condensed forms of matrices**

complex Hermitian matrix

eigenvalues and eigenvectors

band matrix

all/selected eigenvalues and eigenvectors by root-free :math:QR algorithm: :meth:zhbevx

all eigenvalues and eigenvectors by a divide-and-conquer algorithm, using packed storage: :meth:zhbevd

all eigenvalues and eigenvectors by root-free :math:QR algorithm: :meth:zhbev

general matrix

all/selected eigenvalues and eigenvectors by root-free :math:QR algorithm: :meth:zheevx

all/selected eigenvalues and eigenvectors by root-free :math:QR algorithm, using packed storage: :meth:zhpevx

all/selected eigenvalues and eigenvectors using Relatively Robust Representations: :meth:zheevr

all eigenvalues and eigenvectors by a divide-and-conquer algorithm: :meth:zheevd

all eigenvalues and eigenvectors by a divide-and-conquer algorithm, using packed storage: :meth:zhpevd

all eigenvalues and eigenvectors by root-free :math:QR algorithm: :meth:zheev

all eigenvalues and eigenvectors by root-free :math:QR algorithm, using packed storage: :meth:zhpev

eigenvalues only

band matrix

all/selected eigenvalues by the Pal--Walker--Kahan variant of the :math:QL or :math:QR algorithm: :meth:zhbevx

all eigenvalues by the Pal--Walker--Kahan variant of the :math:QL or :math:QR algorithm: :meth:zhbev

all eigenvalues by the Pal--Walker--Kahan variant of the :math:QL or :math:QR algorithm, using packed storage: :meth:zhbevd

general matrix

all/selected eigenvalues by the Pal--Walker--Kahan variant of the :math:QL or :math:QR algorithm: :meth:zheevx

all/selected eigenvalues by the Pal--Walker--Kahan variant of the :math:QL or :math:QR algorithm, using packed storage: :meth:zhpevx

all eigenvalues by the Pal--Walker--Kahan variant of the :math:QL or :math:QR algorithm: :meth:zheev

all eigenvalues by the Pal--Walker--Kahan variant of the :math:QL or :math:QR algorithm, using packed storage: :meth:zhpev

complex upper Hessenberg matrix, reduced from complex general matrix

eigenvalues and Schur factorization: :meth:zhseqr

selected right and/or left eigenvectors by inverse iteration: :meth:zhsein

real bidiagonal matrix

singular value decomposition

after reduction from complex general matrix: :meth:zbdsqr

after reduction from real general matrix: :meth:dbdsqr

after reduction from real general matrix, using divide-and-conquer: :meth:dbdsdc

real symmetric matrix

eigenvalues and eigenvectors

band matrix

all/selected eigenvalues and eigenvectors by root-free :math:QR algorithm: :meth:dsbevx

all eigenvalues and eigenvectors by a divide-and-conquer algorithm: :meth:dsbevd

all eigenvalues and eigenvectors by root-free :math:QR algorithm: :meth:dsbev

general matrix

all/selected eigenvalues and eigenvectors by root-free :math:QR algorithm: :meth:dsyevx

all/selected eigenvalues and eigenvectors by root-free :math:QR algorithm, using packed storage: :meth:dspevx

all/selected eigenvalues and eigenvectors using Relatively Robust Representations: :meth:dsyevr

all eigenvalues and eigenvectors by a divide-and-conquer algorithm: :meth:dsyevd

all eigenvalues and eigenvectors by a divide-and-conquer algorithm, using packed storage: :meth:dspevd

all eigenvalues and eigenvectors by root-free :math:QR algorithm: :meth:dsyev

all eigenvalues and eigenvectors by root-free :math:QR algorithm, using packed storage: :meth:dspev

eigenvalues only

band matrix

all/selected eigenvalues by the Pal--Walker--Kahan variant of the :math:QL or :math:QR algorithm: :meth:dsbevx

all eigenvalues by the Pal--Walker--Kahan variant of the :math:QL or :math:QR algorithm: :meth:dsbev

general matrix

all/selected eigenvalues by the Pal--Walker--Kahan variant of the :math:QL or :math:QR algorithm: :meth:dsyevx

all/selected eigenvalues by the Pal--Walker--Kahan variant of the :math:QL or :math:QR algorithm, using packed storage: :meth:dspevx

all eigenvalues by the Pal--Walker--Kahan variant of the :math:QL or :math:QR algorithm: :meth:dsyev

all eigenvalues by the Pal--Walker--Kahan variant of the :math:QL or :math:QR algorithm, using packed storage: :meth:dspev

real symmetric tridiagonal matrix

eigenvalues and eigenvectors

after reduction from complex Hermitian matrix

all/selected eigenvalues and eigenvectors, using Relatively Robust Representations: :meth:zstegr

all eigenvalues and eigenvectors: :meth:zsteqr

all eigenvalues and eigenvectors, positive definite matrix: :meth:zpteqr

all eigenvalues and eigenvectors, using divide-and-conquer: :meth:zstedc

selected eigenvectors by inverse iteration: :meth:zstein

all/selected eigenvalues and eigenvectors, using Relatively Robust Representations: :meth:dstegr

all/selected eigenvalues and eigenvectors by root-free :math:QR algorithm: :meth:dstevx

all/selected eigenvalues and eigenvectors using Relatively Robust Representations: :meth:dstevr

all eigenvalues and eigenvectors: :meth:dsteqr

all eigenvalues and eigenvectors, by divide-and-conquer: :meth:dstedc

all eigenvalues and eigenvectors, positive definite matrix: :meth:dpteqr

all eigenvalues and eigenvectors by a divide-and-conquer algorithm: :meth:dstevd

all eigenvalues and eigenvectors by root-free :math:QR algorithm: :meth:dstev

selected eigenvectors by inverse iteration: :meth:dstein

eigenvalues only

all/selected eigenvalues by the Pal--Walker--Kahan variant of the :math:QL or :math:QR algorithm: :meth:dstevx

all eigenvalues by root-free :math:QR algorithm: :meth:dsterf

all eigenvalues by the Pal--Walker--Kahan variant of the :math:QL or :math:QR algorithm: :meth:dstev

selected eigenvalues only: :meth:dstebz

real upper Hessenberg matrix, reduced from real general matrix

eigenvalues and Schur factorization: :meth:dhseqr

selected right and/or left eigenvectors by inverse iteration: :meth:dhsein

**Eigenvalue problems for nonsymmetric matrices**

complex matrix

all eigenvalues, Schur form, Schur vectors and reciprocal condition numbers: :meth:zgeesx

all eigenvalues, Schur form and Schur vectors: :meth:zgees

all eigenvalues and left/right eigenvectors: :meth:zgeev

all eigenvalues and left/right eigenvectors, plus balancing transformation and reciprocal condition numbers: :meth:zgeevx

real matrix

all eigenvalues, real Schur form, Schur vectors and reciprocal condition numbers: :meth:dgeesx

all eigenvalues, real Schur form and Schur vectors: :meth:dgees

all eigenvalues and left/right eigenvectors: :meth:dgeev

all eigenvalues and left/right eigenvectors, plus balancing transformation and reciprocal condition numbers: :meth:dgeevx

**Eigenvalues and generalized Schur factorization**

complex generalized upper Hessenberg form: :meth:zhgeqz

real generalized upper Hessenberg form: :meth:dhgeqz

**General Gauss--Markov linear model**

solves a complex general Gauss--Markov linear model problem: :meth:zggglm

solves a real general Gauss--Markov linear model problem: :meth:dggglm

**Generalized eigenvalue problems for condensed forms of matrices**

complex Hermitian-definite eigenproblems

banded matrices

all eigenvalues and eigenvectors by a divide-and-conquer algorithm: :meth:zhbgvd

all eigenvalues and eigenvectors by reduction to tridiagonal form: :meth:zhbgv

selected eigenvalues and eigenvectors by reduction to tridiagonal form: :meth:zhbgvx

general matrices

all eigenvalues and eigenvectors by a divide-and-conquer algorithm: :meth:zhegvd

all eigenvalues and eigenvectors by a divide-and-conquer algorithm, packed storage format: :meth:zhpgvd

all eigenvalues and eigenvectors by reduction to tridiagonal form: :meth:zhegv

all eigenvalues and eigenvectors by reduction to tridiagonal form, packed storage format: :meth:zhpgv

selected eigenvalues and eigenvectors by reduction to tridiagonal form: :meth:zhegvx

selected eigenvalues and eigenvectors by reduction to tridiagonal form, packed storage format: :meth:zhpgvx

real symmetric-definite eigenproblems

banded matrices

all eigenvalues and eigenvectors by a divide-and-conquer algorithm: :meth:dsbgvd

all eigenvalues and eigenvectors by reduction to tridiagonal form: :meth:dsbgv

selected eigenvalues and eigenvectors by reduction to tridiagonal form: :meth:dsbgvx

general matrices

all eigenvalues and eigenvectors by a divide-and-conquer algorithm: :meth:dsygvd

all eigenvalues and eigenvectors by a divide-and-conquer algorithm, packed storage format: :meth:dspgvd

all eigenvalues and eigenvectors by reduction to tridiagonal form: :meth:dsygv

all eigenvalues and eigenvectors by reduction to tridiagonal form, packed storage format: :meth:dspgv

selected eigenvalues and eigenvectors by reduction to tridiagonal form: :meth:dsygvx

selected eigenvalues and eigenvectors by reduction to tridiagonal form, packed storage format: :meth:dspgvx

**Generalized eigenvalue problems for nonsymmetric matrix pairs**

complex nonsymmetric matrix pairs

all eigenvalues, generalized Schur form, Schur vectors and reciprocal condition numbers: :meth:zggesx

all eigenvalues, generalized Schur form and Schur vectors, deprecated: :meth:zgges

all eigenvalues, generalized Schur form and Schur vectors, using level 3 BLAS: :meth:zgges3

all eigenvalues and left/right eigenvectors, deprecated: :meth:zggev

all eigenvalues and left/right eigenvectors, plus the balancing transformation and reciprocal condition numbers: :meth:zggevx

all eigenvalues and left/right eigenvectors, using level 3 BLAS: :meth:zggev3

real nonsymmetric matrix pairs

all eigenvalues, generalized real Schur form and left/right Schur vectors, deprecated: :meth:dgges

all eigenvalues, generalized real Schur form and left/right Schur vectors, plus reciprocal condition numbers: :meth:dggesx

all eigenvalues, generalized real Schur form and left/right Schur vectors, using level 3 BLAS: :meth:dgges3

all eigenvalues and left/right eigenvectors, deprecated: :meth:dggev

all eigenvalues and left/right eigenvectors, plus the balancing transformation and reciprocal condition numbers: :meth:dggevx

all eigenvalues and left/right eigenvectors, using level 3 BLAS: :meth:dggev3

**Generalized** :math:QR **factorization**

complex matrices: :meth:zggqrf

real matrices: :meth:dggqrf

**Generalized** :math:RQ **factorization**

complex matrices: :meth:zggrqf

real matrices: :meth:dggrqf

**Generalized singular value decomposition**

after reduction from complex general matrix

complex triangular or trapezoidal matrix pair: :meth:ztgsja

after reduction from real general matrix

real triangular or trapezoidal matrix pair: :meth:dtgsja

complex matrix pair, deprecated: :meth:zggsvd

complex matrix pair, using level 3 BLAS: :meth:zggsvd3

partitioned orthogonal matrix (CS decomposition): :meth:dorcsd

partitioned unitary matrix (CS decomposition): :meth:zuncsd

real matrix pair, deprecated: :meth:dggsvd

real matrix pair, using level 3 BLAS: :meth:dggsvd3

reduction of a pair of general matrices to triangular or trapezoidal form

complex matrices, deprecated: :meth:zggsvp

complex matrices, using level 3 BLAS: :meth:zggsvp3

real matrices, deprecated: :meth:dggsvp

real matrices, using level 3 BLAS: :meth:dggsvp3

**least squares problems**

complex matrices

apply orthogonal matrix: :meth:zunmrz

minimum norm solution using a complete orthogonal factorization: :meth:zgelsy

minimum norm solution using the singular value decomposition: :meth:zgelss

minimum norm solution using the singular value decomposition (divide-and-conquer): :meth:zgelsd

reduction of upper trapezoidal matrix to upper triangular form: :meth:ztzrzf

real matrices

apply orthogonal matrix: :meth:dormrz

minimum norm solution using a complete orthogonal factorization: :meth:dgelsy

minimum norm solution using the singular value decomposition: :meth:dgelss

minimum norm solution using the singular value decomposition (divide-and-conquer): :meth:dgelsd

reduction of upper trapezoidal matrix to upper triangular form: :meth:dtzrzf

**least squares problems with linear equality constraints**

complex matrices

minimum norm solution subject to linear equality constraints using a generalized :math:RQ factorization: :meth:zgglse

real matrices

minimum norm solution subject to linear equality constraints using a generalized :math:RQ factorization: :meth:dgglse

**Left and right eigenvectors of a pair of matrices**

complex upper triangular matrices: :meth:ztgevc

real quasi-triangular matrices: :meth:dtgevc

:math:LQ **factorization and related operations**

complex matrices

apply unitary matrix: :meth:zunmlq

factorization: :meth:zgelqf

form all or part of unitary matrix: :meth:zunglq

real matrices

apply orthogonal matrix: :meth:dormlq

factorization: :meth:dgelqf

form all or part of orthogonal matrix: :meth:dorglq

**Operations on eigenvectors of a real symmetric or complex Hermitian matrix, or singular vectors of a general matrix**

estimate condition numbers: :meth:ddisna

**Operations on generalized Schur factorization of a general matrix pair**

complex matrix

estimate condition numbers of eigenvalues and/or eigenvectors: :meth:ztgsna

re-order Schur factorization: :meth:ztgexc

re-order Schur factorization, compute generalized eigenvalues and condition numbers: :meth:ztgsen

real matrix

estimate condition numbers of eigenvalues and/or eigenvectors: :meth:dtgsna

re-order Schur factorization: :meth:dtgexc

re-order Schur factorization, compute generalized eigenvalues and condition numbers: :meth:dtgsen

**Operations on Schur factorization of a general matrix**

complex matrix

compute left and/or right eigenvectors: :meth:ztrevc

estimate sensitivities of eigenvalues and/or eigenvectors: :meth:ztrsna

re-order Schur factorization: :meth:ztrexc

re-order Schur factorization, compute basis of invariant subspace, and estimate sensitivities: :meth:ztrsen

real matrix

compute left and/or right eigenvectors: :meth:dtrevc

estimate sensitivities of eigenvalues and/or eigenvectors: :meth:dtrsna

re-order Schur factorization: :meth:dtrexc

re-order Schur factorization, compute basis of invariant subspace, and estimate sensitivities: :meth:dtrsen

**Overdetermined and underdetermined linear systems**

complex matrices

solves an overdetermined or undetermined complex linear system: :meth:zgels

real matrices

solves an overdetermined or undetermined real linear system: :meth:dgels

**Performs a reduction of eigenvalue problems to condensed forms, and related operations**

real rectangular band matrix to upper bidiagonal form: :meth:dgbbrd

:math:QL **factorization and related operations**

complex matrices

apply unitary matrix: :meth:zunmql

factorization: :meth:zgeqlf

form all or part of unitary matrix: :meth:zungql

real matrices

apply orthogonal matrix: :meth:dormql

factorization: :meth:dgeqlf

form all or part of orthogonal matrix: :meth:dorgql

:math:QR **factorization and related operations**

complex matrices

general matrices

apply unitary matrix: :meth:zunmqr

apply unitary matrix, explicitly blocked: :meth:zgemqrt

factorization: :meth:zgeqrf

factorization, explicitly blocked: :meth:zgeqrt

factorization, with column pivoting, deprecated: :meth:zgeqpf

form all or part of unitary matrix: :meth:zungqr

triangular-pentagonal matrices

apply unitary matrix: :meth:ztpmqrt

factorization: :meth:ztpqrt

real matrices

general matrices

apply orthogonal matrix: :meth:dormqr

apply orthogonal matrix, explicitly blocked: :meth:dgemqrt

factorization

with column pivoting, using BLAS-3: :meth:dgeqp3

factorization, orthogonal matrix: :meth:dgeqrf

factorization, with column pivoting, deprecated: :meth:dgeqpf

factorization, with explicit blocking: :meth:dgeqrt

form all or part of orthogonal matrix: :meth:dorgqr

triangular-pentagonal matrices

apply orthogonal matrix: :meth:dtpqrt

factorization: :meth:dtpmqrt

**Reduction of a pair of general matrices to generalized upper Hessenberg form**

orthogonal reduction, real matrices, deprecated: :meth:dgghrd

orthogonal reduction, real matrices, using level 3 BLAS: :meth:dgghd3

unitary reduction, complex matrices, deprecated: :meth:zgghrd

unitary reduction, complex matrices, using level 3 BLAS: :meth:zgghd3

**Reduction of eigenvalue problems to condensed forms, and related operations**

complex general matrix to upper Hessenberg form

apply orthogonal matrix: :meth:zunmhr

form orthogonal matrix: :meth:zunghr

reduce to Hessenberg form: :meth:zgehrd

complex Hermitian band matrix to real symmetric tridiagonal form: :meth:zhbtrd

complex Hermitian matrix to real symmetric tridiagonal form

apply unitary matrix: :meth:zunmtr

apply unitary matrix, packed storage: :meth:zupmtr

form unitary matrix: :meth:zungtr

form unitary matrix, packed storage: :meth:zupgtr

reduce to tridiagonal form: :meth:zhetrd

reduce to tridiagonal form, packed storage: :meth:zhptrd

complex rectangular band matrix to real upper bidiagonal form: :meth:zgbbrd

complex rectangular matrix to real bidiagonal form

apply unitary matrix: :meth:zunmbr

form unitary matrix: :meth:zungbr

reduce to bidiagonal form: :meth:zgebrd

real general matrix to upper Hessenberg form

apply orthogonal matrix: :meth:dormhr

form orthogonal matrix: :meth:dorghr

reduce to Hessenberg form: :meth:dgehrd

real rectangular matrix to bidiagonal form

apply orthogonal matrix: :meth:dormbr

form orthogonal matrix: :meth:dorgbr

reduce to bidiagonal form: :meth:dgebrd

real symmetric band matrix to symmetric tridiagonal form: :meth:dsbtrd

real symmetric matrix to symmetric tridiagonal form

apply orthogonal matrix: :meth:dormtr

apply orthogonal matrix, packed storage: :meth:dopmtr

form orthogonal matrix: :meth:dorgtr

form orthogonal matrix, packed storage: :meth:dopgtr

reduce to tridiagonal form: :meth:dsytrd

reduce to tridiagonal form, packed storage: :meth:dsptrd

**Reduction of generalized eigenproblems to standard eigenproblems**

complex Hermitian-definite banded generalized eigenproblem :math:Ax = \lambda Bx: :meth:zhbgst

complex Hermitian-definite generalized eigenproblem :math:Ax = \lambda Bx, :math:ABx = \lambda x or :math:BAx = \lambda x: :meth:zhegst

complex Hermitian-definite generalized eigenproblem :math:Ax = \lambda Bx, :math:ABx = \lambda x or :math:BAx = \lambda x, packed storage: :meth:zhpgst

real symmetric-definite banded generalized eigenproblem :math:Ax = \lambda Bx: :meth:dsbgst

real symmetric-definite generalized eigenproblem :math:Ax = \lambda Bx, :math:ABx = \lambda x or :math:BAx = \lambda x: :meth:dsygst

real symmetric-definite generalized eigenproblem :math:Ax = \lambda Bx, :math:ABx = \lambda x or :math:BAx = \lambda x, packed storage: :meth:dspgst

:math:RQ **factorization and related operations**

complex matrices

apply unitary matrix: :meth:zunmrq

factorization: :meth:zgerqf

form all or part of unitary matrix: :meth:zungrq

real matrices

apply orthogonal matrix: :meth:dormrq

factorization: :meth:dgerqf

form all or part of orthogonal matrix: :meth:dorgrq

**Singular value decomposition**

complex matrix

all/selected singular values and, optionally, the corresponding singular vectors: :meth:zgesvdx

preconditioned Jacobi SVD using fast scaled rotations and de Rijks pivoting: :meth:zgejsv

using a divide-and-conquer algorithm: :meth:zgesdd

using bidiagonal :math:QR iteration: :meth:zgesvd

using fast scaled rotation and de Rijks pivoting: :meth:zgesvj

real matrix

all/selected singular values and, optionally, the corresponding singular vectors: :meth:dgesvdx

preconditioned Jacobi SVD using fast scaled rotations and de Rijks pivoting: :meth:dgejsv

using a divide-and-conquer algorithm: :meth:dgesdd

using bidiagonal :math:QR iteration: :meth:dgesvd

using fast scaled rotation and de Rijks pivoting: :meth:dgesvj

real square bidiagonal matrix

all/selected singular values and, optionally, the corresponding singular vectors: :meth:dbdsvdx

**Solve generalized Sylvester equation**

complex matrices: :meth:ztgsyl

real matrices: :meth:dtgsyl

**Solve reduced form of Sylvester matrix equation**

complex matrices: :meth:ztrsyl

real matrices: :meth:dtrsyl

**Split Cholesky factorization**

complex Hermitian positive definite band matrix: :meth:zpbstf

real symmetric positive definite band matrix: :meth:dpbstf

For full information please refer to the NAG Library document

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html
"""

[docs]def dgels(trans, a, b):
r"""
dgels solves linear least squares problems of the form

.. math::

where :math:A is an :math:m\times n real matrix of full rank, using a :math:QR or :math:LQ factorization of :math:A.

.. _f08aa-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08aaf.html

.. _f08aa-py2-py-parameters:

**Parameters**
**trans** : str, length 1
If :math:\mathrm{trans} = \texttt{'N'}, the linear system involves :math:A.

If :math:\mathrm{trans} = \texttt{'T'}, the linear system involves :math:A^\mathrm{T}.

**a** : float, array-like, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:A.

**b** : float, array-like, shape :math:\left(\max\left(m,n\right), \textit{nrhs}\right)
The matrix :math:B of right-hand side vectors, stored in columns; :math:\mathrm{b} is :math:m\times r if :math:\mathrm{trans} = \texttt{'N'}, or :math:n\times r if :math:\mathrm{trans} = \texttt{'T'}.

**Returns**
**a** : float, ndarray, shape :math:\left(m, n\right)
If :math:m\geq n, :math:\mathrm{a} is overwritten by details of its :math:QR factorization, as returned by :meth:dgeqrf.

If :math:m < n, :math:\mathrm{a} is overwritten by details of its :math:LQ factorization, as returned by :meth:dgelqf.

**b** : float, ndarray, shape :math:\left(\max\left(m,n\right), \textit{nrhs}\right)
:math:\mathrm{b} is overwritten by the solution vectors, :math:x, stored in columns:

if :math:\mathrm{trans} = \texttt{'N'} and :math:m\geq n, or :math:\mathrm{trans} = \texttt{'T'} and :math:m < n, elements :math:1 to :math:\mathrm{min}\left(m, n\right) in each column of :math:\mathrm{b} contain the least squares solution vectors; the residual sum of squares for the solution is given by the sum of squares of the modulus of elements :math:\left(\mathrm{min}\left(m, n\right)+1\right) to :math:\mathrm{max}\left(m, n\right) in that column;

otherwise, elements :math:1 to :math:\mathrm{max}\left(m, n\right) in each column of :math:\mathrm{b} contain the minimum norm solution vectors.

.. _f08aa-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{trans}.

Constraint: :math:\mathrm{trans} = \texttt{'N'} or :math:\texttt{'T'}.

(errno :math:-2)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

(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:i > 0)
Diagonal element :math:\langle\mathit{\boldsymbol{value}}\rangle of the triangular factor of :math:A is zero, so that :math:A does not have full rank; the least squares solution could not be computed.

.. _f08aa-py2-py-notes:

**Notes**
The following options are provided:

(1) If :math:\mathrm{trans} = \texttt{'N'} and :math:m\geq n: find the least squares solution of an overdetermined system, i.e., solve the least squares problem

.. math::
\mathrm{min}_x\left\lVert b-Ax\right\rVert_2\text{.}

(#) If :math:\mathrm{trans} = \texttt{'N'} and :math:m < n: find the minimum norm solution of an underdetermined system :math:Ax = b.

(#) If :math:\mathrm{trans} = \texttt{'T'} and :math:m\geq n: find the minimum norm solution of an undetermined system :math:A^\mathrm{T}x = b.

(#) If :math:\mathrm{trans} = \texttt{'T'} and :math:m < n: find the least squares solution of an overdetermined system, i.e., solve the least squares problem

.. math::
\mathrm{min}_x\left\lVert b-A^\mathrm{T}x\right\rVert_2\text{.}

Several right-hand side vectors :math:b and solution vectors :math:x can be handled in a single call; they are stored as the columns of the :math:m\times r right-hand side matrix :math:B and the :math:n\times r solution matrix :math:X.

.. _f08aa-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 dgeqrt(nb, a):
r"""
dgeqrt recursively computes, with explicit blocking, the :math:QR factorization of a real :math:m\times n matrix.

.. _f08ab-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08abf.html

.. _f08ab-py2-py-parameters:

**Parameters**
**nb** : int
The explicitly chosen block size to be used in computing the :math:QR factorization. See Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08abf.html#fcomments>__ for details.

**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)
If :math:m\geq n, the elements below the diagonal are overwritten by details of the orthogonal matrix :math:Q and the upper triangle is overwritten by the corresponding elements of the :math:n\times n upper triangular matrix :math:R.

If :math:m < n, the strictly lower triangular part is overwritten by details of the orthogonal matrix :math:Q and the remaining elements are overwritten by the corresponding elements of the :math:m\times n upper trapezoidal matrix :math:R.

**t** : float, ndarray, shape :math:\left(\mathrm{nb}, \min\left(m,n\right)\right)
Further details of the orthogonal matrix :math:Q. The number of blocks is :math:b = \left\lceil \frac{k}{\mathrm{nb}}\right\rceil, where :math:k = \mathrm{min}\left(m, n\right) and each block is of order :math:\mathrm{nb} except for the last block, which is of order :math:k-\left(b-1\right)\times \mathrm{nb}. For each of the blocks, an upper triangular block reflector factor is computed: :math:\boldsymbol{T}_1,\boldsymbol{T}_2,\ldots,\boldsymbol{T}_b. These are stored in the :math:\mathrm{nb}\times n matrix :math:T as :math:\boldsymbol{T} = \left[\boldsymbol{T}_1|\boldsymbol{T}_2| \cdots |\boldsymbol{T}_b\right].

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

(errno :math:-3)
On entry, error in parameter :math:\mathrm{nb}.

Constraint: :math:1\leq \mathrm{nb}\leq \mathrm{min}\left(m, n\right).

.. _f08ab-py2-py-notes:

**Notes**
dgeqrt forms the :math:QR factorization of an arbitrary rectangular real :math:m\times n matrix.
No pivoting is performed.

It differs from :meth:dgeqrf in that it: requires an explicit block size; stores reflector factors that are upper triangular matrices of the chosen block size (rather than scalars); and recursively computes the :math:QR factorization based on the algorithm of Elmroth and Gustavson (2000).

If :math:m\geq n, the factorization is given by:

.. math::
A = Q\begin{pmatrix}R\\0\end{pmatrix}\text{,}

where :math:R is an :math:n\times n upper triangular matrix and :math:Q is an :math:m\times m orthogonal matrix.
It is sometimes more convenient to write the factorization as

.. math::
A = \begin{pmatrix}Q_1&Q_2\end{pmatrix}\begin{pmatrix}R\\0\end{pmatrix}\text{,}

which reduces to

.. math::
A = Q_1R\text{,}

where :math:Q_1 consists of the first :math:n columns of :math:Q, and :math:Q_2 the remaining :math:m-n columns.

If :math:m < n, :math:R is upper trapezoidal, and the factorization can be written

.. math::
A = Q\begin{pmatrix}R_1&R_2\end{pmatrix}\text{,}

where :math:R_1 is upper triangular and :math:R_2 is rectangular.

The matrix :math:Q is not formed explicitly but is represented as a product of :math:\mathrm{min}\left(m, n\right) elementary reflectors (see the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html>__ for details). Functions are provided to work with :math:Q in this representation (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08abf.html#fcomments>__).

Note also that for any :math:k < n, the information returned represents a :math:QR factorization of the first :math:k columns of the original matrix :math:A.

.. _f08ab-py2-py-references:

**References**
Elmroth, E and Gustavson, F, 2000, Applying Recursion to Serial and Parallel :math:{QR} Factorization Leads to Better Performance, IBM Journal of Research and Development. (Volume 44) (4), 605--624

Golub, G H and Van Loan, C F, 2012, Matrix Computations, (4th Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError

[docs]def dgemqrt(side, trans, v, t, c):
r"""
dgemqrt multiplies an arbitrary real matrix :math:C by the real orthogonal matrix :math:Q from a :math:QR factorization computed by :meth:dgeqrt.

.. _f08ac-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08acf.html

.. _f08ac-py2-py-parameters:

**Parameters**
**side** : str, length 1
Indicates how :math:Q or :math:Q^\mathrm{T} is to be applied to :math:C.

:math:\mathrm{side} = \texttt{'L'}

:math:Q or :math:Q^\mathrm{T} is applied to :math:C from the left.

:math:\mathrm{side} = \texttt{'R'}

:math:Q or :math:Q^\mathrm{T} is applied to :math:C from the right.

**trans** : str, length 1
Indicates whether :math:Q or :math:Q^\mathrm{T} is to be applied to :math:C.

:math:\mathrm{trans} = \texttt{'N'}

:math:Q is applied to :math:C.

:math:\mathrm{trans} = \texttt{'T'}

:math:Q^\mathrm{T} is applied to :math:C.

**v** : float, array-like, shape :math:\left(:, k\right)
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\mathrm{side}=\texttt{'L'}: :math:m; if :math:\mathrm{side}=\texttt{'R'}: :math:n; otherwise: :math:0.

Details of the vectors which define the elementary reflectors, as returned by :meth:dgeqrt in the first :math:k columns of its array argument :math:\textit{a}.

**t** : float, array-like, shape :math:\left(\textit{nb}, k\right)
Further details of the orthogonal matrix :math:Q as returned by :meth:dgeqrt. The number of blocks is :math:b = \left\lceil \frac{k}{\textit{nb}}\right\rceil, where :math:k = \mathrm{min}\left(m, n\right) and each block is of order :math:\textit{nb} except for the last block, which is of order :math:k-\left(b-1\right)\times \textit{nb}. For the :math:b blocks the upper triangular block reflector factors :math:\boldsymbol{T}_1,\boldsymbol{T}_2,\ldots,\boldsymbol{T}_b are stored in the :math:\textit{nb}\times n matrix :math:T as :math:\boldsymbol{T} = \left[\boldsymbol{T}_1|\boldsymbol{T}_2| \cdots |\boldsymbol{T}_b\right].

**c** : float, array-like, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:C.

**Returns**
**c** : float, ndarray, shape :math:\left(m, n\right)
:math:\mathrm{c} is overwritten by :math:QC or :math:Q^\mathrm{T}C or :math:CQ or :math:CQ^\mathrm{T} as specified by :math:\mathrm{side} and :math:\mathrm{trans}.

.. _f08ac-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{side}.

Constraint: :math:\mathrm{side} = \texttt{'L'} or :math:\texttt{'R'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{trans}.

Constraint: :math:\mathrm{trans} = \texttt{'N'} or :math:\texttt{'T'}.

(errno :math:-3)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

(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{k}.

Constraint: :math:m\geq k\geq 0.

(errno :math:-5)
On entry, error in parameter :math:\textit{k}.

Constraint: :math:n\geq k\geq 0.

(errno :math:-6)
On entry, error in parameter :math:\textit{nb}.

Constraint: :math:\textit{nb}\geq 1.

(errno :math:-6)
On entry, error in parameter :math:\textit{nb}.

Constraint: :math:\textit{nb}\leq k.

.. _f08ac-py2-py-notes:

**Notes**
dgemqrt is intended to be used after a call to :meth:dgeqrt which performs a :math:QR factorization of a real matrix :math:A.
The orthogonal matrix :math:Q is represented as a product of elementary reflectors.

This function may be used to form one of the matrix products

.. math::
QC,Q^\mathrm{T}C,CQ\text{ or }CQ^\mathrm{T}\text{,}

overwriting the result on :math:C (which may be any real rectangular matrix).

A common application of this function is in solving linear least squares problems, as described in the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html>__.

.. _f08ac-py2-py-references:

**References**
Golub, G H and Van Loan, C F, 2012, Matrix Computations, (4th Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError

[docs]def dgeqrf(a):
r"""
dgeqrf computes the :math:QR factorization of a real :math:m\times n matrix.

.. _f08ae-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08aef.html

.. _f08ae-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)
If :math:m\geq n, the elements below the diagonal are overwritten by details of the orthogonal matrix :math:Q and the upper triangle is overwritten by the corresponding elements of the :math:n\times n upper triangular matrix :math:R.

If :math:m < n, the strictly lower triangular part is overwritten by details of the orthogonal matrix :math:Q and the remaining elements are overwritten by the corresponding elements of the :math:m\times n upper trapezoidal matrix :math:R.

**tau** : float, ndarray, shape :math:\left(\min\left(m,n\right)\right)
Further details of the orthogonal matrix :math:Q.

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

.. _f08ae-py2-py-notes:

**Notes**
dgeqrf forms the :math:QR factorization of an arbitrary rectangular real :math:m\times n matrix.
No pivoting is performed.

If :math:m\geq n, the factorization is given by:

.. math::
A = Q\begin{pmatrix}R\\0\end{pmatrix}\text{,}

where :math:R is an :math:n\times n upper triangular matrix and :math:Q is an :math:m\times m orthogonal matrix.
It is sometimes more convenient to write the factorization as

.. math::
A = \begin{pmatrix}Q_1&Q_2\end{pmatrix}\begin{pmatrix}R\\0\end{pmatrix}\text{,}

which reduces to

.. math::
A = Q_1R\text{,}

where :math:Q_1 consists of the first :math:n columns of :math:Q, and :math:Q_2 the remaining :math:m-n columns.

If :math:m < n, :math:R is trapezoidal, and the factorization can be written

.. math::
A = Q\begin{pmatrix}R_1&R_2\end{pmatrix}\text{,}

where :math:R_1 is upper triangular and :math:R_2 is rectangular.

The matrix :math:Q is not formed explicitly but is represented as a product of :math:\mathrm{min}\left(m, n\right) elementary reflectors (see the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html>__ for details). Functions are provided to work with :math:Q in this representation (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08aef.html#fcomments>__).

Note also that for any :math:k < n, the information returned in the first :math:k columns of the array :math:\mathrm{a} represents a :math:QR factorization of the first :math:k columns of the original matrix :math:A.

.. _f08ae-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 dorgqr(a, tau):
r"""
dorgqr generates all or part of the real orthogonal matrix :math:Q from a :math:QR factorization computed by :meth:dgeqrf or :meth:dgeqp3.

.. _f08af-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08aff.html

.. _f08af-py2-py-parameters:

**Parameters**
**a** : float, array-like, shape :math:\left(m, n\right)
Details of the vectors which define the elementary reflectors, as returned by :meth:dgeqrf or :meth:dgeqp3.

**tau** : float, array-like, shape :math:\left(\max\left(1,k\right)\right)
Further details of the elementary reflectors, as returned by :meth:dgeqrf or :meth:dgeqp3.

**Returns**
**a** : float, ndarray, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:Q.

.. _f08af-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:m\geq n\geq 0.

(errno :math:-3)
On entry, error in parameter :math:\textit{k}.

Constraint: :math:n\geq k\geq 0.

.. _f08af-py2-py-notes:

**Notes**
dorgqr is intended to be used after a call to :meth:dgeqrf or :meth:dgeqp3. which perform a :math:QR factorization of a real matrix :math:A.
The orthogonal matrix :math:Q is represented as a product of elementary reflectors.

This function may be used to generate :math:Q explicitly as a square matrix, or to form only its leading columns.

Usually :math:Q is determined from the :math:QR factorization of an :math:m\times p matrix :math:A with :math:m\geq p.
The whole of :math:Q may be computed by calling dorgqr with :math:\textit{n} set to :math:m and :math:\textit{k} set to :math:p or its leading :math:p columns by calling dorgqr with :math:\textit{n} and :math:\textit{k} set to :math:p.

The columns of :math:Q returned by the last call form an orthonormal basis for the space spanned by the columns of :math:A; thus :meth:dgeqrf followed by dorgqr can be used to orthogonalize the columns of :math:A.

The information returned by the :math:QR factorization functions also yields the :math:QR factorization of the leading :math:k columns of :math:A, where :math:k < p.
The orthogonal matrix arising from this factorization can be computed by calling dorgqr with :math:\textit{n} set to :math:m or its leading :math:k columns by calling dorgqr with :math:\textit{n} set to :math:k.

.. _f08af-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 dormqr(side, trans, a, tau, c):
r"""
dormqr multiplies an arbitrary real matrix :math:C by the real orthogonal matrix :math:Q from a :math:QR factorization computed by :meth:dgeqrf or :meth:dgeqp3.

.. _f08ag-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08agf.html

.. _f08ag-py2-py-parameters:

**Parameters**
**side** : str, length 1
Indicates how :math:Q or :math:Q^\mathrm{T} is to be applied to :math:C.

:math:\mathrm{side} = \texttt{'L'}

:math:Q or :math:Q^\mathrm{T} is applied to :math:C from the left.

:math:\mathrm{side} = \texttt{'R'}

:math:Q or :math:Q^\mathrm{T} is applied to :math:C from the right.

**trans** : str, length 1
Indicates whether :math:Q or :math:Q^\mathrm{T} is to be applied to :math:C.

:math:\mathrm{trans} = \texttt{'N'}

:math:Q is applied to :math:C.

:math:\mathrm{trans} = \texttt{'T'}

:math:Q^\mathrm{T} is applied to :math:C.

**a** : float, array-like, shape :math:\left(:, k\right)
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\mathrm{side}=\texttt{'L'}: :math:m; if :math:\mathrm{side}=\texttt{'R'}: :math:n; otherwise: :math:0.

Details of the vectors which define the elementary reflectors, as returned by :meth:dgeqrf or :meth:dgeqp3.

**tau** : float, array-like, shape :math:\left(k\right)
Further details of the elementary reflectors, as returned by :meth:dgeqrf or :meth:dgeqp3.

**c** : float, array-like, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:C.

**Returns**
**c** : float, ndarray, shape :math:\left(m, n\right)
:math:\mathrm{c} is overwritten by :math:QC or :math:Q^\mathrm{T}C or :math:CQ or :math:CQ^\mathrm{T} as specified by :math:\mathrm{side} and :math:\mathrm{trans}.

.. _f08ag-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{side}.

Constraint: :math:\mathrm{side} = \texttt{'L'} or :math:\texttt{'R'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{trans}.

Constraint: :math:\mathrm{trans} = \texttt{'N'} or :math:\texttt{'T'}.

(errno :math:-3)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

(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{k}.

Constraint: :math:m\geq k\geq 0.

(errno :math:-5)
On entry, error in parameter :math:\textit{k}.

Constraint: :math:n\geq k\geq 0.

.. _f08ag-py2-py-notes:

**Notes**
dormqr is intended to be used after a call to :meth:dgeqrf or :meth:dgeqp3 which perform a :math:QR factorization of a real matrix :math:A.
The orthogonal matrix :math:Q is represented as a product of elementary reflectors.

This function may be used to form one of the matrix products

.. math::
QC,Q^\mathrm{T}C,CQ\text{ or }CQ^\mathrm{T}\text{,}

overwriting the result on :math:\mathrm{c} (which may be any real rectangular matrix).

A common application of this function is in solving linear least squares problems, as described in the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html>__.

.. _f08ag-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 dgelqf(a):
r"""
dgelqf computes the :math:LQ factorization of a real :math:m\times n matrix.

.. _f08ah-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08ahf.html

.. _f08ah-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)
If :math:m\leq n, the elements above the diagonal are overwritten by details of the orthogonal matrix :math:Q and the lower triangle is overwritten by the corresponding elements of the :math:m\times m lower triangular matrix :math:L.

If :math:m > n, the strictly upper triangular part is overwritten by details of the orthogonal matrix :math:Q and the remaining elements are overwritten by the corresponding elements of the :math:m\times n lower trapezoidal matrix :math:L.

**tau** : float, ndarray, shape :math:\left(\min\left(m,n\right)\right)
Further details of the orthogonal matrix :math:Q.

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

.. _f08ah-py2-py-notes:

**Notes**
dgelqf forms the :math:LQ factorization of an arbitrary rectangular real :math:m\times n matrix.
No pivoting is performed.

If :math:m\leq n, the factorization is given by:

.. math::
A = \begin{pmatrix}L&0\end{pmatrix}Q

where :math:L is an :math:m\times m lower triangular matrix and :math:Q is an :math:n\times n orthogonal matrix.
It is sometimes more convenient to write the factorization as

.. math::
A = \begin{pmatrix}L&0\end{pmatrix}\begin{pmatrix}Q_1\\Q_2\end{pmatrix}

which reduces to

.. math::
A = LQ_1\text{,}

where :math:Q_1 consists of the first :math:m rows of :math:Q, and :math:Q_2 the remaining :math:n-m rows.

If :math:m > n, :math:L is trapezoidal, and the factorization can be written

.. math::
A = \begin{pmatrix}L_1\\L_2\end{pmatrix}Q

where :math:L_1 is lower triangular and :math:L_2 is rectangular.

The :math:LQ factorization of :math:A is essentially the same as the :math:QR factorization of :math:A^\mathrm{T}, since

.. math::
A = \begin{pmatrix}L&0\end{pmatrix}Q⇔A^\mathrm{T} = Q^\mathrm{T}\begin{pmatrix}L^\mathrm{T}\\0\end{pmatrix}\text{.}

The matrix :math:Q is not formed explicitly but is represented as a product of :math:\mathrm{min}\left(m, n\right) elementary reflectors (see the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html>__ for details). Functions are provided to work with :math:Q in this representation (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08ahf.html#fcomments>__).

Note also that for any :math:k < m, the information returned in the first :math:k rows of the array :math:\mathrm{a} represents an :math:LQ factorization of the first :math:k rows of the original matrix :math:A.
"""
raise NotImplementedError

[docs]def dorglq(a, tau):
r"""
dorglq generates all or part of the real orthogonal matrix :math:Q from an :math:LQ factorization computed by :meth:dgelqf.

.. _f08aj-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08ajf.html

.. _f08aj-py2-py-parameters:

**Parameters**
**a** : float, array-like, shape :math:\left(m, n\right)
Details of the vectors which define the elementary reflectors, as returned by :meth:dgelqf.

**tau** : float, array-like, shape :math:\left(k\right)
Further details of the elementary reflectors, as returned by :meth:dgelqf.

**Returns**
**a** : float, ndarray, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:Q.

.. _f08aj-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 m.

(errno :math:-3)
On entry, error in parameter :math:\textit{k}.

Constraint: :math:m\geq k\geq 0.

.. _f08aj-py2-py-notes:

**Notes**
dorglq is intended to be used after a call to :meth:dgelqf, which performs an :math:LQ factorization of a real matrix :math:A.
The orthogonal matrix :math:Q is represented as a product of elementary reflectors.

This function may be used to generate :math:Q explicitly as a square matrix, or to form only its leading rows.

Usually :math:Q is determined from the :math:LQ factorization of a :math:p\times n matrix :math:A with :math:p\leq n.
The whole of :math:Q may be computed by calling dorglq with :math:\textit{m} set to :math:n and :math:\textit{k} set to :math:p or its leading :math:p rows by calling dorglq with :math:\textit{m} and :math:\textit{k} set to :math:p.

The rows of :math:Q returned by the last call form an orthonormal basis for the space spanned by the rows of :math:A; thus :meth:dgelqf followed by dorglq can be used to orthogonalize the rows of :math:A.

The information returned by the :math:LQ factorization functions also yields the :math:LQ factorization of the leading :math:k rows of :math:A, where :math:k < p.
The orthogonal matrix arising from this factorization can be computed by calling dorglq with :math:\textit{m} set to :math:n or its leading :math:k rows by calling dorglq with :math:\textit{m} set to :math:k.

.. _f08aj-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 dormlq(side, trans, a, tau, c):
r"""
dormlq multiplies an arbitrary real matrix :math:C by the real orthogonal matrix :math:Q from an :math:LQ factorization computed by :meth:dgelqf.

.. _f08ak-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08akf.html

.. _f08ak-py2-py-parameters:

**Parameters**
**side** : str, length 1
Indicates how :math:Q or :math:Q^\mathrm{T} is to be applied to :math:C.

:math:\mathrm{side} = \texttt{'L'}

:math:Q or :math:Q^\mathrm{T} is applied to :math:C from the left.

:math:\mathrm{side} = \texttt{'R'}

:math:Q or :math:Q^\mathrm{T} is applied to :math:C from the right.

**trans** : str, length 1
Indicates whether :math:Q or :math:Q^\mathrm{T} is to be applied to :math:C.

:math:\mathrm{trans} = \texttt{'N'}

:math:Q is applied to :math:C.

:math:\mathrm{trans} = \texttt{'T'}

:math:Q^\mathrm{T} is applied to :math:C.

**a** : float, array-like, shape :math:\left(k, :\right)
Note: the required extent for this argument in dimension 2 is determined as follows: if :math:\mathrm{side}=\texttt{'L'}: :math:m; if :math:\mathrm{side}=\texttt{'R'}: :math:n; otherwise: :math:0.

Details of the vectors which define the elementary reflectors, as returned by :meth:dgelqf.

**tau** : float, array-like, shape :math:\left(k\right)
Further details of the elementary reflectors, as returned by :meth:dgelqf.

**c** : float, array-like, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:C.

**Returns**
**c** : float, ndarray, shape :math:\left(m, n\right)
:math:\mathrm{c} is overwritten by :math:QC or :math:Q^\mathrm{T}C or :math:CQ or :math:CQ^\mathrm{T} as specified by :math:\mathrm{side} and :math:\mathrm{trans}.

.. _f08ak-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{side}.

Constraint: :math:\mathrm{side} = \texttt{'L'} or :math:\texttt{'R'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{trans}.

Constraint: :math:\mathrm{trans} = \texttt{'N'} or :math:\texttt{'T'}.

(errno :math:-3)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

(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{k}.

Constraint: :math:m\geq k\geq 0.

(errno :math:-5)
On entry, error in parameter :math:\textit{k}.

Constraint: :math:n\geq k\geq 0.

.. _f08ak-py2-py-notes:

**Notes**
dormlq is intended to be used after a call to :meth:dgelqf, which performs an :math:LQ factorization of a real matrix :math:A.
The orthogonal matrix :math:Q is represented as a product of elementary reflectors.

This function may be used to form one of the matrix products

.. math::
QC,Q^\mathrm{T}C,CQ\text{ or }CQ^\mathrm{T}\text{,}

overwriting the result on :math:C (which may be any real rectangular matrix).

.. _f08ak-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 zgels(trans, a, b):
r"""
zgels solves linear least squares problems of the form

.. math::

where :math:A is an :math:m\times n complex matrix of full rank, using a :math:QR or :math:LQ factorization of :math:A.

.. _f08an-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08anf.html

.. _f08an-py2-py-parameters:

**Parameters**
**trans** : str, length 1
If :math:\mathrm{trans} = \texttt{'N'}, the linear system involves :math:A.

If :math:\mathrm{trans} = \texttt{'C'}, the linear system involves :math:A^\mathrm{H}.

**a** : complex, array-like, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:A.

**b** : complex, array-like, shape :math:\left(\max\left(m,n\right), \textit{nrhs}\right)
The matrix :math:B of right-hand side vectors, stored in columns; :math:\mathrm{b} is :math:m\times r if :math:\mathrm{trans} = \texttt{'N'}, or :math:n\times r if :math:\mathrm{trans} = \texttt{'C'}.

**Returns**
**a** : complex, ndarray, shape :math:\left(m, n\right)
If :math:m\geq n, :math:\mathrm{a} is overwritten by details of its :math:QR factorization, as returned by :meth:zgeqrf.

If :math:m < n, :math:\mathrm{a} is overwritten by details of its :math:LQ factorization, as returned by :meth:zgelqf.

**b** : complex, ndarray, shape :math:\left(\max\left(m,n\right), \textit{nrhs}\right)
:math:\mathrm{b} is overwritten by the solution vectors, :math:x, stored in columns:

if :math:\mathrm{trans} = \texttt{'N'} and :math:m\geq n, or :math:\mathrm{trans} = \texttt{'C'} and :math:m < n, elements :math:1 to :math:\mathrm{min}\left(m, n\right) in each column of :math:\mathrm{b} contain the least squares solution vectors; the residual sum of squares for the solution is given by the sum of squares of the modulus of elements :math:\left(\mathrm{min}\left(m, n\right)+1\right) to :math:\mathrm{max}\left(m, n\right) in that column;

otherwise, elements :math:1 to :math:\mathrm{max}\left(m, n\right) in each column of :math:\mathrm{b} contain the minimum norm solution vectors.

.. _f08an-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{trans}.

Constraint: :math:\mathrm{trans} = \texttt{'N'} or :math:\texttt{'C'}.

(errno :math:-2)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

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

(errno :math:i > 0)
Diagonal element :math:\langle\mathit{\boldsymbol{value}}\rangle of the triangular factor of :math:A is zero, so that :math:A does not have full rank; the least squares solution could not be computed.

.. _f08an-py2-py-notes:

**Notes**
The following options are provided:

(1) If :math:\mathrm{trans} = \texttt{'N'} and :math:m\geq n: find the least squares solution of an overdetermined system, i.e., solve the least squares problem

.. math::
\mathrm{min}_x\left\lVert b-Ax\right\rVert_2\text{.}

(#) If :math:\mathrm{trans} = \texttt{'N'} and :math:m < n: find the minimum norm solution of an underdetermined system :math:Ax = b.

(#) If :math:\mathrm{trans} = \texttt{'C'} and :math:m\geq n: find the minimum norm solution of an undetermined system :math:A^\mathrm{H}x = b.

(#) If :math:\mathrm{trans} = \texttt{'C'} and :math:m < n: find the least squares solution of an overdetermined system, i.e., solve the least squares problem

.. math::
\mathrm{min}_x\left\lVert b-A^\mathrm{H}x\right\rVert_2\text{.}

Several right-hand side vectors :math:b and solution vectors :math:x can be handled in a single call; they are stored as the columns of the :math:m\times r right-hand side matrix :math:B and the :math:n\times r solution matrix :math:X.

.. _f08an-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 zgeqrt(nb, a):
r"""
zgeqrt recursively computes, with explicit blocking, the :math:QR factorization of a complex :math:m\times n matrix.

.. _f08ap-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08apf.html

.. _f08ap-py2-py-parameters:

**Parameters**
**nb** : int
The explicitly chosen block size to be used in computing the :math:QR factorization. See Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08apf.html#fcomments>__ for details.

**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)
If :math:m\geq n, the elements below the diagonal are overwritten by details of the unitary matrix :math:Q and the upper triangle is overwritten by the corresponding elements of the :math:n\times n upper triangular matrix :math:R.

If :math:m < n, the strictly lower triangular part is overwritten by details of the unitary matrix :math:Q and the remaining elements are overwritten by the corresponding elements of the :math:m\times n upper trapezoidal matrix :math:R.

The diagonal elements of :math:R are real.

**t** : complex, ndarray, shape :math:\left(\mathrm{nb}, \min\left(m,n\right)\right)
Further details of the unitary matrix :math:Q. The number of blocks is :math:b = \left\lceil \frac{k}{\mathrm{nb}}\right\rceil, where :math:k = \mathrm{min}\left(m, n\right) and each block is of order :math:\mathrm{nb} except for the last block, which is of order :math:k-\left(b-1\right)\times \mathrm{nb}. For each of the blocks, an upper triangular block reflector factor is computed: :math:\boldsymbol{T}_1,\boldsymbol{T}_2,\ldots,\boldsymbol{T}_b. These are stored in the :math:\mathrm{nb}\times n matrix :math:T as :math:\boldsymbol{T} = \left[\boldsymbol{T}_1|\boldsymbol{T}_2| \cdots |\boldsymbol{T}_b\right].

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

(errno :math:-3)
On entry, error in parameter :math:\mathrm{nb}.

Constraint: :math:1\leq \mathrm{nb}\leq \mathrm{min}\left(m, n\right).

.. _f08ap-py2-py-notes:

**Notes**
zgeqrt forms the :math:QR factorization of an arbitrary rectangular complex :math:m\times n matrix.
No pivoting is performed.

It differs from :meth:zgeqrf in that it: requires an explicit block size; stores reflector factors that are upper triangular matrices of the chosen block size (rather than scalars); and recursively computes the :math:QR factorization based on the algorithm of Elmroth and Gustavson (2000).

If :math:m\geq n, the factorization is given by:

.. math::
A = Q\begin{pmatrix}R\\0\end{pmatrix}\text{,}

where :math:R is an :math:n\times n upper triangular matrix (with real diagonal elements) and :math:Q is an :math:m\times m unitary matrix.
It is sometimes more convenient to write the factorization as

.. math::
A = \begin{pmatrix}Q_1&Q_2\end{pmatrix}\begin{pmatrix}R\\0\end{pmatrix}\text{,}

which reduces to

.. math::
A = Q_1R\text{,}

where :math:Q_1 consists of the first :math:n columns of :math:Q, and :math:Q_2 the remaining :math:m-n columns.

If :math:m < n, :math:R is upper trapezoidal, and the factorization can be written

.. math::
A = Q\begin{pmatrix}R_1&R_2\end{pmatrix}\text{,}

where :math:R_1 is upper triangular and :math:R_2 is rectangular.

The matrix :math:Q is not formed explicitly but is represented as a product of :math:\mathrm{min}\left(m, n\right) elementary reflectors (see the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html>__ for details). Functions are provided to work with :math:Q in this representation (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08apf.html#fcomments>__).

Note also that for any :math:k < n, the information returned represents a :math:QR factorization of the first :math:k columns of the original matrix :math:A.

.. _f08ap-py2-py-references:

**References**
Elmroth, E and Gustavson, F, 2000, Applying Recursion to Serial and Parallel :math:{QR} Factorization Leads to Better Performance, IBM Journal of Research and Development. (Volume 44) (4), 605--624

Golub, G H and Van Loan, C F, 2012, Matrix Computations, (4th Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError

[docs]def zgemqrt(side, trans, v, t, c):
r"""
zgemqrt multiplies an arbitrary complex matrix :math:C by the complex unitary matrix :math:Q from a :math:QR factorization computed by :meth:zgeqrt.

.. _f08aq-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08aqf.html

.. _f08aq-py2-py-parameters:

**Parameters**
**side** : str, length 1
Indicates how :math:Q or :math:Q^\mathrm{H} is to be applied to :math:C.

:math:\mathrm{side} = \texttt{'L'}

:math:Q or :math:Q^\mathrm{H} is applied to :math:C from the left.

:math:\mathrm{side} = \texttt{'R'}

:math:Q or :math:Q^\mathrm{H} is applied to :math:C from the right.

**trans** : str, length 1
Indicates whether :math:Q or :math:Q^\mathrm{H} is to be applied to :math:C.

:math:\mathrm{trans} = \texttt{'N'}

:math:Q is applied to :math:C.

:math:\mathrm{trans} = \texttt{'C'}

:math:Q^\mathrm{H} is applied to :math:C.

**v** : complex, array-like, shape :math:\left(:, k\right)
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\mathrm{side}=\texttt{'L'}: :math:m; if :math:\mathrm{side}=\texttt{'R'}: :math:n; otherwise: :math:0.

Details of the vectors which define the elementary reflectors, as returned by :meth:zgeqrt in the first :math:k columns of its array argument :math:\textit{a}.

**t** : complex, array-like, shape :math:\left(\textit{nb}, k\right)
Further details of the unitary matrix :math:Q as returned by :meth:zgeqrt. The number of blocks is :math:b = \left\lceil \frac{k}{\textit{nb}}\right\rceil, where :math:k = \mathrm{min}\left(m, n\right) and each block is of order :math:\textit{nb} except for the last block, which is of order :math:k-\left(b-1\right)\times \textit{nb}. For the :math:b blocks the upper triangular block reflector factors :math:\boldsymbol{T}_1,\boldsymbol{T}_2,\ldots,\boldsymbol{T}_b are stored in the :math:\textit{nb}\times n matrix :math:T as :math:\boldsymbol{T} = \left[\boldsymbol{T}_1|\boldsymbol{T}_2| \cdots |\boldsymbol{T}_b\right].

**c** : complex, array-like, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:C.

**Returns**
**c** : complex, ndarray, shape :math:\left(m, n\right)
:math:\mathrm{c} is overwritten by :math:QC or :math:Q^\mathrm{H}C or :math:CQ or :math:CQ^\mathrm{H} as specified by :math:\mathrm{side} and :math:\mathrm{trans}.

.. _f08aq-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{side}.

Constraint: :math:\mathrm{side} = \texttt{'L'} or :math:\texttt{'R'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{trans}.

Constraint: :math:\mathrm{trans} = \texttt{'N'} or :math:\texttt{'C'}.

(errno :math:-3)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

(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{k}.

Constraint: :math:m\geq k\geq 0.

(errno :math:-5)
On entry, error in parameter :math:\textit{k}.

Constraint: :math:n\geq k\geq 0.

(errno :math:-6)
On entry, error in parameter :math:\textit{nb}.

Constraint: :math:\textit{nb}\geq 1.

(errno :math:-6)
On entry, error in parameter :math:\textit{nb}.

Constraint: :math:\textit{nb}\leq k.

.. _f08aq-py2-py-notes:

**Notes**
zgemqrt is intended to be used after a call to :meth:zgeqrt, which performs a :math:QR factorization of a complex matrix :math:A.
The unitary matrix :math:Q is represented as a product of elementary reflectors.

This function may be used to form one of the matrix products

.. math::
QC,Q^\mathrm{H}C,CQ\text{ or }CQ^\mathrm{H}\text{,}

overwriting the result on :math:C (which may be any complex rectangular matrix).

A common application of this function is in solving linear least squares problems, as described in the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html>__.

.. _f08aq-py2-py-references:

**References**
Golub, G H and Van Loan, C F, 2012, Matrix Computations, (4th Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError

[docs]def zgeqrf(a):
r"""
zgeqrf computes the :math:QR factorization of a complex :math:m\times n matrix.

.. _f08as-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08asf.html

.. _f08as-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)
If :math:m\geq n, the elements below the diagonal are overwritten by details of the unitary matrix :math:Q and the upper triangle is overwritten by the corresponding elements of the :math:n\times n upper triangular matrix :math:R.

If :math:m < n, the strictly lower triangular part is overwritten by details of the unitary matrix :math:Q and the remaining elements are overwritten by the corresponding elements of the :math:m\times n upper trapezoidal matrix :math:R.

The diagonal elements of :math:R are real.

**tau** : complex, ndarray, shape :math:\left(\min\left(m,n\right)\right)
Further details of the unitary matrix :math:Q.

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

.. _f08as-py2-py-notes:

**Notes**
zgeqrf forms the :math:QR factorization of an arbitrary rectangular complex :math:m\times n matrix.
No pivoting is performed.

If :math:m\geq n, the factorization is given by:

.. math::
A = Q\begin{pmatrix}R\\0\end{pmatrix}\text{,}

where :math:R is an :math:n\times n upper triangular matrix (with real diagonal elements) and :math:Q is an :math:m\times m unitary matrix.
It is sometimes more convenient to write the factorization as

.. math::
A = \begin{pmatrix}Q_1&Q_2\end{pmatrix}\begin{pmatrix}R\\0\end{pmatrix}\text{,}

which reduces to

.. math::
A = Q_1R\text{,}

where :math:Q_1 consists of the first :math:n columns of :math:Q, and :math:Q_2 the remaining :math:m-n columns.

If :math:m < n, :math:R is trapezoidal, and the factorization can be written

.. math::
A = Q\begin{pmatrix}R_1&R_2\end{pmatrix}\text{,}

where :math:R_1 is upper triangular and :math:R_2 is rectangular.

The matrix :math:Q is not formed explicitly but is represented as a product of :math:\mathrm{min}\left(m, n\right) elementary reflectors (see the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html>__ for details). Functions are provided to work with :math:Q in this representation (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08asf.html#fcomments>__).

Note also that for any :math:k < n, the information returned in the first :math:k columns of the array :math:\mathrm{a} represents a :math:QR factorization of the first :math:k columns of the original matrix :math:A.

.. _f08as-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 zungqr(a, tau):
r"""
zungqr generates all or part of the complex unitary matrix :math:Q from a :math:QR factorization computed by :meth:zgeqrf or :meth:zgeqp3.

.. _f08at-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08atf.html

.. _f08at-py2-py-parameters:

**Parameters**
**a** : complex, array-like, shape :math:\left(m, n\right)
Details of the vectors which define the elementary reflectors, as returned by :meth:zgeqrf or :meth:zgeqp3.

**tau** : complex, array-like, shape :math:\left(\max\left(1,k\right)\right)
Further details of the elementary reflectors, as returned by :meth:zgeqrf or :meth:zgeqp3.

**Returns**
**a** : complex, ndarray, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:Q.

.. _f08at-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:m\geq n\geq 0.

(errno :math:-3)
On entry, error in parameter :math:\textit{k}.

Constraint: :math:n\geq k\geq 0.

.. _f08at-py2-py-notes:

**Notes**
zungqr is intended to be used after a call to :meth:zgeqrf or :meth:zgeqp3, which perform a :math:QR factorization of a complex matrix :math:A.
The unitary matrix :math:Q is represented as a product of elementary reflectors.

This function may be used to generate :math:Q explicitly as a square matrix, or to form only its leading columns.

Usually :math:Q is determined from the :math:QR factorization of an :math:m\times p matrix :math:A with :math:m\geq p.
The whole of :math:Q may be computed by calling zungqr with :math:\textit{n} set to :math:m and :math:\textit{k} set to :math:p or its leading :math:p columns by calling zungqr with :math:\textit{n} and :math:\textit{k} set to :math:p.

The columns of :math:Q returned by the last call form an orthonormal basis for the space spanned by the columns of :math:A; thus :meth:zgeqrf followed by zungqr can be used to orthogonalize the columns of :math:A.

The information returned by the :math:QR factorization functions also yields the :math:QR factorization of the leading :math:k columns of :math:A, where :math:k < p.
The unitary matrix arising from this factorization can be computed by calling zungqr with :math:\textit{n} set to :math:m or its leading :math:k columns by calling zungqr with :math:\textit{n} set to :math:k.

.. _f08at-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 zunmqr(side, trans, a, tau, c):
r"""
zunmqr multiplies an arbitrary complex matrix :math:C by the complex unitary matrix :math:Q from a :math:QR factorization computed by :meth:zgeqrf or :meth:zgeqp3.

.. _f08au-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08auf.html

.. _f08au-py2-py-parameters:

**Parameters**
**side** : str, length 1
Indicates how :math:Q or :math:Q^\mathrm{H} is to be applied to :math:C.

:math:\mathrm{side} = \texttt{'L'}

:math:Q or :math:Q^\mathrm{H} is applied to :math:C from the left.

:math:\mathrm{side} = \texttt{'R'}

:math:Q or :math:Q^\mathrm{H} is applied to :math:C from the right.

**trans** : str, length 1
Indicates whether :math:Q or :math:Q^\mathrm{H} is to be applied to :math:C.

:math:\mathrm{trans} = \texttt{'N'}

:math:Q is applied to :math:C.

:math:\mathrm{trans} = \texttt{'C'}

:math:Q^\mathrm{H} is applied to :math:C.

**a** : complex, array-like, shape :math:\left(:, k\right)
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\mathrm{side}=\texttt{'L'}: :math:m; if :math:\mathrm{side}=\texttt{'R'}: :math:n; otherwise: :math:0.

Details of the vectors which define the elementary reflectors, as returned by :meth:zgeqrf or :meth:zgeqp3.

**tau** : complex, array-like, shape :math:\left(k\right)
Further details of the elementary reflectors, as returned by :meth:zgeqrf or :meth:zgeqp3.

**c** : complex, array-like, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:C.

**Returns**
**c** : complex, ndarray, shape :math:\left(m, n\right)
:math:\mathrm{c} is overwritten by :math:QC or :math:Q^\mathrm{H}C or :math:CQ or :math:CQ^\mathrm{H} as specified by :math:\mathrm{side} and :math:\mathrm{trans}.

.. _f08au-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{side}.

Constraint: :math:\mathrm{side} = \texttt{'L'} or :math:\texttt{'R'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{trans}.

Constraint: :math:\mathrm{trans} = \texttt{'N'} or :math:\texttt{'C'}.

(errno :math:-3)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

(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{k}.

Constraint: :math:m\geq k\geq 0.

(errno :math:-5)
On entry, error in parameter :math:\textit{k}.

Constraint: :math:n\geq k\geq 0.

.. _f08au-py2-py-notes:

**Notes**
zunmqr is intended to be used after a call to :meth:zgeqrf or :meth:zgeqp3, which perform a :math:QR factorization of a complex matrix :math:A.
The unitary matrix :math:Q is represented as a product of elementary reflectors.

This function may be used to form one of the matrix products

.. math::
QC,Q^\mathrm{H}C,CQ\text{ or }CQ^\mathrm{H}\text{,}

overwriting the result on :math:\mathrm{c} (which may be any complex rectangular matrix).

A common application of this function is in solving linear least squares problems, as described in the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html>__.

.. _f08au-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 zgelqf(a):
r"""
zgelqf computes the :math:LQ factorization of a complex :math:m\times n matrix.

.. _f08av-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08avf.html

.. _f08av-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)
If :math:m\leq n, the elements above the diagonal are overwritten by details of the unitary matrix :math:Q and the lower triangle is overwritten by the corresponding elements of the :math:m\times m lower triangular matrix :math:L.

If :math:m > n, the strictly upper triangular part is overwritten by details of the unitary matrix :math:Q and the remaining elements are overwritten by the corresponding elements of the :math:m\times n lower trapezoidal matrix :math:L.

The diagonal elements of :math:L are real.

**tau** : complex, ndarray, shape :math:\left(\min\left(m,n\right)\right)
Further details of the unitary matrix :math:Q.

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

.. _f08av-py2-py-notes:

**Notes**
zgelqf forms the :math:LQ factorization of an arbitrary rectangular complex :math:m\times n matrix.
No pivoting is performed.

If :math:m\leq n, the factorization is given by:

.. math::
A = \begin{pmatrix}L&0\end{pmatrix}Q

where :math:L is an :math:m\times m lower triangular matrix (with real diagonal elements) and :math:Q is an :math:n\times n unitary matrix.
It is sometimes more convenient to write the factorization as

.. math::
A = \begin{pmatrix}L&0\end{pmatrix}\begin{pmatrix}Q_1\\Q_2\end{pmatrix}

which reduces to

.. math::
A = LQ_1\text{,}

where :math:Q_1 consists of the first :math:m rows of :math:Q, and :math:Q_2 the remaining :math:n-m rows.

If :math:m > n, :math:L is trapezoidal, and the factorization can be written

.. math::
A = \begin{pmatrix}L_1\\L_2\end{pmatrix}Q

where :math:L_1 is lower triangular and :math:L_2 is rectangular.

The :math:LQ factorization of :math:A is essentially the same as the :math:QR factorization of :math:A^\mathrm{H}, since

.. math::
A = \begin{pmatrix}L&0\end{pmatrix}Q⇔A^\mathrm{H} = Q^\mathrm{H}\begin{pmatrix}L^\mathrm{H}\\0\end{pmatrix}\text{.}

The matrix :math:Q is not formed explicitly but is represented as a product of :math:\mathrm{min}\left(m, n\right) elementary reflectors (see the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html>__ for details). Functions are provided to work with :math:Q in this representation (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08avf.html#fcomments>__).

Note also that for any :math:k < m, the information returned in the first :math:k rows of the array :math:\mathrm{a} represents an :math:LQ factorization of the first :math:k rows of the original matrix :math:A.
"""
raise NotImplementedError

[docs]def zunglq(a, tau):
r"""
zunglq generates all or part of the complex unitary matrix :math:Q from an :math:LQ factorization computed by :meth:zgelqf.

.. _f08aw-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08awf.html

.. _f08aw-py2-py-parameters:

**Parameters**
**a** : complex, array-like, shape :math:\left(m, n\right)
Details of the vectors which define the elementary reflectors, as returned by :meth:zgelqf.

**tau** : complex, array-like, shape :math:\left(k\right)
Further details of the elementary reflectors, as returned by :meth:zgelqf.

**Returns**
**a** : complex, ndarray, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:Q.

.. _f08aw-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 m.

(errno :math:-3)
On entry, error in parameter :math:\textit{k}.

Constraint: :math:m\geq k\geq 0.

.. _f08aw-py2-py-notes:

**Notes**
zunglq is intended to be used after a call to :meth:zgelqf, which performs an :math:LQ factorization of a complex matrix :math:A.
The unitary matrix :math:Q is represented as a product of elementary reflectors.

This function may be used to generate :math:Q explicitly as a square matrix, or to form only its leading rows.

Usually :math:Q is determined from the :math:LQ factorization of a :math:p\times n matrix :math:A with :math:p\leq n.
The whole of :math:Q may be computed by calling zunglq with :math:\textit{m} set to :math:n and :math:\textit{k} set to :math:p or its leading :math:p rows by calling zunglq with :math:\textit{m} and :math:\textit{k} set to :math:p.

The rows of :math:Q returned by the last call form an orthonormal basis for the space spanned by the rows of :math:A; thus :meth:zgelqf followed by zunglq can be used to orthogonalize the rows of :math:A.

The information returned by the :math:LQ factorization functions also yields the :math:LQ factorization of the leading :math:k rows of :math:A, where :math:k < p.
The unitary matrix arising from this factorization can be computed by calling zunglq with :math:\textit{m} set to :math:n or its leading :math:k rows by calling zunglq with :math:\textit{m} set to :math:k.

.. _f08aw-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 zunmlq(side, trans, a, tau, c):
r"""
zunmlq multiplies an arbitrary complex matrix :math:C by the complex unitary matrix :math:Q from an :math:LQ factorization computed by :meth:zgelqf.

.. _f08ax-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08axf.html

.. _f08ax-py2-py-parameters:

**Parameters**
**side** : str, length 1
Indicates how :math:Q or :math:Q^\mathrm{H} is to be applied to :math:C.

:math:\mathrm{side} = \texttt{'L'}

:math:Q or :math:Q^\mathrm{H} is applied to :math:C from the left.

:math:\mathrm{side} = \texttt{'R'}

:math:Q or :math:Q^\mathrm{H} is applied to :math:C from the right.

**trans** : str, length 1
Indicates whether :math:Q or :math:Q^\mathrm{H} is to be applied to :math:C.

:math:\mathrm{trans} = \texttt{'N'}

:math:Q is applied to :math:C.

:math:\mathrm{trans} = \texttt{'C'}

:math:Q^\mathrm{H} is applied to :math:C.

**a** : complex, array-like, shape :math:\left(k, :\right)
Note: the required extent for this argument in dimension 2 is determined as follows: if :math:\mathrm{side}=\texttt{'L'}: :math:m; if :math:\mathrm{side}=\texttt{'R'}: :math:n; otherwise: :math:0.

Details of the vectors which define the elementary reflectors, as returned by :meth:zgelqf.

**tau** : complex, array-like, shape :math:\left(k\right)
Further details of the elementary reflectors, as returned by :meth:zgelqf.

**c** : complex, array-like, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:C.

**Returns**
**c** : complex, ndarray, shape :math:\left(m, n\right)
:math:\mathrm{c} is overwritten by :math:QC or :math:Q^\mathrm{H}C or :math:CQ or :math:CQ^\mathrm{H} as specified by :math:\mathrm{side} and :math:\mathrm{trans}.

.. _f08ax-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{side}.

Constraint: :math:\mathrm{side} = \texttt{'L'} or :math:\texttt{'R'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{trans}.

Constraint: :math:\mathrm{trans} = \texttt{'N'} or :math:\texttt{'C'}.

(errno :math:-3)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

(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{k}.

Constraint: :math:m\geq k\geq 0.

(errno :math:-5)
On entry, error in parameter :math:\textit{k}.

Constraint: :math:n\geq k\geq 0.

.. _f08ax-py2-py-notes:

**Notes**
zunmlq is intended to be used after a call to :meth:zgelqf, which performs an :math:LQ factorization of a complex matrix :math:A.
The unitary matrix :math:Q is represented as a product of elementary reflectors.

This function may be used to form one of the matrix products

.. math::
QC,Q^\mathrm{H}C,CQ\text{ or }CQ^\mathrm{H}\text{,}

overwriting the result on :math:C (which may be any complex rectangular matrix).

.. _f08ax-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 dgelsy(a, b, jpvt, rcond):
r"""
dgelsy computes the minimum norm solution to a real linear least squares problem

.. math::
\mathrm{min}_x\left\lVert b-Ax\right\rVert_2

using a complete orthogonal factorization of :math:A. :math:A is an :math:m\times n matrix which may be rank-deficient.
Several right-hand side vectors :math:b and solution vectors :math:x can be handled in a single call.

.. _f08ba-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08baf.html

.. _f08ba-py2-py-parameters:

**Parameters**
**a** : float, array-like, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:A.

**b** : float, array-like, shape :math:\left(\max\left(m,n\right), \textit{nrhs}\right)
The :math:m\times r right-hand side matrix :math:B.

**jpvt** : int, array-like, shape :math:\left(n\right)
If :math:\mathrm{jpvt}[i-1]\neq 0, the :math:i\ th column of :math:A is permuted to the front of :math:AP, otherwise column :math:i is a free column.

**rcond** : float
Used to determine the effective rank of :math:A, which is defined as the order of the largest leading triangular sub-matrix :math:R_{11} in the :math:QR factorization of :math:A, whose estimated condition number is :math:\text{} < 1/\mathrm{rcond}.

Suggested value: if the condition number of :math:\mathrm{a} is not known then :math:\mathrm{rcond} = \sqrt{\left(\epsilon \right)/2} (where :math:\epsilon is machine precision, see :meth:machine.precision <naginterfaces.library.machine.precision>) is a good choice. Negative values or values less than machine precision should be avoided since this will cause :math:\mathrm{a} to have an effective :math:\text{rank} = \mathrm{min}\left(m, n\right) that could be larger than its actual rank, leading to meaningless results.

**Returns**
**a** : float, ndarray, shape :math:\left(m, n\right)
:math:\mathrm{a} has been overwritten by details of its complete orthogonal factorization.

**b** : float, ndarray, shape :math:\left(\max\left(m,n\right), \textit{nrhs}\right)
The :math:n\times r solution matrix :math:X.

**jpvt** : int, ndarray, shape :math:\left(n\right)
If :math:\mathrm{jpvt}[i-1] = k, the :math:i\ th column of :math:AP was the :math:k\ th column of :math:A.

**rank** : int
The effective rank of :math:A, i.e., the order of the sub-matrix :math:R_{11}. This is the same as the order of the sub-matrix :math:T_{11} in the complete orthogonal factorization of :math:A.

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

(errno :math:-3)
On entry, error in parameter :math:\textit{nrhs}.

Constraint: :math:\textit{nrhs}\geq 0.

.. _f08ba-py2-py-notes:

**Notes**
The right-hand side vectors are stored as the columns of the :math:m\times r matrix :math:B and the solution vectors in the :math:n\times r matrix :math:X.

dgelsy first computes a :math:QR factorization with column pivoting

.. math::
AP = Q\begin{pmatrix}R_{11}&R_{12}\\0&R_{22}\end{pmatrix}\text{,}

with :math:R_{11} defined as the largest leading sub-matrix whose estimated condition number is less than :math:1/\mathrm{rcond}.
The order of :math:R_{11}, :math:\mathrm{rank}, is the effective rank of :math:A.

Then, :math:R_{22} is considered to be negligible, and :math:R_{12} is annihilated by orthogonal transformations from the right, arriving at the complete orthogonal factorization

.. math::
AP = Q\begin{pmatrix}T_{11}&0\\0&0\end{pmatrix}Z\text{.}

The minimum norm solution is then

.. math::
X = PZ^\mathrm{T}\begin{pmatrix} T_{11}^{-1} Q_1^\mathrm{T} b \\0\end{pmatrix}

where :math:Q_1 consists of the first :math:\mathrm{rank} columns of :math:Q.

.. _f08ba-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 dtpqrt(l, nb, a, b):
r"""
dtpqrt computes the :math:QR factorization of a real :math:\left(m+n\right)\times n triangular-pentagonal matrix.

.. _f08bb-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08bbf.html

.. _f08bb-py2-py-parameters:

**Parameters**
**l** : int
:math:l, the number of rows of the trapezoidal part of :math:B (i.e., :math:B_2).

**nb** : int
The explicitly chosen block-size to be used in the algorithm for computing the :math:QR factorization. See Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08bbf.html#fcomments>__ for details.

**a** : float, array-like, shape :math:\left(n, n\right)
The :math:n\times n upper triangular matrix :math:A.

**b** : float, array-like, shape :math:\left(m, n\right)
The :math:m\times n pentagonal matrix :math:B composed of an :math:\left(m-l\right)\times n rectangular matrix :math:B_1 above an :math:l\times n upper trapezoidal matrix :math:B_2.

**Returns**
**a** : float, ndarray, shape :math:\left(n, n\right)
The upper triangle is overwritten by the corresponding elements of the :math:n\times n upper triangular matrix :math:R.

**b** : float, ndarray, shape :math:\left(m, n\right)
Details of the orthogonal matrix :math:Q.

**t** : float, ndarray, shape :math:\left(\mathrm{nb}, n\right)
Further details of the orthogonal matrix :math:Q. The number of blocks is :math:b = \left\lceil \frac{k}{\mathrm{nb}}\right\rceil, where :math:k = \mathrm{min}\left(m, n\right) and each block is of order :math:\mathrm{nb} except for the last block, which is of order :math:k-\left(b-1\right)\times \mathrm{nb}. For each of the blocks, an upper triangular block reflector factor is computed: :math:\boldsymbol{T}_1,\boldsymbol{T}_2,\ldots,\boldsymbol{T}_b. These are stored in the :math:\mathrm{nb}\times n matrix :math:T as :math:\boldsymbol{T} = \left[\boldsymbol{T}_1|\boldsymbol{T}_2| \cdots |\boldsymbol{T}_b\right].

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

(errno :math:-3)
On entry, error in parameter :math:\mathrm{l}.

Constraint: :math:0\leq \mathrm{l}\leq \mathrm{min}\left(m, n\right).

(errno :math:-4)
On entry, error in parameter :math:\mathrm{nb}.

Constraint: :math:\mathrm{nb}\geq 1.

(errno :math:-4)
On entry, error in parameter :math:\mathrm{nb}.

Constraint: :math:\mathrm{nb}\leq n.

.. _f08bb-py2-py-notes:

**Notes**
dtpqrt forms the :math:QR factorization of a real :math:\left(m+n\right)\times n triangular-pentagonal matrix :math:C,

.. math::
C = \begin{pmatrix}A\\B\end{pmatrix}

where :math:A is an upper triangular :math:n\times n matrix and :math:B is an :math:m\times n pentagonal matrix consisting of an :math:\left(m-l\right)\times n rectangular matrix :math:B_1 on top of an :math:l\times n upper trapezoidal matrix :math:B_2:

.. math::
B = \begin{pmatrix}B_1\\B_2\end{pmatrix}\text{.}

The upper trapezoidal matrix :math:B_2 consists of the first :math:l rows of an :math:n\times n upper triangular matrix, where :math:0≤l≤\mathrm{min}\left(m, n\right).
If :math:l = 0, :math:B is :math:m\times n rectangular; if :math:l = n and :math:m = n, :math:B is upper triangular.

A recursive, explicitly blocked, :math:QR factorization (see :meth:dgeqrt) is performed on the matrix :math:C.
The upper triangular matrix :math:R, details of the orthogonal matrix :math:Q, and further details (the block reflector factors) of :math:Q are returned.

Typically the matrix :math:A or :math:B_2 contains the matrix :math:R from the :math:QR factorization of a subproblem and dtpqrt performs the :math:QR update operation from the inclusion of matrix :math:B_1.

For example, consider the :math:QR factorization of an :math:l\times n matrix :math:\hat{B} with :math:l < n: :math:\hat{B} = \hat{Q}\hat{R}, :math:\hat{R} = \begin{pmatrix}\hat{R_1}&\hat{R_2}\end{pmatrix}, where :math:\hat{R_1} is :math:l\times l upper triangular and :math:\hat{R_2} is :math:\left(n-l\right)\times n rectangular (this can be performed by :meth:dgeqrt).
Given an initial least squares problem :math:\hat{B}\hat{X} = \hat{Y} where :math:X and :math:Y are :math:l\times \textit{nrhs} matrices, we have :math:\hat{R}\hat{X} = \hat{Q}^\mathrm{T}\hat{Y}.

Now, adding an additional :math:m-l rows to the original system gives the augmented least squares problem

.. math::
BX = Y

where :math:B is an :math:m\times n matrix formed by adding :math:m-l rows on top of :math:\hat{R} and :math:Y is an :math:m\times \textit{nrhs} matrix formed by adding :math:m-l rows on top of :math:\hat{Q}^\mathrm{T}\hat{Y}.

dtpqrt can then be used to perform the :math:QR factorization of the pentagonal matrix :math:B; the :math:n\times n matrix :math:A will be zero on input and contain :math:R on output.

In the case where :math:\hat{B} is :math:r\times n, :math:r\geq n, :math:\hat{R} is :math:n\times n upper triangular (forming :math:A) on top of :math:r-n rows of zeros (forming first :math:r-n rows of :math:B).
Augmentation is then performed by adding rows to the bottom of :math:B with :math:l = 0.

.. _f08bb-py2-py-references:

**References**
Elmroth, E and Gustavson, F, 2000, Applying Recursion to Serial and Parallel :math:{QR} Factorization Leads to Better Performance, IBM Journal of Research and Development. (Volume 44) (4), 605--624

Golub, G H and Van Loan, C F, 2012, Matrix Computations, (4th Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError

[docs]def dtpmqrt(side, trans, l, v, t, c1, c2):
r"""
dtpmqrt multiplies an arbitrary real matrix :math:C by the real orthogonal matrix :math:Q from a :math:QR factorization computed by :meth:dtpqrt.

.. _f08bc-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08bcf.html

.. _f08bc-py2-py-parameters:

**Parameters**
**side** : str, length 1
Indicates how :math:Q or :math:Q^\mathrm{T} is to be applied to :math:C.

:math:\mathrm{side} = \texttt{'L'}

:math:Q or :math:Q^\mathrm{T} is applied to :math:C from the left.

:math:\mathrm{side} = \texttt{'R'}

:math:Q or :math:Q^\mathrm{T} is applied to :math:C from the right.

**trans** : str, length 1
Indicates whether :math:Q or :math:Q^\mathrm{T} is to be applied to :math:C.

:math:\mathrm{trans} = \texttt{'N'}

:math:Q is applied to :math:C.

:math:\mathrm{trans} = \texttt{'T'}

:math:Q^\mathrm{T} is applied to :math:C.

**l** : int
:math:l, the number of rows of the upper trapezoidal part of the pentagonal composite matrix :math:V, passed (as :math:\textit{b}) in a previous call to :meth:dtpqrt. This must be the same value used in the previous call to :meth:dtpqrt (see :math:\textit{l} in :meth:dtpqrt).

**v** : float, array-like, shape :math:\left(:, k\right)
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\mathrm{side}=\texttt{'L'}: :math:m; if :math:\mathrm{side}=\texttt{'R'}: :math:n; otherwise: :math:0.

The :math:m_v\times n_v matrix :math:V; this should remain unchanged from the array :math:\textit{b} returned by a previous call to :meth:dtpqrt.

**t** : float, array-like, shape :math:\left(\textit{nb}, k\right)
This must remain unchanged from a previous call to :meth:dtpqrt (see :math:\textit{t} in :meth:dtpqrt).

**c1** : float, array-like, shape :math:\left(:, :\right)
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\mathrm{side}=\texttt{'L'}: :math:k; if :math:\mathrm{side}=\texttt{'R'}: :math:m; otherwise: :math:0.

Note: the required extent for this argument in dimension 2 is determined as follows: if :math:\mathrm{side}=\texttt{'L'}: :math:n; if :math:\mathrm{side}=\texttt{'R'}: :math:k; otherwise: :math:0.

:math:C_1, the first part of the composite matrix :math:C:

if :math:\mathrm{side} = \texttt{'L'}

then :math:\mathrm{c1} contains the first :math:k rows of :math:C;

if :math:\mathrm{side} = \texttt{'R'}

then :math:\mathrm{c1} contains the first :math:k columns of :math:C.

**c2** : float, array-like, shape :math:\left(m, n\right)
:math:C_2, the second part of the composite matrix :math:C.

if :math:\mathrm{side} = \texttt{'L'}

then :math:\mathrm{c2} contains the remaining :math:m_v rows of :math:C;

if :math:\mathrm{side} = \texttt{'R'}

then :math:\mathrm{c2} contains the remaining :math:m_v columns of :math:C;

**Returns**
**c1** : float, ndarray, shape :math:\left(:, :\right)
:math:\mathrm{c1} is overwritten by the corresponding block of :math:QC or :math:Q^\mathrm{T}C or :math:CQ or :math:CQ^\mathrm{T}.

**c2** : float, ndarray, shape :math:\left(m, n\right)
:math:\mathrm{c2} is overwritten by the corresponding block of :math:QC or :math:Q^\mathrm{T}C or :math:CQ or :math:CQ^\mathrm{T}.

.. _f08bc-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{side}.

Constraint: :math:\mathrm{side} = \texttt{'L'} or :math:\texttt{'R'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{trans}.

Constraint: :math:\mathrm{trans} = \texttt{'N'} or :math:\texttt{'T'}.

(errno :math:-3)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

(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{k}.

Constraint: :math:k\geq 0.

(errno :math:-6)
On entry, error in parameter :math:\mathrm{l}.

Constraint: :math:0\leq \mathrm{l}\leq k.

(errno :math:-7)
On entry, error in parameter :math:\textit{nb}.

Constraint: :math:\textit{nb}\geq 1.

(errno :math:-7)
On entry, error in parameter :math:\textit{nb}.

Constraint: :math:\textit{nb}\leq k.

.. _f08bc-py2-py-notes:

**Notes**
dtpmqrt is intended to be used after a call to :meth:dtpqrt which performs a :math:QR factorization of a triangular-pentagonal matrix containing an upper triangular matrix :math:A over a pentagonal matrix :math:B.
The orthogonal matrix :math:Q is represented as a product of elementary reflectors.

This function may be used to form the matrix products

.. math::
QC,Q^\mathrm{T}C,CQ\text{ or }CQ^\mathrm{T}\text{,}

where the real rectangular :math:m_c\times n_c matrix :math:C is split into component matrices :math:C_1 and :math:C_2.

If :math:Q is being applied from the left (:math:QC or :math:Q^\mathrm{T}C) then

.. math::
C = \begin{pmatrix}C_1\\C_2\end{pmatrix}

where :math:C_1 is :math:k\times n_c, :math:C_2 is :math:m_v\times n_c, :math:m_c = k+m_v is fixed and :math:m_v is the number of rows of the matrix :math:V containing the elementary reflectors (i.e., :math:\textit{m} as passed to :meth:dtpqrt); the number of columns of :math:V is :math:n_v (i.e., :math:\textit{n} as passed to :meth:dtpqrt).

If :math:Q is being applied from the right (:math:CQ or :math:CQ^\mathrm{T}) then

.. math::
C = \begin{pmatrix}C_1&C_2\end{pmatrix}

where :math:C_1 is :math:m_c\times k, and :math:C_2 is :math:m_c\times m_v and :math:n_c = k+m_v is fixed.

The matrices :math:C_1 and :math:C_2 are overwriten by the result of the matrix product.

A common application of this routine is in updating the solution of a linear least squares problem.

.. _f08bc-py2-py-references:

**References**
Golub, G H and Van Loan, C F, 2012, Matrix Computations, (4th Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError

[docs]def dgeqpf(a, jpvt):
r"""
dgeqpf computes the :math:QR factorization, with column pivoting, of a real :math:m\times n matrix. dgeqpf is marked as deprecated by LAPACK; the replacement routine is :meth:dgeqp3 which makes better use of Level 3 BLAS.

.. deprecated:: 27.0.0.0
dgeqpf is deprecated.
Please use :meth:dgeqp3 instead.
See also the :ref:Replacement Calls <replace> document.

.. _f08be-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08bef.html

.. _f08be-py2-py-parameters:

**Parameters**
**a** : float, array-like, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:A.

**jpvt** : int, array-like, shape :math:\left(n\right)
If :math:\mathrm{jpvt}[i-1]\neq 0, the :math:i th column of :math:A is moved to the beginning of :math:AP before the decomposition is computed and is fixed in place during the computation. Otherwise, the :math:i th column of :math:A is a free column (i.e., one which may be interchanged during the computation with any other free column).

**Returns**
**a** : float, ndarray, shape :math:\left(m, n\right)
If :math:m\geq n, the elements below the diagonal are overwritten by details of the orthogonal matrix :math:Q and the upper triangle is overwritten by the corresponding elements of the :math:n\times n upper triangular matrix :math:R.

If :math:m < n, the strictly lower triangular part is overwritten by details of the orthogonal matrix :math:Q and the remaining elements are overwritten by the corresponding elements of the :math:m\times n upper trapezoidal matrix :math:R.

**jpvt** : int, ndarray, shape :math:\left(n\right)
Details of the permutation matrix :math:P. More precisely, if :math:\mathrm{jpvt}[i-1] = k, the :math:k\ th column of :math:A is moved to become the :math:i th column of :math:AP; in other words, the columns of :math:AP are the columns of :math:A in the order :math:\mathrm{jpvt},\mathrm{jpvt},\ldots,\mathrm{jpvt}[n-1].

**tau** : float, ndarray, shape :math:\left(\min\left(m,n\right)\right)
Further details of the orthogonal matrix :math:Q.

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

.. _f08be-py2-py-notes:

**Notes**
dgeqpf forms the :math:QR factorization, with column pivoting, of an arbitrary rectangular real :math:m\times n matrix.

If :math:m\geq n, the factorization is given by:

.. math::
AP = Q\begin{pmatrix}R\\0\end{pmatrix}\text{,}

where :math:R is an :math:n\times n upper triangular matrix, :math:Q is an :math:m\times m orthogonal matrix and :math:P is an :math:n\times n permutation matrix.
It is sometimes more convenient to write the factorization as

.. math::
AP = \begin{pmatrix}Q_1&Q_2\end{pmatrix}\begin{pmatrix}R\\0\end{pmatrix}\text{,}

which reduces to

.. math::
AP = Q_1R\text{,}

where :math:Q_1 consists of the first :math:n columns of :math:Q, and :math:Q_2 the remaining :math:m-n columns.

If :math:m < n, :math:R is trapezoidal, and the factorization can be written

.. math::
AP = Q\begin{pmatrix}R_1&R_2\end{pmatrix}\text{,}

where :math:R_1 is upper triangular and :math:R_2 is rectangular.

The matrix :math:Q is not formed explicitly but is represented as a product of :math:\mathrm{min}\left(m, n\right) elementary reflectors (see the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html>__ for details). Functions are provided to work with :math:Q in this representation (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08bef.html#fcomments>__).

Note also that for any :math:k < n, the information returned in the first :math:k columns of the array :math:\mathrm{a} represents a :math:QR factorization of the first :math:k columns of the permuted matrix :math:AP.

The function allows specified columns of :math:A to be moved to the leading columns of :math:AP at the start of the factorization and fixed there.
The remaining columns are free to be interchanged so that at the :math:i\ th stage the pivot column is chosen to be the column which maximizes the :math:2-norm of elements :math:i to :math:m over columns :math:i to :math:n.

.. _f08be-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 dgeqp3(a, jpvt):
r"""
dgeqp3 computes the :math:QR factorization, with column pivoting, of a real :math:m\times n matrix.

.. _f08bf-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08bff.html

.. _f08bf-py2-py-parameters:

**Parameters**
**a** : float, array-like, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:A.

**jpvt** : int, array-like, shape :math:\left(n\right)
If :math:\mathrm{jpvt}[j-1]\neq 0, the :math:j th column of :math:A is moved to the beginning of :math:AP before the decomposition is computed and is fixed in place during the computation. Otherwise, the :math:j th column of :math:A is a free column (i.e., one which may be interchanged during the computation with any other free column).

**Returns**
**a** : float, ndarray, shape :math:\left(m, n\right)
If :math:m\geq n, the elements below the diagonal are overwritten by details of the orthogonal matrix :math:Q and the upper triangle is overwritten by the corresponding elements of the :math:n\times n upper triangular matrix :math:R.

If :math:m < n, the strictly lower triangular part is overwritten by details of the orthogonal matrix :math:Q and the remaining elements are overwritten by the corresponding elements of the :math:m\times n upper trapezoidal matrix :math:R.

**jpvt** : int, ndarray, shape :math:\left(n\right)
Details of the permutation matrix :math:P. More precisely, if :math:\mathrm{jpvt}[j-1] = k, the :math:k\ th column of :math:A is moved to become the :math:j th column of :math:AP; in other words, the columns of :math:AP are the columns of :math:A in the order :math:\mathrm{jpvt},\mathrm{jpvt},\ldots,\mathrm{jpvt}[n-1].

**tau** : float, ndarray, shape :math:\left(\min\left(m,n\right)\right)
The scalar factors of the elementary reflectors.

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

.. _f08bf-py2-py-notes:

**Notes**
dgeqp3 forms the :math:QR factorization, with column pivoting, of an arbitrary rectangular real :math:m\times n matrix.

If :math:m\geq n, the factorization is given by:

.. math::
AP = Q\begin{pmatrix}R\\0\end{pmatrix}\text{,}

where :math:R is an :math:n\times n upper triangular matrix, :math:Q is an :math:m\times m orthogonal matrix and :math:P is an :math:n\times n permutation matrix.
It is sometimes more convenient to write the factorization as

.. math::
AP = \begin{pmatrix}Q_1&Q_2\end{pmatrix}\begin{pmatrix}R\\0\end{pmatrix}\text{,}

which reduces to

.. math::
AP = Q_1R\text{,}

where :math:Q_1 consists of the first :math:n columns of :math:Q, and :math:Q_2 the remaining :math:m-n columns.

If :math:m < n, :math:R is trapezoidal, and the factorization can be written

.. math::
AP = Q\begin{pmatrix}R_1&R_2\end{pmatrix}\text{,}

where :math:R_1 is upper triangular and :math:R_2 is rectangular.

The matrix :math:Q is not formed explicitly but is represented as a product of :math:\mathrm{min}\left(m, n\right) elementary reflectors (see the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html>__ for details). Functions are provided to work with :math:Q in this representation (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08bff.html#fcomments>__).

Note also that for any :math:k < n, the information returned in the first :math:k columns of the array :math:\mathrm{a} represents a :math:QR factorization of the first :math:k columns of the permuted matrix :math:AP.

The function allows specified columns of :math:A to be moved to the leading columns of :math:AP at the start of the factorization and fixed there.
The remaining columns are free to be interchanged so that at the :math:i\ th stage the pivot column is chosen to be the column which maximizes the :math:2-norm of elements :math:i to :math:m over columns :math:i to :math:n.

.. _f08bf-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 dtzrzf(a):
r"""
dtzrzf reduces the :math:m\times n (:math:m\leq n) real upper trapezoidal matrix :math:A to upper triangular form by means of orthogonal transformations.

.. _f08bh-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08bhf.html

.. _f08bh-py2-py-parameters:

**Parameters**
**a** : float, array-like, shape :math:\left(m, n\right)
The leading :math:m\times n upper trapezoidal part of the array :math:\mathrm{a} must contain the matrix to be factorized.

**Returns**
**a** : float, ndarray, shape :math:\left(m, n\right)
The leading :math:m\times m upper triangular part of :math:\mathrm{a} contains the upper triangular matrix :math:R, and elements :math:m+1 to :math:\textit{n} of the first :math:m rows of :math:\mathrm{a}, with the array :math:\mathrm{tau}, represent the orthogonal matrix :math:Z as a product of :math:m elementary reflectors (see the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html#recomm_36>__).

**tau** : float, ndarray, shape :math:\left(m\right)
The scalar factors of the elementary reflectors.

.. _f08bh-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 m.

.. _f08bh-py2-py-notes:

**Notes**
The :math:m\times n (:math:m\leq n) real upper trapezoidal matrix :math:A given by

.. math::
A = \begin{pmatrix}R_1&R_2\end{pmatrix}\text{,}

where :math:R_1 is an :math:m\times m upper triangular matrix and :math:R_2 is an :math:m\times \left(n-m\right) matrix, is factorized as

.. math::
A = \begin{pmatrix}R&0\end{pmatrix}Z\text{,}

where :math:R is also an :math:m\times m upper triangular matrix and :math:Z is an :math:n\times n orthogonal matrix.

.. _f08bh-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 dormrz(side, trans, l, a, tau, c):
r"""
dormrz multiplies a general real :math:m\times n matrix :math:C by the real orthogonal matrix :math:Z from an :math:RZ factorization computed by :meth:dtzrzf.

.. _f08bk-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08bkf.html

.. _f08bk-py2-py-parameters:

**Parameters**
**side** : str, length 1
Indicates how :math:Z or :math:Z^\mathrm{T} is to be applied to :math:C.

:math:\mathrm{side} = \texttt{'L'}

:math:Z or :math:Z^\mathrm{T} is applied to :math:C from the left.

:math:\mathrm{side} = \texttt{'R'}

:math:Z or :math:Z^\mathrm{T} is applied to :math:C from the right.

**trans** : str, length 1
Indicates whether :math:Z or :math:Z^\mathrm{T} is to be applied to :math:C.

:math:\mathrm{trans} = \texttt{'N'}

:math:Z is applied to :math:C.

:math:\mathrm{trans} = \texttt{'T'}

:math:Z^\mathrm{T} is applied to :math:C.

**l** : int
:math:l, the number of columns of the matrix :math:A containing the meaningful part of the Householder reflectors.

**a** : float, array-like, shape :math:\left(k, :\right)
Note: the required extent for this argument in dimension 2 is determined as follows: if :math:\mathrm{side}=\texttt{'L'}: :math:m; if :math:\mathrm{side}=\texttt{'R'}: :math:n; otherwise: :math:0.

The :math:\textit{i}\ th row of :math:\mathrm{a} must contain the vector which defines the elementary reflector :math:H_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,k, as returned by :meth:dtzrzf.

**tau** : float, array-like, shape :math:\left(k\right)
:math:\mathrm{tau}[i-1] must contain the scalar factor of the elementary reflector :math:H_i, as returned by :meth:dtzrzf.

**c** : float, array-like, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:C.

**Returns**
**c** : float, ndarray, shape :math:\left(m, n\right)
:math:\mathrm{c} is overwritten by :math:ZC or :math:Z^\mathrm{T}C or :math:CZ or :math:Z^\mathrm{T}C as specified by :math:\mathrm{side} and :math:\mathrm{trans}.

.. _f08bk-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{side}.

Constraint: :math:\mathrm{side} = \texttt{'L'} or :math:\texttt{'R'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{trans}.

Constraint: :math:\mathrm{trans} = \texttt{'N'} or :math:\texttt{'T'}.

(errno :math:-3)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

(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{k}.

Constraint: :math:m\geq k\geq 0.

(errno :math:-5)
On entry, error in parameter :math:\textit{k}.

Constraint: :math:n\geq k\geq 0.

(errno :math:-6)
On entry, error in parameter :math:\mathrm{l}.

Constraint: :math:m\geq \mathrm{l}\geq 0.

(errno :math:-6)
On entry, error in parameter :math:\mathrm{l}.

Constraint: :math:n\geq \mathrm{l}\geq 0.

.. _f08bk-py2-py-notes:

**Notes**
dormrz is intended to be used following a call to :meth:dtzrzf, which performs an :math:RZ factorization of a real upper trapezoidal matrix :math:A and represents the orthogonal matrix :math:Z as a product of elementary reflectors.

This function may be used to form one of the matrix products

.. math::

overwriting the result on :math:C, which may be any real rectangular :math:m\times n matrix.

.. _f08bk-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 zgelsy(a, b, jpvt, rcond):
r"""
zgelsy computes the minimum norm solution to a complex linear least squares problem

.. math::
\mathrm{min}_x\left\lVert b-Ax\right\rVert_2

using a complete orthogonal factorization of :math:A. :math:A is an :math:m\times n matrix which may be rank-deficient.
Several right-hand side vectors :math:b and solution vectors :math:x can be handled in a single call.

.. _f08bn-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08bnf.html

.. _f08bn-py2-py-parameters:

**Parameters**
**a** : complex, array-like, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:A.

**b** : complex, array-like, shape :math:\left(\max\left(m,n\right), \textit{nrhs}\right)
The :math:m\times r right-hand side matrix :math:B.

**jpvt** : int, array-like, shape :math:\left(n\right)
If :math:\mathrm{jpvt}[i-1]\neq 0, the :math:i\ th column of :math:A is permuted to the front of :math:AP, otherwise column :math:i is a free column.

**rcond** : float
Used to determine the effective rank of :math:A, which is defined as the order of the largest leading triangular sub-matrix :math:R_{11} in the :math:QR factorization of :math:A, whose estimated condition number is :math:\text{} < 1/\mathrm{rcond}.

Suggested value: if the condition number of :math:\mathrm{a} is not known then :math:\mathrm{rcond} = \sqrt{\left(\epsilon \right)/2} (where :math:\epsilon is machine precision, see :meth:machine.precision <naginterfaces.library.machine.precision>) is a good choice. Negative values or values less than machine precision should be avoided since this will cause :math:\mathrm{a} to have an effective :math:\text{rank} = \mathrm{min}\left(m, n\right) that could be larger than its actual rank, leading to meaningless results.

**Returns**
**a** : complex, ndarray, shape :math:\left(m, n\right)
:math:\mathrm{a} has been overwritten by details of its complete orthogonal factorization.

**b** : complex, ndarray, shape :math:\left(\max\left(m,n\right), \textit{nrhs}\right)
The :math:n\times r solution matrix :math:X.

**jpvt** : int, ndarray, shape :math:\left(n\right)
If :math:\mathrm{jpvt}[i-1] = k, the :math:i\ th column of :math:AP was the :math:k\ th column of :math:A.

**rank** : int
The effective rank of :math:A, i.e., the order of the sub-matrix :math:R_{11}. This is the same as the order of the sub-matrix :math:T_{11} in the complete orthogonal factorization of :math:A.

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

(errno :math:-3)
On entry, error in parameter :math:\textit{nrhs}.

Constraint: :math:\textit{nrhs}\geq 0.

.. _f08bn-py2-py-notes:

**Notes**
The right-hand side vectors are stored as the columns of the :math:m\times r matrix :math:B and the solution vectors in the :math:n\times r matrix :math:X.

zgelsy first computes a :math:QR factorization with column pivoting

.. math::
AP = Q\begin{pmatrix}R_{11}&R_{12}\\0&R_{22}\end{pmatrix}\text{,}

with :math:R_{11} defined as the largest leading sub-matrix whose estimated condition number is less than :math:1/\mathrm{rcond}.
The order of :math:R_{11}, :math:\mathrm{rank}, is the effective rank of :math:A.

Then, :math:R_{22} is considered to be negligible, and :math:R_{12} is annihilated by orthogonal transformations from the right, arriving at the complete orthogonal factorization

.. math::
AP = Q\begin{pmatrix}T_{11}&0\\0&0\end{pmatrix}Z\text{.}

The minimum norm solution is then

.. math::
X = PZ^\mathrm{H}\begin{pmatrix} T_{11}^{-1} Q_1^\mathrm{H} b \\0\end{pmatrix}

where :math:Q_1 consists of the first :math:\mathrm{rank} columns of :math:Q.

.. _f08bn-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 ztpqrt(l, nb, a, b):
r"""
ztpqrt computes the :math:QR factorization of a complex :math:\left(m+n\right)\times n triangular-pentagonal matrix.

.. _f08bp-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08bpf.html

.. _f08bp-py2-py-parameters:

**Parameters**
**l** : int
:math:l, the number of rows of the trapezoidal part of :math:B (i.e., :math:B_2).

**nb** : int
The explicitly chosen block-size to be used in the algorithm for computing the :math:QR factorization. See Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08bpf.html#fcomments>__ for details.

**a** : complex, array-like, shape :math:\left(n, n\right)
The :math:n\times n upper triangular matrix :math:A.

**b** : complex, array-like, shape :math:\left(m, n\right)
The :math:m\times n pentagonal matrix :math:B composed of an :math:\left(m-l\right)\times n rectangular matrix :math:B_1 above an :math:l\times n upper trapezoidal matrix :math:B_2.

**Returns**
**a** : complex, ndarray, shape :math:\left(n, n\right)
The upper triangle is overwritten by the corresponding elements of the :math:n\times n upper triangular matrix :math:R.

**b** : complex, ndarray, shape :math:\left(m, n\right)
Details of the unitary matrix :math:Q.

**t** : complex, ndarray, shape :math:\left(\mathrm{nb}, n\right)
Further details of the unitary matrix :math:Q. The number of blocks is :math:b = \left\lceil \frac{k}{\mathrm{nb}}\right\rceil, where :math:k = \mathrm{min}\left(m, n\right) and each block is of order :math:\mathrm{nb} except for the last block, which is of order :math:k-\left(b-1\right)\times \mathrm{nb}. For each of the blocks, an upper triangular block reflector factor is computed: :math:\boldsymbol{T}_1,\boldsymbol{T}_2,\ldots,\boldsymbol{T}_b. These are stored in the :math:\mathrm{nb}\times n matrix :math:T as :math:\boldsymbol{T} = \left[\boldsymbol{T}_1|\boldsymbol{T}_2| \cdots |\boldsymbol{T}_b\right].

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

(errno :math:-3)
On entry, error in parameter :math:\mathrm{l}.

Constraint: :math:0\leq \mathrm{l}\leq \mathrm{min}\left(m, n\right).

(errno :math:-4)
On entry, error in parameter :math:\mathrm{nb}.

Constraint: :math:\mathrm{nb}\geq 1.

(errno :math:-4)
On entry, error in parameter :math:\mathrm{nb}.

Constraint: :math:\mathrm{nb}\leq n.

.. _f08bp-py2-py-notes:

**Notes**
ztpqrt forms the :math:QR factorization of a complex :math:\left(m+n\right)\times n triangular-pentagonal matrix :math:C,

.. math::
C = \begin{pmatrix}A\\B\end{pmatrix}

where :math:A is an upper triangular :math:n\times n matrix and :math:B is an :math:m\times n pentagonal matrix consisting of an :math:\left(m-l\right)\times n rectangular matrix :math:B_1 on top of an :math:l\times n upper trapezoidal matrix :math:B_2:

.. math::
B = \begin{pmatrix}B_1\\B_2\end{pmatrix}\text{.}

The upper trapezoidal matrix :math:B_2 consists of the first :math:l rows of an :math:n\times n upper triangular matrix, where :math:0≤l≤\mathrm{min}\left(m, n\right).
If :math:l = 0, :math:B is :math:m\times n rectangular; if :math:l = n and :math:m = n, :math:B is upper triangular.

A recursive, explicitly blocked, :math:QR factorization (see :meth:zgeqrt) is performed on the matrix :math:C.
The upper triangular matrix :math:R, details of the unitary matrix :math:Q, and further details (the block reflector factors) of :math:Q are returned.

Typically the matrix :math:A or :math:B_2 contains the matrix :math:R from the :math:QR factorization of a subproblem and ztpqrt performs the :math:QR update operation from the inclusion of matrix :math:B_1.

For example, consider the :math:QR factorization of an :math:l\times n matrix :math:\hat{B} with :math:l < n: :math:\hat{B} = \hat{Q}\hat{R}, :math:\hat{R} = \begin{pmatrix}\hat{R_1}&\hat{R_2}\end{pmatrix}, where :math:\hat{R_1} is :math:l\times l upper triangular and :math:\hat{R_2} is :math:\left(n-l\right)\times n rectangular (this can be performed by :meth:zgeqrt).
Given an initial least squares problem :math:\hat{B}\hat{X} = \hat{Y} where :math:X and :math:Y are :math:l\times \textit{nrhs} matrices, we have :math:\hat{R}\hat{X} = \hat{Q}^\mathrm{H}\hat{Y}.

Now, adding an additional :math:m-l rows to the original system gives the augmented least squares problem

.. math::
BX = Y

where :math:B is an :math:m\times n matrix formed by adding :math:m-l rows on top of :math:\hat{R} and :math:Y is an :math:m\times \textit{nrhs} matrix formed by adding :math:m-l rows on top of :math:\hat{Q}^\mathrm{H}\hat{Y}.

ztpqrt can then be used to perform the :math:QR factorization of the pentagonal matrix :math:B; the :math:n\times n matrix :math:A will be zero on input and contain :math:R on output.

In the case where :math:\hat{B} is :math:r\times n, :math:r\geq n, :math:\hat{R} is :math:n\times n upper triangular (forming :math:A) on top of :math:r-n rows of zeros (forming first :math:r-n rows of :math:B).
Augmentation is then performed by adding rows to the bottom of :math:B with :math:l = 0.

.. _f08bp-py2-py-references:

**References**
Elmroth, E and Gustavson, F, 2000, Applying Recursion to Serial and Parallel :math:{QR} Factorization Leads to Better Performance, IBM Journal of Research and Development. (Volume 44) (4), 605--624

Golub, G H and Van Loan, C F, 2012, Matrix Computations, (4th Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError

[docs]def ztpmqrt(side, trans, l, v, t, c1, c2):
r"""
ztpmqrt multiplies an arbitrary complex matrix :math:C by the complex unitary matrix :math:Q from a :math:QR factorization computed by :meth:ztpqrt.

.. _f08bq-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08bqf.html

.. _f08bq-py2-py-parameters:

**Parameters**
**side** : str, length 1
Indicates how :math:Q or :math:Q^\mathrm{H} is to be applied to :math:C.

:math:\mathrm{side} = \texttt{'L'}

:math:Q or :math:Q^\mathrm{H} is applied to :math:C from the left.

:math:\mathrm{side} = \texttt{'R'}

:math:Q or :math:Q^\mathrm{H} is applied to :math:C from the right.

**trans** : str, length 1
Indicates whether :math:Q or :math:Q^\mathrm{H} is to be applied to :math:C.

:math:\mathrm{trans} = \texttt{'N'}

:math:Q is applied to :math:C.

:math:\mathrm{trans} = \texttt{'C'}

:math:Q^\mathrm{H} is applied to :math:C.

**l** : int
:math:l, the number of rows of the upper trapezoidal part of the pentagonal composite matrix :math:V, passed (as :math:\textit{b}) in a previous call to :meth:ztpqrt. This must be the same value used in the previous call to :meth:ztpqrt (see :math:\textit{l} in :meth:ztpqrt).

**v** : complex, array-like, shape :math:\left(:, k\right)
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\mathrm{side}=\texttt{'L'}: :math:m; if :math:\mathrm{side}=\texttt{'R'}: :math:n; otherwise: :math:0.

The :math:m_v\times n_v matrix :math:V; this should remain unchanged from the array :math:\textit{b} returned by a previous call to :meth:ztpqrt.

**t** : complex, array-like, shape :math:\left(\textit{nb}, k\right)
This must remain unchanged from a previous call to :meth:ztpqrt (see :math:\textit{t} in :meth:ztpqrt).

**c1** : complex, array-like, shape :math:\left(:, :\right)
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\mathrm{side}=\texttt{'L'}: :math:k; if :math:\mathrm{side}=\texttt{'R'}: :math:m; otherwise: :math:0.

Note: the required extent for this argument in dimension 2 is determined as follows: if :math:\mathrm{side}=\texttt{'L'}: :math:n; if :math:\mathrm{side}=\texttt{'R'}: :math:k; otherwise: :math:0.

:math:C_1, the first part of the composite matrix :math:C:

if :math:\mathrm{side} = \texttt{'L'}

then :math:\mathrm{c1} contains the first :math:k rows of :math:C;

if :math:\mathrm{side} = \texttt{'R'}

then :math:\mathrm{c1} contains the first :math:k columns of :math:C.

**c2** : complex, array-like, shape :math:\left(m, n\right)
:math:C_2, the second part of the composite matrix :math:C.

if :math:\mathrm{side} = \texttt{'L'}

then :math:\mathrm{c2} contains the remaining :math:m_v rows of :math:C;

if :math:\mathrm{side} = \texttt{'R'}

then :math:\mathrm{c2} contains the remaining :math:m_v columns of :math:C;

**Returns**
**c1** : complex, ndarray, shape :math:\left(:, :\right)
:math:\mathrm{c1} is overwritten by the corresponding block of :math:QC or :math:Q^\mathrm{H}C or :math:CQ or :math:CQ^\mathrm{H}.

**c2** : complex, ndarray, shape :math:\left(m, n\right)
:math:\mathrm{c2} is overwritten by the corresponding block of :math:QC or :math:Q^\mathrm{H}C or :math:CQ or :math:CQ^\mathrm{H}.

.. _f08bq-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{side}.

Constraint: :math:\mathrm{side} = \texttt{'L'} or :math:\texttt{'R'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{trans}.

Constraint: :math:\mathrm{trans} = \texttt{'N'} or :math:\texttt{'C'}.

(errno :math:-3)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

(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{k}.

Constraint: :math:k\geq 0.

(errno :math:-6)
On entry, error in parameter :math:\mathrm{l}.

Constraint: :math:0\leq \mathrm{l}\leq k.

(errno :math:-7)
On entry, error in parameter :math:\textit{nb}.

Constraint: :math:\textit{nb}\geq 1.

(errno :math:-7)
On entry, error in parameter :math:\textit{nb}.

Constraint: :math:\textit{nb}\leq k.

.. _f08bq-py2-py-notes:

**Notes**
ztpmqrt is intended to be used after a call to :meth:ztpqrt which performs a :math:QR factorization of a triangular-pentagonal matrix containing an upper triangular matrix :math:A over a pentagonal matrix :math:B.
The unitary matrix :math:Q is represented as a product of elementary reflectors.

This function may be used to form the matrix products

.. math::
QC,Q^\mathrm{H}C,CQ\text{ or }CQ^\mathrm{H}\text{,}

where the complex rectangular :math:m_c\times n_c matrix :math:C is split into component matrices :math:C_1 and :math:C_2.

If :math:Q is being applied from the left (:math:QC or :math:Q^\mathrm{H}C) then

.. math::
C = \begin{pmatrix}C_1\\C_2\end{pmatrix}

where :math:C_1 is :math:k\times n_c, :math:C_2 is :math:m_v\times n_c, :math:m_c = k+m_v is fixed and :math:m_v is the number of rows of the matrix :math:V containing the elementary reflectors (i.e., :math:\textit{m} as passed to :meth:ztpqrt); the number of columns of :math:V is :math:n_v (i.e., :math:\textit{n} as passed to :meth:ztpqrt).

If :math:Q is being applied from the right (:math:CQ or :math:CQ^\mathrm{H}) then

.. math::
C = \begin{pmatrix}C_1&C_2\end{pmatrix}

where :math:C_1 is :math:m_c\times k, and :math:C_2 is :math:m_c\times m_v and :math:n_c = k+m_v is fixed.

The matrices :math:C_1 and :math:C_2 are overwriten by the result of the matrix product.

A common application of this routine is in updating the solution of a linear least squares problem.

.. _f08bq-py2-py-references:

**References**
Golub, G H and Van Loan, C F, 2012, Matrix Computations, (4th Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError

[docs]def zgeqpf(a, jpvt):
r"""
zgeqpf computes the :math:QR factorization, with column pivoting, of a complex :math:m\times n matrix. zgeqpf is marked as deprecated by LAPACK; the replacement routine is :meth:zgeqp3 which makes better use of Level 3 BLAS.

.. deprecated:: 27.0.0.0
zgeqpf is deprecated.
Please use :meth:zgeqp3 instead.
See also the :ref:Replacement Calls <replace> document.

.. _f08bs-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08bsf.html

.. _f08bs-py2-py-parameters:

**Parameters**
**a** : complex, array-like, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:A.

**jpvt** : int, array-like, shape :math:\left(n\right)
If :math:\mathrm{jpvt}[i-1]\neq 0, the :math:i th column of :math:A is moved to the beginning of :math:AP before the decomposition is computed and is fixed in place during the computation. Otherwise, the :math:i th column of :math:A is a free column (i.e., one which may be interchanged during the computation with any other free column).

**Returns**
**a** : complex, ndarray, shape :math:\left(m, n\right)
If :math:m\geq n, the elements below the diagonal are overwritten by details of the unitary matrix :math:Q and the upper triangle is overwritten by the corresponding elements of the :math:n\times n upper triangular matrix :math:R.

If :math:m < n, the strictly lower triangular part is overwritten by details of the unitary matrix :math:Q and the remaining elements are overwritten by the corresponding elements of the :math:m\times n upper trapezoidal matrix :math:R.

The diagonal elements of :math:R are real.

**jpvt** : int, ndarray, shape :math:\left(n\right)
Details of the permutation matrix :math:P. More precisely, if :math:\mathrm{jpvt}[i-1] = k, the :math:k\ th column of :math:A is moved to become the :math:i th column of :math:AP; in other words, the columns of :math:AP are the columns of :math:A in the order :math:\mathrm{jpvt},\mathrm{jpvt},\ldots,\mathrm{jpvt}[n-1].

**tau** : complex, ndarray, shape :math:\left(\min\left(m,n\right)\right)
Further details of the unitary matrix :math:Q.

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

.. _f08bs-py2-py-notes:

**Notes**
zgeqpf forms the :math:QR factorization, with column pivoting, of an arbitrary rectangular complex :math:m\times n matrix.

If :math:m\geq n, the factorization is given by:

.. math::
AP = Q\begin{pmatrix}R\\0\end{pmatrix}\text{,}

where :math:R is an :math:n\times n upper triangular matrix (with real diagonal elements), :math:Q is an :math:m\times m unitary matrix and :math:P is an :math:n\times n permutation matrix.
It is sometimes more convenient to write the factorization as

.. math::
AP = \begin{pmatrix}Q_1&Q_2\end{pmatrix}\begin{pmatrix}R\\0\end{pmatrix}\text{,}

which reduces to

.. math::
AP = Q_1R\text{,}

where :math:Q_1 consists of the first :math:n columns of :math:Q, and :math:Q_2 the remaining :math:m-n columns.

If :math:m < n, :math:R is trapezoidal, and the factorization can be written

.. math::
AP = Q\begin{pmatrix}R_1&R_2\end{pmatrix}\text{,}

where :math:R_1 is upper triangular and :math:R_2 is rectangular.

The matrix :math:Q is not formed explicitly but is represented as a product of :math:\mathrm{min}\left(m, n\right) elementary reflectors (see the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html>__ for details). Functions are provided to work with :math:Q in this representation (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08bsf.html#fcomments>__).

Note also that for any :math:k < n, the information returned in the first :math:k columns of the array :math:\mathrm{a} represents a :math:QR factorization of the first :math:k columns of the permuted matrix :math:AP.

The function allows specified columns of :math:A to be moved to the leading columns of :math:AP at the start of the factorization and fixed there.
The remaining columns are free to be interchanged so that at the :math:i\ th stage the pivot column is chosen to be the column which maximizes the :math:2-norm of elements :math:i to :math:m over columns :math:i to :math:n.

.. _f08bs-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 zgeqp3(a, jpvt):
r"""
zgeqp3 computes the :math:QR factorization, with column pivoting, of a complex :math:m\times n matrix.

.. _f08bt-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08btf.html

.. _f08bt-py2-py-parameters:

**Parameters**
**a** : complex, array-like, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:A.

**jpvt** : int, array-like, shape :math:\left(n\right)
If :math:\mathrm{jpvt}[j-1]\neq 0, the :math:j th column of :math:A is moved to the beginning of :math:AP before the decomposition is computed and is fixed in place during the computation. Otherwise, the :math:j th column of :math:A is a free column (i.e., one which may be interchanged during the computation with any other free column).

**Returns**
**a** : complex, ndarray, shape :math:\left(m, n\right)
If :math:m\geq n, the elements below the diagonal are overwritten by details of the unitary matrix :math:Q and the upper triangle is overwritten by the corresponding elements of the :math:n\times n upper triangular matrix :math:R.

If :math:m < n, the strictly lower triangular part is overwritten by details of the unitary matrix :math:Q and the remaining elements are overwritten by the corresponding elements of the :math:m\times n upper trapezoidal matrix :math:R.

The diagonal elements of :math:R are real.

**jpvt** : int, ndarray, shape :math:\left(n\right)
Details of the permutation matrix :math:P. More precisely, if :math:\mathrm{jpvt}[j-1] = k, the :math:k\ th column of :math:A is moved to become the :math:j th column of :math:AP; in other words, the columns of :math:AP are the columns of :math:A in the order :math:\mathrm{jpvt},\mathrm{jpvt},\ldots,\mathrm{jpvt}[n-1].

**tau** : complex, ndarray, shape :math:\left(\min\left(m,n\right)\right)
Further details of the unitary matrix :math:Q.

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

.. _f08bt-py2-py-notes:

**Notes**
zgeqp3 forms the :math:QR factorization, with column pivoting, of an arbitrary rectangular complex :math:m\times n matrix.

If :math:m\geq n, the factorization is given by:

.. math::
AP = Q\begin{pmatrix}R\\0\end{pmatrix}\text{,}

where :math:R is an :math:n\times n upper triangular matrix (with real diagonal elements), :math:Q is an :math:m\times m unitary matrix and :math:P is an :math:n\times n permutation matrix.
It is sometimes more convenient to write the factorization as

.. math::
AP = \begin{pmatrix}Q_1&Q_2\end{pmatrix}\begin{pmatrix}R\\0\end{pmatrix}\text{,}

which reduces to

.. math::
AP = Q_1R\text{,}

where :math:Q_1 consists of the first :math:n columns of :math:Q, and :math:Q_2 the remaining :math:m-n columns.

If :math:m < n, :math:R is trapezoidal, and the factorization can be written

.. math::
AP = Q\begin{pmatrix}R_1&R_2\end{pmatrix}\text{,}

where :math:R_1 is upper triangular and :math:R_2 is rectangular.

The matrix :math:Q is not formed explicitly but is represented as a product of :math:\mathrm{min}\left(m, n\right) elementary reflectors (see the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html>__ for details). Functions are provided to work with :math:Q in this representation (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08btf.html#fcomments>__).

Note also that for any :math:k < n, the information returned in the first :math:k columns of the array :math:\mathrm{a} represents a :math:QR factorization of the first :math:k columns of the permuted matrix :math:AP.

The function allows specified columns of :math:A to be moved to the leading columns of :math:AP at the start of the factorization and fixed there.
The remaining columns are free to be interchanged so that at the :math:i\ th stage the pivot column is chosen to be the column which maximizes the :math:2-norm of elements :math:i to :math:m over columns :math:i to :math:n.

.. _f08bt-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 ztzrzf(a):
r"""
ztzrzf reduces the :math:m\times n (:math:m\leq n) complex upper trapezoidal matrix :math:A to upper triangular form by means of unitary transformations.

.. _f08bv-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08bvf.html

.. _f08bv-py2-py-parameters:

**Parameters**
**a** : complex, array-like, shape :math:\left(m, n\right)
The leading :math:m\times n upper trapezoidal part of the array :math:\mathrm{a} must contain the matrix to be factorized.

**Returns**
**a** : complex, ndarray, shape :math:\left(m, n\right)
The leading :math:m\times m upper triangular part of :math:\mathrm{a} contains the upper triangular matrix :math:R, and elements :math:m+1 to :math:\textit{n} of the first :math:m rows of :math:\mathrm{a}, with the array :math:\mathrm{tau}, represent the unitary matrix :math:Z as a product of :math:m elementary reflectors (see the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html#recomm_36>__).

**tau** : complex, ndarray, shape :math:\left(m\right)
The scalar factors of the elementary reflectors.

.. _f08bv-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 m.

.. _f08bv-py2-py-notes:

**Notes**
The :math:m\times n (:math:m\leq n) complex upper trapezoidal matrix :math:A given by

.. math::
A = \begin{pmatrix}R_1&R_2\end{pmatrix}\text{,}

where :math:R_1 is an :math:m\times m upper triangular matrix and :math:R_2 is an :math:m\times \left(n-m\right) matrix, is factorized as

.. math::
A = \begin{pmatrix}R&0\end{pmatrix}Z\text{,}

where :math:R is also an :math:m\times m upper triangular matrix and :math:Z is an :math:n\times n unitary matrix.

.. _f08bv-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 zunmrz(side, trans, l, a, tau, c):
r"""
zunmrz multiplies a general complex :math:m\times n matrix :math:C by the complex unitary matrix :math:Z from an :math:RZ factorization computed by :meth:ztzrzf.

.. _f08bx-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08bxf.html

.. _f08bx-py2-py-parameters:

**Parameters**
**side** : str, length 1
Indicates how :math:Z or :math:Z^\mathrm{H} is to be applied to :math:C.

:math:\mathrm{side} = \texttt{'L'}

:math:Z or :math:Z^\mathrm{H} is applied to :math:C from the left.

:math:\mathrm{side} = \texttt{'R'}

:math:Z or :math:Z^\mathrm{H} is applied to :math:C from the right.

**trans** : str, length 1
Indicates whether :math:Z or :math:Z^\mathrm{H} is to be applied to :math:C.

:math:\mathrm{trans} = \texttt{'N'}

:math:Z is applied to :math:C.

:math:\mathrm{trans} = \texttt{'C'}

:math:Z^\mathrm{H} is applied to :math:C.

**l** : int
:math:l, the number of columns of the matrix :math:A containing the meaningful part of the Householder reflectors.

**a** : complex, array-like, shape :math:\left(k, :\right)
Note: the required extent for this argument in dimension 2 is determined as follows: if :math:\mathrm{side}=\texttt{'L'}: :math:m; if :math:\mathrm{side}=\texttt{'R'}: :math:n; otherwise: :math:0.

The :math:\textit{i}\ th row of :math:\mathrm{a} must contain the vector which defines the elementary reflector :math:H_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,k, as returned by :meth:ztzrzf.

**tau** : complex, array-like, shape :math:\left(k\right)
:math:\mathrm{tau}[i-1] must contain the scalar factor of the elementary reflector :math:H_i, as returned by :meth:ztzrzf.

**c** : complex, array-like, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:C.

**Returns**
**c** : complex, ndarray, shape :math:\left(m, n\right)
:math:\mathrm{c} is overwritten by :math:ZC or :math:Z^\mathrm{H}C or :math:CZ or :math:Z^\mathrm{H}C as specified by :math:\mathrm{side} and :math:\mathrm{trans}.

.. _f08bx-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{side}.

Constraint: :math:\mathrm{side} = \texttt{'L'} or :math:\texttt{'R'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{trans}.

Constraint: :math:\mathrm{trans} = \texttt{'N'} or :math:\texttt{'C'}.

(errno :math:-3)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

(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{k}.

Constraint: :math:m\geq k\geq 0.

(errno :math:-5)
On entry, error in parameter :math:\textit{k}.

Constraint: :math:n\geq k\geq 0.

(errno :math:-6)
On entry, error in parameter :math:\mathrm{l}.

Constraint: :math:m\geq \mathrm{l}\geq 0.

(errno :math:-6)
On entry, error in parameter :math:\mathrm{l}.

Constraint: :math:n\geq \mathrm{l}\geq 0.

.. _f08bx-py2-py-notes:

**Notes**
zunmrz is intended to be used following a call to :meth:ztzrzf, which performs an :math:RZ factorization of a real upper trapezoidal matrix :math:A and represents the unitary matrix :math:Z as a product of elementary reflectors.

This function may be used to form one of the matrix products

.. math::

overwriting the result on :math:C, which may be any complex rectangular :math:m\times n matrix.

.. _f08bx-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 dgeqlf(a):
r"""
dgeqlf computes a :math:QL factorization of a real :math:m\times n matrix :math:A.

.. _f08ce-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08cef.html

.. _f08ce-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)
If :math:m\geq n, the lower triangle of the subarray :math:\mathrm{a}[m-n:m,0:n] contains the :math:n\times n lower triangular matrix :math:L.

If :math:m\leq n, the elements on and below the :math:\left(n-m\right)\ th superdiagonal contain the :math:m\times n lower trapezoidal matrix :math:L.

The remaining elements, with the array :math:\mathrm{tau}, represent the orthogonal matrix :math:Q as a product of elementary reflectors (see the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html#recomm_36>__).

**tau** : float, ndarray, shape :math:\left(\min\left(m,n\right)\right)
The scalar factors of the elementary reflectors (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08cef.html#fcomments>__).

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

.. _f08ce-py2-py-notes:

**Notes**
dgeqlf forms the :math:QL factorization of an arbitrary rectangular real :math:m\times n matrix.

If :math:m\geq n, the factorization is given by:

.. math::
A = Q\begin{pmatrix}0\\L\end{pmatrix}\text{,}

where :math:L is an :math:n\times n lower triangular matrix and :math:Q is an :math:m\times m orthogonal matrix.
If :math:m < n the factorization is given by

.. math::
A = QL\text{,}

where :math:L is an :math:m\times n lower trapezoidal matrix and :math:Q is again an :math:m\times m orthogonal matrix.
In the case where :math:m > n the factorization can be expressed as

.. math::
A = \begin{pmatrix}Q_1&Q_2\end{pmatrix}\begin{pmatrix}0\\L\end{pmatrix} = Q_2L\text{,}

where :math:Q_1 consists of the first :math:m-n columns of :math:Q, and :math:Q_2 the remaining :math:n columns.

The matrix :math:Q is not formed explicitly but is represented as a product of :math:\mathrm{min}\left(m, n\right) elementary reflectors (see the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html#recomm_36>__ for details). Functions are provided to work with :math:Q in this representation (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08cef.html#fcomments>__).

Note also that for any :math:k < n, the information returned in the last :math:k columns of the array :math:\mathrm{a} represents a :math:QL factorization of the last :math:\textit{k } columns of the original matrix :math:A.

.. _f08ce-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 dorgql(a, tau):
r"""
dorgql generates all or part of the real :math:m\times m orthogonal matrix :math:Q from a :math:QL factorization computed by :meth:dgeqlf.

.. _f08cf-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08cff.html

.. _f08cf-py2-py-parameters:

**Parameters**
**a** : float, array-like, shape :math:\left(m, n\right)
Details of the vectors which define the elementary reflectors, as returned by :meth:dgeqlf.

**tau** : float, array-like, shape :math:\left(k\right)
Further details of the elementary reflectors, as returned by :meth:dgeqlf.

**Returns**
**a** : float, ndarray, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:Q.

.. _f08cf-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:m\geq n\geq 0.

(errno :math:-3)
On entry, error in parameter :math:\textit{k}.

Constraint: :math:n\geq k\geq 0.

.. _f08cf-py2-py-notes:

**Notes**
dorgql is intended to be used after a call to :meth:dgeqlf, which performs a :math:QL factorization of a real matrix :math:A.
The orthogonal matrix :math:Q is represented as a product of elementary reflectors.

This function may be used to generate :math:Q explicitly as a square matrix, or to form only its trailing columns.

Usually :math:Q is determined from the :math:QL factorization of an :math:m\times p matrix :math:A with :math:m\geq p.
The whole of :math:Q may be computed by calling dorgql with :math:\textit{n} set to :math:m and :math:\textit{k} set to :math:p or its trailing :math:p columns by calling dorgql with :math:\textit{n} and :math:\textit{k} set to :math:p.

The columns of :math:Q returned by the last call form an orthonormal basis for the space spanned by the columns of :math:A; thus :meth:dgeqlf followed by dorgql can be used to orthogonalize the columns of :math:A.

The information returned by :meth:dgeqlf also yields the :math:QL factorization of the trailing :math:k columns of :math:A, where :math:k < p.
The orthogonal matrix arising from this factorization can be computed by calling dorgql with :math:\textit{n} set to :math:m or its trailing :math:k columns by calling dorgql with :math:\textit{n} set to :math:k.

.. _f08cf-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 dormql(side, trans, a, tau, c):
r"""
dormql multiplies a general real :math:m\times n matrix :math:C by the real orthogonal matrix :math:Q from a :math:QL factorization computed by :meth:dgeqlf.

.. _f08cg-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08cgf.html

.. _f08cg-py2-py-parameters:

**Parameters**
**side** : str, length 1
Indicates how :math:Q or :math:Q^\mathrm{T} is to be applied to :math:C.

:math:\mathrm{side} = \texttt{'L'}

:math:Q or :math:Q^\mathrm{T} is applied to :math:C from the left.

:math:\mathrm{side} = \texttt{'R'}

:math:Q or :math:Q^\mathrm{T} is applied to :math:C from the right.

**trans** : str, length 1
Indicates whether :math:Q or :math:Q^\mathrm{T} is to be applied to :math:C.

:math:\mathrm{trans} = \texttt{'N'}

:math:Q is applied to :math:C.

:math:\mathrm{trans} = \texttt{'T'}

:math:Q^\mathrm{T} is applied to :math:C.

**a** : float, array-like, shape :math:\left(:, k\right)
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\mathrm{side}=\texttt{'L'}: :math:m; if :math:\mathrm{side}=\texttt{'R'}: :math:n; otherwise: :math:0.

On entry: details of the vectors which define the elementary reflectors, as returned by :meth:dgeqlf.

On exit: is modified by dormql but restored on exit.

**tau** : float, array-like, shape :math:\left(k\right)
Further details of the elementary reflectors, as returned by :meth:dgeqlf.

**c** : float, array-like, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:C.

**Returns**
**c** : float, ndarray, shape :math:\left(m, n\right)
:math:\mathrm{c} is overwritten by :math:QC or :math:Q^\mathrm{T}C or :math:CQ or :math:CQ^\mathrm{T} as specified by :math:\mathrm{side} and :math:\mathrm{trans}.

.. _f08cg-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{side}.

Constraint: :math:\mathrm{side} = \texttt{'L'} or :math:\texttt{'R'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{trans}.

Constraint: :math:\mathrm{trans} = \texttt{'N'} or :math:\texttt{'T'}.

(errno :math:-3)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

(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{k}.

Constraint: :math:m\geq k\geq 0.

(errno :math:-5)
On entry, error in parameter :math:\textit{k}.

Constraint: :math:n\geq k\geq 0.

.. _f08cg-py2-py-notes:

**Notes**
dormql is intended to be used following a call to :meth:dgeqlf, which performs a :math:QL factorization of a real matrix :math:A and represents the orthogonal matrix :math:Q as a product of elementary reflectors.

This function may be used to form one of the matrix products

.. math::

overwriting the result on :math:C, which may be any real rectangular :math:m\times n matrix.

A common application of this function is in solving linear least squares problems, as described in the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html>__.

.. _f08cg-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 dgerqf(a):
r"""
dgerqf computes an :math:RQ factorization of a real :math:m\times n matrix :math:A.

.. _f08ch-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08chf.html

.. _f08ch-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)
If :math:m\leq n, the upper triangle of the subarray :math:\mathrm{a}[0:m,n-m:n] contains the :math:m\times m upper triangular matrix :math:R.

If :math:m\geq n, the elements on and above the :math:\left(m-n\right)\ th subdiagonal contain the :math:m\times n upper trapezoidal matrix :math:R; the remaining elements, with the array :math:\mathrm{tau}, represent the orthogonal matrix :math:Q as a product of :math:\mathrm{min}\left(m, n\right) elementary reflectors (see the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html#recomm_36>__).

**tau** : float, ndarray, shape :math:\left(\min\left(m,n\right)\right)
The scalar factors of the elementary reflectors.

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

.. _f08ch-py2-py-notes:

**Notes**
dgerqf forms the :math:RQ factorization of an arbitrary rectangular real :math:m\times n matrix.
If :math:m\leq n, the factorization is given by

.. math::
A = \begin{pmatrix}0&R\end{pmatrix}Q\text{,}

where :math:R is an :math:m\times m lower triangular matrix and :math:Q is an :math:n\times n orthogonal matrix.
If :math:m > n the factorization is given by

.. math::
A = RQ\text{,}

where :math:R is an :math:m\times n upper trapezoidal matrix and :math:Q is again an :math:n\times n orthogonal matrix.
In the case where :math:m < n the factorization can be expressed as

.. math::
A = \begin{pmatrix}0&R\end{pmatrix}\begin{pmatrix}Q_1\\Q_2\end{pmatrix} = RQ_2\text{,}

where :math:Q_1 consists of the first :math:\left(n-m\right) rows of :math:Q and :math:Q_2 the remaining :math:m rows.

The matrix :math:Q is not formed explicitly, but is represented as a product of :math:\mathrm{min}\left(m, n\right) elementary reflectors (see the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html>__ for details). Functions are provided to work with :math:Q in this representation (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08chf.html#fcomments>__).

.. _f08ch-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 dorgrq(a, tau):
r"""
dorgrq generates all or part of the real :math:n\times n orthogonal matrix :math:Q from an :math:RQ factorization computed by :meth:dgerqf.

.. _f08cj-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08cjf.html

.. _f08cj-py2-py-parameters:

**Parameters**
**a** : float, array-like, shape :math:\left(m, n\right)
Details of the vectors which define the elementary reflectors, as returned by :meth:dgerqf.

**tau** : float, array-like, shape :math:\left(k\right)
:math:\mathrm{tau}[i-1] must contain the scalar factor of the elementary reflector :math:H_i, as returned by :meth:dgerqf.

**Returns**
**a** : float, ndarray, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:Q.

.. _f08cj-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 m.

(errno :math:-3)
On entry, error in parameter :math:\textit{k}.

Constraint: :math:m\geq k\geq 0.

.. _f08cj-py2-py-notes:

**Notes**
dorgrq is intended to be used following a call to :meth:dgerqf, which performs an :math:RQ factorization of a real matrix :math:A and represents the orthogonal matrix :math:Q as a product of :math:k elementary reflectors of order :math:n.

This function may be used to generate :math:Q explicitly as a square matrix, or to form only its trailing rows.

Usually :math:Q is determined from the :math:RQ factorization of a :math:p\times n matrix :math:A with :math:p\leq n.
The whole of :math:Q may be computed by calling dorgrq with :math:\textit{m} set to :math:n and :math:\textit{k} set to :math:p or its trailing :math:p rows by calling dorgrq with :math:\textit{m} and :math:\textit{k} set to :math:p.

The rows of :math:Q returned by the last call form an orthonormal basis for the space spanned by the rows of :math:A; thus :meth:dgerqf followed by dorgrq can be used to orthogonalize the rows of :math:A.

The information returned by :meth:dgerqf also yields the :math:RQ factorization of the trailing :math:k rows of :math:A, where :math:k < p.
The orthogonal matrix arising from this factorization can be computed by calling dorgrq with :math:\textit{m} set to :math:n or its leading :math:k columns by calling dorgrq with :math:\textit{m} set to :math:k.

.. _f08cj-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 dormrq(side, trans, a, tau, c):
r"""
dormrq multiplies a general real :math:m\times n matrix :math:C by the real orthogonal matrix :math:Q from an :math:RQ factorization computed by :meth:dgerqf.

.. _f08ck-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08ckf.html

.. _f08ck-py2-py-parameters:

**Parameters**
**side** : str, length 1
Indicates how :math:Q or :math:Q^\mathrm{T} is to be applied to :math:C.

:math:\mathrm{side} = \texttt{'L'}

:math:Q or :math:Q^\mathrm{T} is applied to :math:C from the left.

:math:\mathrm{side} = \texttt{'R'}

:math:Q or :math:Q^\mathrm{T} is applied to :math:C from the right.

**trans** : str, length 1
Indicates whether :math:Q or :math:Q^\mathrm{T} is to be applied to :math:C.

:math:\mathrm{trans} = \texttt{'N'}

:math:Q is applied to :math:C.

:math:\mathrm{trans} = \texttt{'T'}

:math:Q^\mathrm{T} is applied to :math:C.

**a** : float, array-like, shape :math:\left(k, :\right)
Note: the required extent for this argument in dimension 2 is determined as follows: if :math:\mathrm{side}=\texttt{'L'}: :math:m; if :math:\mathrm{side}=\texttt{'R'}: :math:n; otherwise: :math:0.

The :math:\textit{i}\ th row of :math:\mathrm{a} must contain the vector which defines the elementary reflector :math:H_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,k, as returned by :meth:dgerqf.

**tau** : float, array-like, shape :math:\left(k\right)
:math:\mathrm{tau}[i-1] must contain the scalar factor of the elementary reflector :math:H_i, as returned by :meth:dgerqf.

**c** : float, array-like, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:C.

**Returns**
**a** : float, ndarray, shape :math:\left(k, :\right)
Is modified by dormrq but restored on exit.

**c** : float, ndarray, shape :math:\left(m, n\right)
:math:\mathrm{c} is overwritten by :math:QC or :math:Q^\mathrm{T}C or :math:CQ or :math:CQ^\mathrm{T} as specified by :math:\mathrm{side} and :math:\mathrm{trans}.

.. _f08ck-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{side}.

Constraint: :math:\mathrm{side} = \texttt{'L'} or :math:\texttt{'R'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{trans}.

Constraint: :math:\mathrm{trans} = \texttt{'N'} or :math:\texttt{'T'}.

(errno :math:-3)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

(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{k}.

Constraint: :math:m\geq k\geq 0.

(errno :math:-5)
On entry, error in parameter :math:\textit{k}.

Constraint: :math:n\geq k\geq 0.

.. _f08ck-py2-py-notes:

**Notes**
dormrq is intended to be used following a call to :meth:dgerqf, which performs an :math:RQ factorization of a real matrix :math:A and represents the orthogonal matrix :math:Q as a product of elementary reflectors.

This function may be used to form one of the matrix products

.. math::

overwriting the result on :math:C, which may be any real rectangular :math:m\times n matrix.

A common application of this function is in solving underdetermined linear least squares problems, as described in the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html>__.

.. _f08ck-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 zgeqlf(a):
r"""
zgeqlf computes a :math:QL factorization of a complex :math:m\times n matrix :math:A.

.. _f08cs-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08csf.html

.. _f08cs-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)
If :math:m\geq n, the lower triangle of the subarray :math:\mathrm{a}[m-n:m,0:n] contains the :math:n\times n lower triangular matrix :math:L.

If :math:m\leq n, the elements on and below the :math:\left(n-m\right)\ th superdiagonal contain the :math:m\times n lower trapezoidal matrix :math:L.

The remaining elements, with the array :math:\mathrm{tau}, represent the unitary matrix :math:Q as a product of elementary reflectors (see the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html#recomm_36>__).

**tau** : complex, ndarray, shape :math:\left(\min\left(m,n\right)\right)
The scalar factors of the elementary reflectors (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08csf.html#fcomments>__).

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

.. _f08cs-py2-py-notes:

**Notes**
zgeqlf forms the :math:QL factorization of an arbitrary rectangular complex :math:m\times n matrix.

If :math:m\geq n, the factorization is given by:

.. math::
A = Q\begin{pmatrix}0\\L\end{pmatrix}\text{,}

where :math:L is an :math:n\times n lower triangular matrix and :math:Q is an :math:m\times m unitary matrix.
If :math:m < n the factorization is given by

.. math::
A = QL\text{,}

where :math:L is an :math:m\times n lower trapezoidal matrix and :math:Q is again an :math:m\times m unitary matrix.
In the case where :math:m > n the factorization can be expressed as

.. math::
A = \begin{pmatrix}Q_1&Q_2\end{pmatrix}\begin{pmatrix}0\\L\end{pmatrix} = Q_2L\text{,}

where :math:Q_1 consists of the first :math:m-n columns of :math:Q, and :math:Q_2 the remaining :math:n columns.

The matrix :math:Q is not formed explicitly but is represented as a product of :math:\mathrm{min}\left(m, n\right) elementary reflectors (see the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html#recomm_36>__ for details). Functions are provided to work with :math:Q in this representation (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08csf.html#fcomments>__).

Note also that for any :math:k < n, the information returned in the last :math:k columns of the array :math:\mathrm{a} represents a :math:QL factorization of the last :math:\textit{k } columns of the original matrix :math:A.

.. _f08cs-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 zungql(a, tau):
r"""
zungql generates all or part of the complex :math:m\times m unitary matrix :math:Q from a :math:QL factorization computed by :meth:zgeqlf.

.. _f08ct-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08ctf.html

.. _f08ct-py2-py-parameters:

**Parameters**
**a** : complex, array-like, shape :math:\left(m, n\right)
Details of the vectors which define the elementary reflectors, as returned by :meth:zgeqlf.

**tau** : complex, array-like, shape :math:\left(k\right)
Further details of the elementary reflectors, as returned by :meth:zgeqlf.

**Returns**
**a** : complex, ndarray, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:Q.

.. _f08ct-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:m\geq n\geq 0.

(errno :math:-3)
On entry, error in parameter :math:\textit{k}.

Constraint: :math:n\geq k\geq 0.

.. _f08ct-py2-py-notes:

**Notes**
zungql is intended to be used after a call to :meth:zgeqlf, which performs a :math:QL factorization of a complex matrix :math:A.
The unitary matrix :math:Q is represented as a product of elementary reflectors.

This function may be used to generate :math:Q explicitly as a square matrix, or to form only its trailing columns.

Usually :math:Q is determined from the :math:QL factorization of an :math:m\times p matrix :math:A with :math:m\geq p.
The whole of :math:Q may be computed by calling zungql with :math:\textit{n} set to :math:m or its trailing :math:p columns by calling zungql with :math:\textit{n} and :math:\textit{k} set to :math:p.

The columns of :math:Q returned by the last call form an orthonormal basis for the space spanned by the columns of :math:A; thus :meth:zgeqlf followed by zungql can be used to orthogonalize the columns of :math:A.

The information returned by :meth:zgeqlf also yields the :math:QL factorization of the trailing :math:k columns of :math:A, where :math:k < p.
The unitary matrix arising from this factorization can be computed by calling zungql with :math:\textit{n} set to :math:m or its trailing :math:k columns by calling zungql with :math:\textit{n} set to :math:k.

.. _f08ct-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 zunmql(side, trans, a, tau, c):
r"""
zunmql multiplies a general complex :math:m\times n matrix :math:C by the complex unitary matrix :math:Q from a :math:QL factorization computed by :meth:zgeqlf.

.. _f08cu-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08cuf.html

.. _f08cu-py2-py-parameters:

**Parameters**
**side** : str, length 1
Indicates how :math:Q or :math:Q^\mathrm{H} is to be applied to :math:C.

:math:\mathrm{side} = \texttt{'L'}

:math:Q or :math:Q^\mathrm{H} is applied to :math:C from the left.

:math:\mathrm{side} = \texttt{'R'}

:math:Q or :math:Q^\mathrm{H} is applied to :math:C from the right.

**trans** : str, length 1
Indicates whether :math:Q or :math:Q^\mathrm{H} is to be applied to :math:C.

:math:\mathrm{trans} = \texttt{'N'}

:math:Q is applied to :math:C.

:math:\mathrm{trans} = \texttt{'C'}

:math:Q^\mathrm{H} is applied to :math:C.

**a** : complex, array-like, shape :math:\left(:, k\right)
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\mathrm{side}=\texttt{'L'}: :math:m; if :math:\mathrm{side}=\texttt{'R'}: :math:n; otherwise: :math:0.

On entry: details of the vectors which define the elementary reflectors, as returned by :meth:zgeqlf.

On exit: is modified by zunmql but restored on exit.

**tau** : complex, array-like, shape :math:\left(k\right)
Further details of the elementary reflectors, as returned by :meth:zgeqlf.

**c** : complex, array-like, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:C.

**Returns**
**c** : complex, ndarray, shape :math:\left(m, n\right)
:math:\mathrm{c} is overwritten by :math:QC or :math:Q^\mathrm{H}C or :math:CQ or :math:CQ^\mathrm{H} as specified by :math:\mathrm{side} and :math:\mathrm{trans}.

.. _f08cu-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{side}.

Constraint: :math:\mathrm{side} = \texttt{'L'} or :math:\texttt{'R'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{trans}.

Constraint: :math:\mathrm{trans} = \texttt{'N'} or :math:\texttt{'C'}.

(errno :math:-3)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

(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{k}.

Constraint: :math:m\geq k\geq 0.

(errno :math:-5)
On entry, error in parameter :math:\textit{k}.

Constraint: :math:n\geq k\geq 0.

.. _f08cu-py2-py-notes:

**Notes**
zunmql is intended to be used following a call to :meth:zgeqlf, which performs a :math:QL factorization of a complex matrix :math:A and represents the unitary matrix :math:Q as a product of elementary reflectors.

This function may be used to form one of the matrix products

.. math::

overwriting the result on :math:C, which may be any complex rectangular :math:m\times n matrix.

A common application of this function is in solving linear least squares problems, as described in the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html>__.

.. _f08cu-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 zgerqf(a):
r"""
zgerqf computes an :math:RQ factorization of a complex :math:m\times n matrix :math:A.

.. _f08cv-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08cvf.html

.. _f08cv-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)
If :math:m\leq n, the upper triangle of the subarray :math:\mathrm{a}[0:m,n-m:n] contains the :math:m\times m upper triangular matrix :math:R.

If :math:m\geq n, the elements on and above the :math:\left(m-n\right)\ th subdiagonal contain the :math:m\times n upper trapezoidal matrix :math:R; the remaining elements, with the array :math:\mathrm{tau}, represent the unitary matrix :math:Q as a product of :math:\mathrm{min}\left(m, n\right) elementary reflectors (see the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html#recomm_36>__).

**tau** : complex, ndarray, shape :math:\left(\min\left(m,n\right)\right)
The scalar factors of the elementary reflectors.

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

.. _f08cv-py2-py-notes:

**Notes**
zgerqf forms the :math:RQ factorization of an arbitrary rectangular real :math:m\times n matrix.
If :math:m\leq n, the factorization is given by

.. math::
A = \begin{pmatrix}0&R\end{pmatrix}Q\text{,}

where :math:R is an :math:m\times m lower triangular matrix and :math:Q is an :math:n\times n unitary matrix.
If :math:m > n the factorization is given by

.. math::
A = RQ\text{,}

where :math:R is an :math:m\times n upper trapezoidal matrix and :math:Q is again an :math:n\times n unitary matrix.
In the case where :math:m < n the factorization can be expressed as

.. math::
A = \begin{pmatrix}0&R\end{pmatrix}\begin{pmatrix}Q_1\\Q_2\end{pmatrix} = RQ_2\text{,}

where :math:Q_1 consists of the first :math:\left(n-m\right) rows of :math:Q and :math:Q_2 the remaining :math:m rows.

The matrix :math:Q is not formed explicitly, but is represented as a product of :math:\mathrm{min}\left(m, n\right) elementary reflectors (see the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html>__ for details). Functions are provided to work with :math:Q in this representation (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08cvf.html#fcomments>__).

.. _f08cv-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 zungrq(a, tau):
r"""
zungrq generates all or part of the complex :math:n\times n unitary matrix :math:Q from an :math:RQ factorization computed by :meth:zgerqf.

.. _f08cw-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08cwf.html

.. _f08cw-py2-py-parameters:

**Parameters**
**a** : complex, array-like, shape :math:\left(m, n\right)
Details of the vectors which define the elementary reflectors, as returned by :meth:zgerqf.

**tau** : complex, array-like, shape :math:\left(k\right)
:math:\mathrm{tau}[i-1] must contain the scalar factor of the elementary reflector :math:H_i, as returned by :meth:zgerqf.

**Returns**
**a** : complex, ndarray, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:Q.

.. _f08cw-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 m.

(errno :math:-3)
On entry, error in parameter :math:\textit{k}.

Constraint: :math:m\geq k\geq 0.

.. _f08cw-py2-py-notes:

**Notes**
zungrq is intended to be used following a call to :meth:zgerqf, which performs an :math:RQ factorization of a complex matrix :math:A and represents the unitary matrix :math:Q as a product of :math:k elementary reflectors of order :math:n.

This function may be used to generate :math:Q explicitly as a square matrix, or to form only its trailing rows.

Usually :math:Q is determined from the :math:RQ factorization of a :math:p\times n matrix :math:A with :math:p\leq n.
The whole of :math:Q may be computed by calling zungrq with :math:\textit{m} set to :math:n and :math:\textit{k} set to :math:p or its trailing :math:p rows by calling zungrq with :math:\textit{m} and :math:\textit{k} set to :math:p.

The rows of :math:Q returned by the last call form an orthonormal basis for the space spanned by the rows of :math:A; thus :meth:zgerqf followed by zungrq can be used to orthogonalize the rows of :math:A.

The information returned by :meth:zgerqf also yields the :math:RQ factorization of the trailing :math:k rows of :math:A, where :math:k < p.
The unitary matrix arising from this factorization can be computed by calling zungrq with :math:\textit{m} set to :math:n or its leading :math:k columns by calling zungrq with :math:\textit{m} set to :math:k.

.. _f08cw-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 zunmrq(side, trans, a, tau, c):
r"""
zunmrq multiplies a general complex :math:m\times n matrix :math:C by the complex unitary matrix :math:Q from an :math:RQ factorization computed by :meth:zgerqf.

.. _f08cx-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08cxf.html

.. _f08cx-py2-py-parameters:

**Parameters**
**side** : str, length 1
Indicates how :math:Q or :math:Q^\mathrm{H} is to be applied to :math:C.

:math:\mathrm{side} = \texttt{'L'}

:math:Q or :math:Q^\mathrm{H} is applied to :math:C from the left.

:math:\mathrm{side} = \texttt{'R'}

:math:Q or :math:Q^\mathrm{H} is applied to :math:C from the right.

**trans** : str, length 1
Indicates whether :math:Q or :math:Q^\mathrm{H} is to be applied to :math:C.

:math:\mathrm{trans} = \texttt{'N'}

:math:Q is applied to :math:C.

:math:\mathrm{trans} = \texttt{'C'}

:math:Q^\mathrm{H} is applied to :math:C.

**a** : complex, array-like, shape :math:\left(k, :\right)
Note: the required extent for this argument in dimension 2 is determined as follows: if :math:\mathrm{side}=\texttt{'L'}: :math:m; if :math:\mathrm{side}=\texttt{'R'}: :math:n; otherwise: :math:0.

The :math:\textit{i}\ th row of :math:\mathrm{a} must contain the vector which defines the elementary reflector :math:H_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,k, as returned by :meth:zgerqf.

**tau** : complex, array-like, shape :math:\left(k\right)
:math:\mathrm{tau}[i-1] must contain the scalar factor of the elementary reflector :math:H_i, as returned by :meth:zgerqf.

**c** : complex, array-like, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:C.

**Returns**
**a** : complex, ndarray, shape :math:\left(k, :\right)
Is modified by zunmrq but restored on exit.

**c** : complex, ndarray, shape :math:\left(m, n\right)
:math:\mathrm{c} is overwritten by :math:QC or :math:Q^\mathrm{H}C or :math:CQ or :math:CQ^\mathrm{H} as specified by :math:\mathrm{side} and :math:\mathrm{trans}.

.. _f08cx-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{side}.

Constraint: :math:\mathrm{side} = \texttt{'L'} or :math:\texttt{'R'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{trans}.

Constraint: :math:\mathrm{trans} = \texttt{'N'} or :math:\texttt{'C'}.

(errno :math:-3)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

(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{k}.

Constraint: :math:m\geq k\geq 0.

(errno :math:-5)
On entry, error in parameter :math:\textit{k}.

Constraint: :math:n\geq k\geq 0.

.. _f08cx-py2-py-notes:

**Notes**
zunmrq is intended to be used following a call to :meth:zgerqf, which performs an :math:RQ factorization of a complex matrix :math:A and represents the unitary matrix :math:Q as a product of elementary reflectors.

This function may be used to form one of the matrix products

.. math::

overwriting the result on :math:C, which may be any complex rectangular :math:m\times n matrix.

A common application of this function is in solving underdetermined linear least squares problems, as described in the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html>__.

.. _f08cx-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 dsyev(jobz, uplo, a):
r"""
dsyev computes all the eigenvalues and, optionally, all the eigenvectors of a real :math:n\times n symmetric matrix :math:A.

.. _f08fa-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08faf.html

.. _f08fa-py2-py-parameters:

**Parameters**
**jobz** : str, length 1
Indicates whether eigenvectors are computed.

:math:\mathrm{jobz} = \texttt{'N'}

Only eigenvalues are computed.

:math:\mathrm{jobz} = \texttt{'V'}

Eigenvalues and eigenvectors are computed.

**uplo** : str, length 1
If :math:\mathrm{uplo} = \texttt{'U'}, the upper triangular part of :math:A is stored.

If :math:\mathrm{uplo} = \texttt{'L'}, the lower triangular part of :math:A is stored.

**a** : float, array-like, shape :math:\left(n, n\right)
The :math:n\times n symmetric matrix :math:A.

**Returns**
**a** : None or float, ndarray, shape :math:\left(n, n\right)
If :math:\mathrm{jobz} = \texttt{'V'}, :math:\mathrm{a} contains the orthonormal eigenvectors of the matrix :math:A.

**w** : float, ndarray, shape :math:\left(n\right)
The eigenvalues in ascending order.

.. _f08fa-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{jobz}.

Constraint: :math:\mathrm{jobz} = \texttt{'N'} or :math:\texttt{'V'}.

(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:i > 0)
The algorithm failed to converge; :math:\langle\mathit{\boldsymbol{value}}\rangle off-diagonal elements of an intermediate tridiagonal form did not converge to zero.

.. _f08fa-py2-py-notes:

**Notes**
The symmetric matrix :math:A is first reduced to tridiagonal form, using orthogonal similarity transformations, and then the :math:QR algorithm is applied to the tridiagonal matrix to compute the eigenvalues and (optionally) the eigenvectors.

.. _f08fa-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 dsyevx(jobz, erange, uplo, a, vl, vu, il, iu, abstol):
r"""
dsyevx computes selected eigenvalues and, optionally, eigenvectors of a real :math:n\times n symmetric matrix :math:A.
Eigenvalues and eigenvectors can be selected by specifying either a range of values or a range of indices for the desired eigenvalues.

.. _f08fb-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08fbf.html

.. _f08fb-py2-py-parameters:

**Parameters**
**jobz** : str, length 1
Indicates whether eigenvectors are computed.

:math:\mathrm{jobz} = \texttt{'N'}

Only eigenvalues are computed.

:math:\mathrm{jobz} = \texttt{'V'}

Eigenvalues and eigenvectors are computed.

**erange** : str, length 1
If :math:\mathrm{erange} = \texttt{'A'}, all eigenvalues will be found.

If :math:\mathrm{erange} = \texttt{'V'}, all eigenvalues in the half-open interval :math:\left(\mathrm{vl}, \mathrm{vu}\right] will be found.

If :math:\mathrm{erange} = \texttt{'I'}, the :math:\mathrm{il}\ th to :math:\mathrm{iu}\ th eigenvalues will be found.

**uplo** : str, length 1
If :math:\mathrm{uplo} = \texttt{'U'}, the upper triangular part of :math:A is stored.

If :math:\mathrm{uplo} = \texttt{'L'}, the lower triangular part of :math:A is stored.

**a** : float, array-like, shape :math:\left(n, n\right)
The :math:n\times n symmetric matrix :math:A.

**vl** : float
If :math:\mathrm{erange} = \texttt{'V'}, the lower and upper bounds of the interval to be searched for eigenvalues.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'I'}, :math:\mathrm{vl} and :math:\mathrm{vu} are not referenced.

**vu** : float
If :math:\mathrm{erange} = \texttt{'V'}, the lower and upper bounds of the interval to be searched for eigenvalues.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'I'}, :math:\mathrm{vl} and :math:\mathrm{vu} are not referenced.

**il** : int
If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{il} and :math:\mathrm{iu} specify the indices (in ascending order) of the smallest and largest eigenvalues to be returned, respectively.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}, :math:\mathrm{il} and :math:\mathrm{iu} are not referenced.

**iu** : int
If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{il} and :math:\mathrm{iu} specify the indices (in ascending order) of the smallest and largest eigenvalues to be returned, respectively.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}, :math:\mathrm{il} and :math:\mathrm{iu} are not referenced.

**abstol** : float
The absolute error tolerance for the eigenvalues. An approximate eigenvalue is accepted as converged when it is determined to lie in an interval :math:\left[a, b\right] of width less than or equal to

.. math::
\mathrm{abstol}+\epsilon \mathrm{max}\left(\left\lvert a\right\rvert, \left\lvert b\right\rvert \right)\text{,}

where :math:\epsilon is the machine precision. If :math:\mathrm{abstol} is less than or equal to zero, then :math:\epsilon \left\lVert T\right\rVert_1 will be used in its place, where :math:T is the tridiagonal matrix obtained by reducing :math:A to tridiagonal form. Eigenvalues will be computed most accurately when :math:\mathrm{abstol} is set to twice the underflow threshold :math:2\times \texttt{machine.real_safe}\left(\right), not zero. If this function returns with :math:\mathrm{errno} > 0, indicating that some eigenvectors did not converge, try setting :math:\mathrm{abstol} to :math:2\times \texttt{machine.real_safe}\left(\right). See Demmel and Kahan (1990).

**Returns**
**a** : float, ndarray, shape :math:\left(n, n\right)
The lower triangle (if :math:\mathrm{uplo} = \texttt{'L'}) or the upper triangle (if :math:\mathrm{uplo} = \texttt{'U'}) of :math:\mathrm{a}, including the diagonal, is overwritten.

**m** : int
The total number of eigenvalues found. :math:0\leq \mathrm{m}\leq n.

If :math:\mathrm{erange} = \texttt{'A'}, :math:\mathrm{m} = n.

If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{m} = \mathrm{iu}-\mathrm{il}+1.

**w** : float, ndarray, shape :math:\left(n\right)
The first :math:\mathrm{m} elements contain the selected eigenvalues in ascending order.

**z** : float, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobz} = \texttt{'V'}, then

if no exception or warning is raised, the first :math:\mathrm{m} columns of :math:Z contain the orthonormal eigenvectors of the matrix :math:A corresponding to the selected eigenvalues, with the :math:i\ th column of :math:Z holding the eigenvector associated with :math:\mathrm{w}[i-1];

if an eigenvector fails to converge (:math:\mathrm{errno} > 0), then that column of :math:Z contains the latest approximation to the eigenvector, and the index of the eigenvector is returned in :math:\mathrm{jfail}.

If :math:\mathrm{jobz} = \texttt{'N'}, :math:\mathrm{z} is not referenced.

**Note:** you must ensure that at least :math:\mathrm{max}\left(1, \mathrm{m}\right) columns are supplied in the array :math:\mathrm{z}; if :math:\mathrm{erange} = \texttt{'V'}, the exact value of :math:\mathrm{m} is not known in advance and an upper bound of at least :math:\textit{n} must be used.

**jfail** : int, ndarray, shape :math:\left(n\right)
If :math:\mathrm{jobz} = \texttt{'V'}, then

if no exception or warning is raised, the first :math:\mathrm{m} elements of :math:\mathrm{jfail} are zero;

if :math:\mathrm{errno} > 0, :math:\mathrm{jfail} contains the indices of the eigenvectors that failed to converge.

If :math:\mathrm{jobz} = \texttt{'N'}, :math:\mathrm{jfail} is not referenced.

.. _f08fb-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{jobz}.

Constraint: :math:\mathrm{jobz} = \texttt{'N'} or :math:\texttt{'V'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{erange}.

Constraint: :math:\mathrm{erange} = \texttt{'A'}, :math:\texttt{'V'} or :math:\texttt{'I'}.

(errno :math:-3)
On entry, error in parameter :math:\mathrm{uplo}.

Constraint: :math:\mathrm{uplo} = \texttt{'U'} or :math:\texttt{'L'}.

(errno :math:-4)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

(errno :math:-8)
On entry, error in parameter :math:\mathrm{vu}.

Constraint: :math:\mathrm{vl} < \mathrm{vu}.

(errno :math:-9)
On entry, error in parameter :math:\mathrm{il}.

(errno :math:-10)
On entry, error in parameter :math:\mathrm{iu}.

**Warns**
**NagAlgorithmicWarning**
(errno :math:i > 0)
The algorithm failed to converge; :math:\langle\mathit{\boldsymbol{value}}\rangle eigenvectors did not converge. Their indices are stored in array :math:\mathrm{jfail}.

.. _f08fb-py2-py-notes:

**Notes**
The symmetric matrix :math:A is first reduced to tridiagonal form, using orthogonal similarity transformations.
The required eigenvalues and eigenvectors are then computed from the tridiagonal matrix; the method used depends upon whether all, or selected, eigenvalues and eigenvectors are required.

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

Demmel, J W and Kahan, W, 1990, Accurate singular values of bidiagonal matrices, SIAM J. Sci. Statist. Comput. (11), 873--912

Golub, G H and Van Loan, C F, 1996, Matrix Computations, (3rd Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError

[docs]def dsyevd(job, uplo, a):
r"""
dsyevd computes all the eigenvalues and, optionally, all the eigenvectors of a real symmetric matrix. If the eigenvectors are requested, then it uses a divide-and-conquer algorithm to compute eigenvalues and eigenvectors.
However, if only eigenvalues are required, then it uses the Pal--Walker--Kahan variant of the :math:QL or :math:QR algorithm.

.. _f08fc-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08fcf.html

.. _f08fc-py2-py-parameters:

**Parameters**
**job** : str, length 1
Indicates whether eigenvectors are computed.

:math:\mathrm{job} = \texttt{'N'}

Only eigenvalues are computed.

:math:\mathrm{job} = \texttt{'V'}

Eigenvalues and eigenvectors are computed.

**uplo** : str, length 1
Indicates 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.

**a** : float, array-like, shape :math:\left(n, n\right)
The :math:n\times n symmetric matrix :math:A.

**Returns**
**a** : float, ndarray, shape :math:\left(n, n\right)
If :math:\mathrm{job} = \texttt{'V'}, :math:\mathrm{a} is overwritten by the orthogonal matrix :math:Z which contains the eigenvectors of :math:A.

**w** : float, ndarray, shape :math:\left(n\right)
The eigenvalues of the matrix :math:A in ascending order.

.. _f08fc-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{job}.

Constraint: :math:\mathrm{job} = \texttt{'N'} or :math:\texttt{'V'}.

(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:i > 0)
If :math:\textit{errno} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{job} = \texttt{'N'}, the algorithm failed to converge; :math:\langle\mathit{\boldsymbol{value}}\rangle elements of an intermediate tridiagonal form did not converge to zero; if :math:\textit{errno} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{job} = \texttt{'V'}, then the algorithm failed to compute an eigenvalue while working on the submatrix lying in rows and column :math:\langle\mathit{\boldsymbol{value}}\rangle/\left(n+1\right) through :math:\mathrm{mod}\left(\langle\mathit{\boldsymbol{value}}\rangle, {n+1}\right).

.. _f08fc-py2-py-notes:

**Notes**
dsyevd computes all the eigenvalues and, optionally, all the eigenvectors of a real symmetric matrix :math:A. In other words, it can compute the spectral factorization of :math:A as

.. math::
A = Z\Lambda Z^\mathrm{T}\text{,}

where :math:\Lambda is a diagonal matrix whose diagonal elements are the eigenvalues :math:\lambda_i, and :math:Z is the orthogonal matrix whose columns are the eigenvectors :math:z_i.
Thus

.. math::
Az_i = \lambda_iz_i\text{, }\quad i = 1,2,\ldots,n\text{.}

.. _f08fc-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 dsyevr(jobz, erange, uplo, a, vl, vu, il, iu, abstol):
r"""
dsyevr computes selected eigenvalues and, optionally, eigenvectors of a real :math:n\times n symmetric matrix :math:A.
Eigenvalues and eigenvectors can be selected by specifying either a range of values or a range of indices for the desired eigenvalues.

.. _f08fd-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08fdf.html

.. _f08fd-py2-py-parameters:

**Parameters**
**jobz** : str, length 1
Indicates whether eigenvectors are computed.

:math:\mathrm{jobz} = \texttt{'N'}

Only eigenvalues are computed.

:math:\mathrm{jobz} = \texttt{'V'}

Eigenvalues and eigenvectors are computed.

**erange** : str, length 1
If :math:\mathrm{erange} = \texttt{'A'}, all eigenvalues will be found.

If :math:\mathrm{erange} = \texttt{'V'}, all eigenvalues in the half-open interval :math:\left(\mathrm{vl}, \mathrm{vu}\right] will be found.

If :math:\mathrm{erange} = \texttt{'I'}, the :math:\mathrm{il}\ th to :math:\mathrm{iu}\ th eigenvalues will be found.

For :math:\mathrm{erange} = \texttt{'V'} or :math:\texttt{'I'} and :math:\mathrm{iu}-\mathrm{il} < n-1, :meth:dstebz and :meth:dstein are called.

**uplo** : str, length 1
If :math:\mathrm{uplo} = \texttt{'U'}, the upper triangular part of :math:A is stored.

If :math:\mathrm{uplo} = \texttt{'L'}, the lower triangular part of :math:A is stored.

**a** : float, array-like, shape :math:\left(n, n\right)
The :math:n\times n symmetric matrix :math:A.

**vl** : float
If :math:\mathrm{erange} = \texttt{'V'}, the lower and upper bounds of the interval to be searched for eigenvalues.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'I'}, :math:\mathrm{vl} and :math:\mathrm{vu} are not referenced.

**vu** : float
If :math:\mathrm{erange} = \texttt{'V'}, the lower and upper bounds of the interval to be searched for eigenvalues.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'I'}, :math:\mathrm{vl} and :math:\mathrm{vu} are not referenced.

**il** : int
If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{il} and :math:\mathrm{iu} specify the indices (in ascending order) of the smallest and largest eigenvalues to be returned, respectively.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}, :math:\mathrm{il} and :math:\mathrm{iu} are not referenced.

**iu** : int
If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{il} and :math:\mathrm{iu} specify the indices (in ascending order) of the smallest and largest eigenvalues to be returned, respectively.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}, :math:\mathrm{il} and :math:\mathrm{iu} are not referenced.

**abstol** : float
The absolute error tolerance for the eigenvalues. An approximate eigenvalue is accepted as converged when it is determined to lie in an interval :math:\left[a, b\right] of width less than or equal to

.. math::
\mathrm{abstol}+\epsilon \mathrm{max}\left(\left\lvert a\right\rvert, \left\lvert b\right\rvert \right)\text{,}

where :math:\epsilon is the machine precision. If :math:\mathrm{abstol} is less than or equal to zero, then :math:\epsilon \left\lVert T\right\rVert_1 will be used in its place, where :math:T is the tridiagonal matrix obtained by reducing :math:A to tridiagonal form. See Demmel and Kahan (1990).

If high relative accuracy is important, set :math:\mathrm{abstol} to :math:\texttt{machine.real_safe}\left(\right), although doing so does not currently guarantee that eigenvalues are computed to high relative accuracy.

See Barlow and Demmel (1990) for a discussion of which matrices can define their eigenvalues to high relative accuracy.

**Returns**
**a** : float, ndarray, shape :math:\left(n, n\right)
The lower triangle (if :math:\mathrm{uplo} = \texttt{'L'}) or the upper triangle (if :math:\mathrm{uplo} = \texttt{'U'}) of :math:\mathrm{a}, including the diagonal, is overwritten.

**m** : int
The total number of eigenvalues found. :math:0\leq \mathrm{m}\leq n.

If :math:\mathrm{erange} = \texttt{'A'}, :math:\mathrm{m} = n.

If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{m} = \mathrm{iu}-\mathrm{il}+1.

**w** : float, ndarray, shape :math:\left(n\right)
The first :math:\mathrm{m} elements contain the selected eigenvalues in ascending order.

**z** : float, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobz} = \texttt{'V'}, the first :math:\mathrm{m} columns of :math:Z contain the orthonormal eigenvectors of the matrix :math:A corresponding to the selected eigenvalues, with the :math:i\ th column of :math:Z holding the eigenvector associated with :math:\mathrm{w}[i-1].

If :math:\mathrm{jobz} = \texttt{'N'}, :math:\mathrm{z} is not referenced.

**Note:** you must ensure that at least :math:\mathrm{max}\left(1, \mathrm{m}\right) columns are supplied in the array :math:\mathrm{z}; if :math:\mathrm{erange} = \texttt{'V'}, the exact value of :math:\mathrm{m} is not known in advance and an upper bound of at least :math:\textit{n} must be used.

**isuppz** : int, ndarray, shape :math:\left(:\right)
The support of the eigenvectors in :math:\mathrm{z}, i.e., the indices indicating the nonzero elements in :math:\mathrm{z}. The :math:i\ th eigenvector is nonzero only in elements :math:\mathrm{isuppz}[2\times i-2] through :math:\mathrm{isuppz}[2\times i-1]. Implemented only for :math:\mathrm{erange} = \texttt{'A'} or :math:\mathrm{erange} = \texttt{'I'} and :math:\mathrm{iu}-\mathrm{il} = n-1.

.. _f08fd-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{jobz}.

Constraint: :math:\mathrm{jobz} = \texttt{'N'} or :math:\texttt{'V'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{erange}.

Constraint: :math:\mathrm{erange} = \texttt{'A'}, :math:\texttt{'V'} or :math:\texttt{'I'}.

(errno :math:-3)
On entry, error in parameter :math:\mathrm{uplo}.

Constraint: :math:\mathrm{uplo} = \texttt{'U'} or :math:\texttt{'L'}.

(errno :math:-4)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

(errno :math:-8)
On entry, error in parameter :math:\mathrm{vu}.

Constraint: :math:\mathrm{vl} < \mathrm{vu}.

(errno :math:-9)
On entry, error in parameter :math:\mathrm{il}.

(errno :math:-10)
On entry, error in parameter :math:\mathrm{iu}.

(errno :math:i > 0)
dsyevr failed to converge.

.. _f08fd-py2-py-notes:

**Notes**
The symmetric matrix is first reduced to a tridiagonal matrix :math:T, using orthogonal similarity transformations.
Then whenever possible, dsyevr computes the eigenspectrum using Relatively Robust Representations. dsyevr computes eigenvalues by the dqds algorithm, while orthogonal eigenvectors are computed from various 'good' :math:LDL^\mathrm{T} representations (also known as Relatively Robust Representations).
Gram--Schmidt orthogonalization is avoided as far as possible.
More specifically, the various steps of the algorithm are as follows.
For the :math:i\ th unreduced block of :math:T:

(a) compute :math:T-\sigma_iI = L_iD_iL_i^\mathrm{T}, such that :math:L_iD_iL_i^\mathrm{T} is a relatively robust representation,

(#) compute the eigenvalues, :math:\lambda_j, of :math:L_iD_iL_i^\mathrm{T} to high relative accuracy by the dqds algorithm,

(#) if there is a cluster of close eigenvalues, 'choose' :math:\sigma_i close to the cluster, and go to \(a),

(#) given the approximate eigenvalue :math:\lambda_j of :math:L_iD_iL_i^\mathrm{T}, compute the corresponding eigenvector by forming a rank-revealing twisted factorization.

The desired accuracy of the output can be specified by the argument :math:\mathrm{abstol}.
For more details, see Dhillon (1997) and Parlett and Dhillon (2000).

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

Barlow, J and Demmel, J W, 1990, Computing accurate eigensystems of scaled diagonally dominant matrices, SIAM J. Numer. Anal. (27), 762--791

Demmel, J W and Kahan, W, 1990, Accurate singular values of bidiagonal matrices, SIAM J. Sci. Statist. Comput. (11), 873--912

Dhillon, I, 1997, A new :math:\mathrm{O}\left(n^2\right) algorithm for the symmetric tridiagonal eigenvalue/eigenvector problem, Computer Science Division Technical Report No. UCB//CSD-97-971, UC Berkeley

Golub, G H and Van Loan, C F, 1996, Matrix Computations, (3rd Edition), Johns Hopkins University Press, Baltimore

Parlett, B N and Dhillon, I S, 2000, Relatively robust representations of symmetric tridiagonals, Linear Algebra Appl. (309), 121--151
"""
raise NotImplementedError

[docs]def dsytrd(uplo, a):
r"""
dsytrd reduces a real symmetric matrix to tridiagonal form.

.. _f08fe-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08fef.html

.. _f08fe-py2-py-parameters:

**Parameters**
**uplo** : str, length 1
Indicates 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.

**a** : float, array-like, shape :math:\left(n, n\right)
The :math:n\times n symmetric matrix :math:A.

**Returns**
**a** : float, ndarray, shape :math:\left(n, n\right)
:math:\mathrm{a} is overwritten by the tridiagonal matrix :math:T and details of the orthogonal matrix :math:Q as specified by :math:\mathrm{uplo}.

**d** : float, ndarray, shape :math:\left(n\right)
The diagonal elements of the tridiagonal matrix :math:T.

**e** : float, ndarray, shape :math:\left(\max\left(1,{n-1}\right)\right)
The off-diagonal elements of the tridiagonal matrix :math:T.

**tau** : float, ndarray, shape :math:\left(\max\left(1,{n-1}\right)\right)
Further details of the orthogonal matrix :math:Q.

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

.. _f08fe-py2-py-notes:

**Notes**
dsytrd reduces a real symmetric matrix :math:A to symmetric tridiagonal form :math:T by an orthogonal similarity transformation: :math:A = QTQ^\mathrm{T}.

The matrix :math:Q is not formed explicitly but is represented as a product of :math:n-1 elementary reflectors (see the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html>__ for details). Functions are provided to work with :math:Q in this representation (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08fef.html#fcomments>__).

.. _f08fe-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 dorgtr(uplo, a, tau):
r"""
dorgtr generates the real orthogonal matrix :math:Q, which was determined by :meth:dsytrd when reducing a symmetric matrix to tridiagonal form.

.. _f08ff-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08fff.html

.. _f08ff-py2-py-parameters:

**Parameters**
**uplo** : str, length 1
This **must** be the same argument :math:\mathrm{uplo} as supplied to :meth:dsytrd.

**a** : float, array-like, shape :math:\left(n, n\right)
Details of the vectors which define the elementary reflectors, as returned by :meth:dsytrd.

**tau** : float, array-like, shape :math:\left(\max\left(1,{n-1}\right)\right)
Further details of the elementary reflectors, as returned by :meth:dsytrd.

**Returns**
**a** : float, ndarray, shape :math:\left(n, n\right)
The :math:n\times n orthogonal matrix :math:Q.

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

.. _f08ff-py2-py-notes:

**Notes**
dorgtr is intended to be used after a call to :meth:dsytrd, which reduces a real symmetric matrix :math:A to symmetric tridiagonal form :math:T by an orthogonal similarity transformation: :math:A = QTQ^\mathrm{T}. :meth:dsytrd represents the orthogonal matrix :math:Q as a product of :math:n-1 elementary reflectors.

This function may be used to generate :math:Q explicitly as a square matrix.

.. _f08ff-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 dormtr(side, uplo, trans, a, tau, c):
r"""
dormtr multiplies an arbitrary real matrix :math:C by the real orthogonal matrix :math:Q which was determined by :meth:dsytrd when reducing a real symmetric matrix to tridiagonal form.

.. _f08fg-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08fgf.html

.. _f08fg-py2-py-parameters:

**Parameters**
**side** : str, length 1
Indicates how :math:Q or :math:Q^\mathrm{T} is to be applied to :math:C.

:math:\mathrm{side} = \texttt{'L'}

:math:Q or :math:Q^\mathrm{T} is applied to :math:C from the left.

:math:\mathrm{side} = \texttt{'R'}

:math:Q or :math:Q^\mathrm{T} is applied to :math:C from the right.

**uplo** : str, length 1
This **must** be the same argument :math:\mathrm{uplo} as supplied to :meth:dsytrd.

**trans** : str, length 1
Indicates whether :math:Q or :math:Q^\mathrm{T} is to be applied to :math:C.

:math:\mathrm{trans} = \texttt{'N'}

:math:Q is applied to :math:C.

:math:\mathrm{trans} = \texttt{'T'}

:math:Q^\mathrm{T} is applied to :math:C.

**a** : float, array-like, shape :math:\left(:, :\right)
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\mathrm{side}=\texttt{'L'}: :math:m; if :math:\mathrm{side}=\texttt{'R'}: :math:n; otherwise: :math:0.

Note: the required extent for this argument in dimension 2 is determined as follows: if :math:\mathrm{side}=\texttt{'L'}: :math:m; if :math:\mathrm{side}=\texttt{'R'}: :math:n; otherwise: :math:0.

Details of the vectors which define the elementary reflectors, as returned by :meth:dsytrd.

**tau** : float, array-like, shape :math:\left(:\right)
Note: the required length for this argument is determined as follows: if :math:\mathrm{side}=\texttt{'L'}: :math:{m-1}; if :math:\mathrm{side}=\texttt{'R'}: :math:{n-1}; otherwise: :math:0.

Further details of the elementary reflectors, as returned by :meth:dsytrd.

**c** : float, array-like, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:C.

**Returns**
**c** : float, ndarray, shape :math:\left(m, n\right)
:math:\mathrm{c} is overwritten by :math:QC or :math:Q^\mathrm{T}C or :math:CQ or :math:CQ^\mathrm{T} as specified by :math:\mathrm{side} and :math:\mathrm{trans}.

.. _f08fg-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{side}.

Constraint: :math:\mathrm{side} = \texttt{'L'} or :math:\texttt{'R'}.

(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{trans}.

Constraint: :math:\mathrm{trans} = \texttt{'N'} or :math:\texttt{'T'}.

(errno :math:-4)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

(errno :math:-5)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

.. _f08fg-py2-py-notes:

**Notes**
dormtr is intended to be used after a call to :meth:dsytrd, which reduces a real symmetric matrix :math:A to symmetric tridiagonal form :math:T by an orthogonal similarity transformation: :math:A = QTQ^\mathrm{T}. :meth:dsytrd represents the orthogonal matrix :math:Q as a product of elementary reflectors.

This function may be used to form one of the matrix products

.. math::
QC,Q^\mathrm{T}C,CQ\text{ or }CQ^\mathrm{T}\text{,}

overwriting the result on :math:C (which may be any real rectangular matrix).

A common application of this function is to transform a matrix :math:Z of eigenvectors of :math:T to the matrix :math:\textit{QZ} of eigenvectors of :math:A.

.. _f08fg-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 ddisna(job, m, n, d):
r"""
ddisna computes the reciprocal condition numbers for the eigenvectors of a real symmetric or complex Hermitian :math:m\times m matrix :math:A, or for the left or right singular vectors of a general :math:m\times n matrix :math:A.

.. _f08fl-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08flf.html

.. _f08fl-py2-py-parameters:

**Parameters**
**job** : str, length 1
Specifies for which problem the reciprocal condition number should be computed.

:math:\mathrm{job} = \texttt{'E'}

The eigenvectors of a symmetric or Hermitian matrix.

:math:\mathrm{job} = \texttt{'L'}

The left singular vectors of a general matrix.

:math:\mathrm{job} = \texttt{'R'}

The right singular vectors of a general matrix.

**m** : int
:math:m, the number of rows of the matrix :math:A.

**n** : int
:math:n, the number of columns of the matrix when :math:\mathrm{job} = \texttt{'L'} or :math:\texttt{'R'}.

If :math:\mathrm{job} = \texttt{'E'}, :math:\mathrm{n} is not referenced.

**d** : float, array-like, shape :math:\left(:\right)
Note: the required length for this argument is determined as follows: if :math:\mathrm{job}=\texttt{'E'}: :math:\mathrm{m}; if :math:\mathrm{job}\text{ in } (\texttt{'L'}, \texttt{'R'}): :math:\min\left(\mathrm{m},\mathrm{n}\right); otherwise: :math:0.

The eigenvalues if :math:\mathrm{job} = \texttt{'E'}, or singular values if :math:\mathrm{job} = \texttt{'L'} or :math:\texttt{'R'} of the matrix :math:A.

**Returns**
**sep** : float, ndarray, shape :math:\left(:\right)
The reciprocal condition numbers of the vectors.

.. _f08fl-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{job}.

Constraint: :math:\mathrm{job} = \texttt{'E'}, :math:\texttt{'L'} or :math:\texttt{'R'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{m}.

Constraint: :math:\mathrm{m}\geq 0.

(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{d}.

Constraint: the elements of the array must be in increasing or decreasing order.

(errno :math:-4)
On entry, error in parameter :math:\mathrm{d}.

Constraint: the elements of the array must not be negative.

.. _f08fl-py2-py-notes:

**Notes**
The bound on the error, measured by the angle in radians, for the :math:i\ th computed vector is given by :math:\epsilon \left\lVert A\right\rVert_2/\mathrm{sep}_i, where :math:\epsilon is the machine precision and :math:\mathrm{sep}_i is the reciprocal condition number for the vectors, returned in the array element :math:\mathrm{sep}[i-1]. :math:\mathrm{sep}[i-1] is restricted to be at least :math:\epsilon \left\lVert A\right\rVert_2 in order to limit the size of the error bound.

.. _f08fl-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 zheev(jobz, uplo, a):
r"""
zheev computes all the eigenvalues and, optionally, all the eigenvectors of a complex :math:n\times n Hermitian matrix :math:A.

.. _f08fn-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08fnf.html

.. _f08fn-py2-py-parameters:

**Parameters**
**jobz** : str, length 1
Indicates whether eigenvectors are computed.

:math:\mathrm{jobz} = \texttt{'N'}

Only eigenvalues are computed.

:math:\mathrm{jobz} = \texttt{'V'}

Eigenvalues and eigenvectors are computed.

**uplo** : str, length 1
If :math:\mathrm{uplo} = \texttt{'U'}, the upper triangular part of :math:A is stored.

If :math:\mathrm{uplo} = \texttt{'L'}, the lower triangular part of :math:A is stored.

**a** : complex, array-like, shape :math:\left(n, n\right)
The :math:n\times n Hermitian matrix :math:A.

**Returns**
**a** : None or complex, ndarray, shape :math:\left(n, n\right)
If :math:\mathrm{jobz} = \texttt{'V'}, :math:\mathrm{a} contains the orthonormal eigenvectors of the matrix :math:A.

**w** : float, ndarray, shape :math:\left(n\right)
The eigenvalues in ascending order.

.. _f08fn-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{jobz}.

Constraint: :math:\mathrm{jobz} = \texttt{'N'} or :math:\texttt{'V'}.

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

**Warns**
**NagAlgorithmicWarning**
(errno :math:i > 0)
The algorithm failed to converge; :math:\langle\mathit{\boldsymbol{value}}\rangle off-diagonal elements of an intermediate tridiagonal form did not converge to zero.

.. _f08fn-py2-py-notes:

**Notes**
The Hermitian matrix :math:A is first reduced to real tridiagonal form, using unitary similarity transformations, and then the :math:QR algorithm is applied to the tridiagonal matrix to compute the eigenvalues and (optionally) the eigenvectors.

.. _f08fn-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 zheevx(jobz, erange, uplo, a, vl, vu, il, iu, abstol):
r"""
zheevx computes selected eigenvalues and, optionally, eigenvectors of a complex :math:n\times n Hermitian matrix :math:A.
Eigenvalues and eigenvectors can be selected by specifying either a range of values or a range of indices for the desired eigenvalues.

.. _f08fp-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08fpf.html

.. _f08fp-py2-py-parameters:

**Parameters**
**jobz** : str, length 1
Indicates whether eigenvectors are computed.

:math:\mathrm{jobz} = \texttt{'N'}

Only eigenvalues are computed.

:math:\mathrm{jobz} = \texttt{'V'}

Eigenvalues and eigenvectors are computed.

**erange** : str, length 1
If :math:\mathrm{erange} = \texttt{'A'}, all eigenvalues will be found.

If :math:\mathrm{erange} = \texttt{'V'}, all eigenvalues in the half-open interval :math:\left(\mathrm{vl}, \mathrm{vu}\right] will be found.

If :math:\mathrm{erange} = \texttt{'I'}, the :math:\mathrm{il}\ th to :math:\mathrm{iu}\ th eigenvalues will be found.

**uplo** : str, length 1
If :math:\mathrm{uplo} = \texttt{'U'}, the upper triangular part of :math:A is stored.

If :math:\mathrm{uplo} = \texttt{'L'}, the lower triangular part of :math:A is stored.

**a** : complex, array-like, shape :math:\left(n, n\right)
The :math:n\times n Hermitian matrix :math:A.

**vl** : float
If :math:\mathrm{erange} = \texttt{'V'}, the lower and upper bounds of the interval to be searched for eigenvalues.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'I'}, :math:\mathrm{vl} and :math:\mathrm{vu} are not referenced.

**vu** : float
If :math:\mathrm{erange} = \texttt{'V'}, the lower and upper bounds of the interval to be searched for eigenvalues.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'I'}, :math:\mathrm{vl} and :math:\mathrm{vu} are not referenced.

**il** : int
If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{il} and :math:\mathrm{iu} specify the indices (in ascending order) of the smallest and largest eigenvalues to be returned, respectively.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}, :math:\mathrm{il} and :math:\mathrm{iu} are not referenced.

**iu** : int
If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{il} and :math:\mathrm{iu} specify the indices (in ascending order) of the smallest and largest eigenvalues to be returned, respectively.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}, :math:\mathrm{il} and :math:\mathrm{iu} are not referenced.

**abstol** : float
The absolute error tolerance for the eigenvalues. An approximate eigenvalue is accepted as converged when it is determined to lie in an interval :math:\left[a, b\right] of width less than or equal to

.. math::
\mathrm{abstol}+\epsilon \mathrm{max}\left(\left\lvert a\right\rvert, \left\lvert b\right\rvert \right)\text{,}

where :math:\epsilon is the machine precision. If :math:\mathrm{abstol} is less than or equal to zero, then :math:\epsilon \left\lVert T\right\rVert_1 will be used in its place, where :math:T is the tridiagonal matrix obtained by reducing :math:A to tridiagonal form. Eigenvalues will be computed most accurately when :math:\mathrm{abstol} is set to twice the underflow threshold :math:2\times \texttt{machine.real_safe}\left(\right), not zero. If this function returns with :math:\mathrm{errno} > 0, indicating that some eigenvectors did not converge, try setting :math:\mathrm{abstol} to :math:2\times \texttt{machine.real_safe}\left(\right). See Demmel and Kahan (1990).

**Returns**
**a** : complex, ndarray, shape :math:\left(n, n\right)
The lower triangle (if :math:\mathrm{uplo} = \texttt{'L'}) or the upper triangle (if :math:\mathrm{uplo} = \texttt{'U'}) of :math:\mathrm{a}, including the diagonal, is overwritten.

**m** : int
The total number of eigenvalues found. :math:0\leq \mathrm{m}\leq n.

If :math:\mathrm{erange} = \texttt{'A'}, :math:\mathrm{m} = n.

If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{m} = \mathrm{iu}-\mathrm{il}+1.

**w** : float, ndarray, shape :math:\left(n\right)
The first :math:\mathrm{m} elements contain the selected eigenvalues in ascending order.

**z** : complex, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobz} = \texttt{'V'}, then

if no exception or warning is raised, the first :math:\mathrm{m} columns of :math:Z contain the orthonormal eigenvectors of the matrix :math:A corresponding to the selected eigenvalues, with the :math:i\ th column of :math:Z holding the eigenvector associated with :math:\mathrm{w}[i-1];

if an eigenvector fails to converge (:math:\mathrm{errno} > 0), then that column of :math:Z contains the latest approximation to the eigenvector, and the index of the eigenvector is returned in :math:\mathrm{jfail}.

If :math:\mathrm{jobz} = \texttt{'N'}, :math:\mathrm{z} is not referenced.

**Note:** you must ensure that at least :math:\mathrm{max}\left(1, \mathrm{m}\right) columns are supplied in the array :math:\mathrm{z}; if :math:\mathrm{erange} = \texttt{'V'}, the exact value of :math:\mathrm{m} is not known in advance and an upper bound of at least :math:\textit{n} must be used.

**jfail** : int, ndarray, shape :math:\left(n\right)
If :math:\mathrm{jobz} = \texttt{'V'}, then

if no exception or warning is raised, the first :math:\mathrm{m} elements of :math:\mathrm{jfail} are zero;

if :math:\mathrm{errno} > 0, :math:\mathrm{jfail} contains the indices of the eigenvectors that failed to converge.

If :math:\mathrm{jobz} = \texttt{'N'}, :math:\mathrm{jfail} is not referenced.

.. _f08fp-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{jobz}.

Constraint: :math:\mathrm{jobz} = \texttt{'N'} or :math:\texttt{'V'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{erange}.

Constraint: :math:\mathrm{erange} = \texttt{'A'}, :math:\texttt{'V'} or :math:\texttt{'I'}.

(errno :math:-3)
On entry, error in parameter :math:\mathrm{uplo}.

Constraint: :math:\mathrm{uplo} = \texttt{'U'} or :math:\texttt{'L'}.

(errno :math:-4)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

(errno :math:-8)
On entry, error in parameter :math:\mathrm{vu}.

Constraint: :math:\mathrm{vl} < \mathrm{vu}.

(errno :math:-9)
On entry, error in parameter :math:\mathrm{il}.

(errno :math:-10)
On entry, error in parameter :math:\mathrm{iu}.

**Warns**
**NagAlgorithmicWarning**
(errno :math:i > 0)
The algorithm failed to converge; :math:\langle\mathit{\boldsymbol{value}}\rangle eigenvectors did not converge. Their indices are stored in array :math:\mathrm{jfail}.

.. _f08fp-py2-py-notes:

**Notes**
The Hermitian matrix :math:A is first reduced to real tridiagonal form, using unitary similarity transformations.
The required eigenvalues and eigenvectors are then computed from the tridiagonal matrix; the method used depends upon whether all, or selected, eigenvalues and eigenvectors are required.

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

Demmel, J W and Kahan, W, 1990, Accurate singular values of bidiagonal matrices, SIAM J. Sci. Statist. Comput. (11), 873--912

Golub, G H and Van Loan, C F, 1996, Matrix Computations, (3rd Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError

[docs]def zheevd(job, uplo, a):
r"""
zheevd computes all the eigenvalues and, optionally, all the eigenvectors of a complex Hermitian matrix. If the eigenvectors are requested, then it uses a divide-and-conquer algorithm to compute eigenvalues and eigenvectors.
However, if only eigenvalues are required, then it uses the Pal--Walker--Kahan variant of the :math:QL or :math:QR algorithm.

.. _f08fq-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08fqf.html

.. _f08fq-py2-py-parameters:

**Parameters**
**job** : str, length 1
Indicates whether eigenvectors are computed.

:math:\mathrm{job} = \texttt{'N'}

Only eigenvalues are computed.

:math:\mathrm{job} = \texttt{'V'}

Eigenvalues and eigenvectors are computed.

**uplo** : str, length 1
Indicates 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.

**a** : complex, array-like, shape :math:\left(n, n\right)
The :math:n\times n Hermitian matrix :math:A.

**Returns**
**a** : complex, ndarray, shape :math:\left(n, n\right)
If :math:\mathrm{job} = \texttt{'V'}, :math:\mathrm{a} is overwritten by the unitary matrix :math:Z which contains the eigenvectors of :math:A.

**w** : float, ndarray, shape :math:\left(n\right)
The eigenvalues of the matrix :math:A in ascending order.

.. _f08fq-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{job}.

Constraint: :math:\mathrm{job} = \texttt{'N'} or :math:\texttt{'V'}.

(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:i > 0)
If :math:\textit{errno} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{job} = \texttt{'N'}, the algorithm failed to converge; :math:\langle\mathit{\boldsymbol{value}}\rangle elements of an intermediate tridiagonal form did not converge to zero; if :math:\textit{errno} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{job} = \texttt{'V'}, then the algorithm failed to compute an eigenvalue while working on the submatrix lying in rows and column :math:\langle\mathit{\boldsymbol{value}}\rangle/\left(n+1\right) through :math:\mathrm{mod}\left(\langle\mathit{\boldsymbol{value}}\rangle, {n+1}\right).

.. _f08fq-py2-py-notes:

**Notes**
zheevd computes all the eigenvalues and, optionally, all the eigenvectors of a complex Hermitian matrix :math:A. In other words, it can compute the spectral factorization of :math:A as

.. math::
A = Z\Lambda Z^\mathrm{H}\text{,}

where :math:\Lambda is a real diagonal matrix whose diagonal elements are the eigenvalues :math:\lambda_i, and :math:Z is the (complex) unitary matrix whose columns are the eigenvectors :math:z_i.
Thus

.. math::
Az_i = \lambda_iz_i\text{, }\quad i = 1,2,\ldots,n\text{.}

.. _f08fq-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 zheevr(jobz, erange, uplo, a, vl, vu, il, iu, abstol):
r"""
zheevr computes selected eigenvalues and, optionally, eigenvectors of a complex :math:n\times n Hermitian matrix :math:A.
Eigenvalues and eigenvectors can be selected by specifying either a range of values or a range of indices for the desired eigenvalues.

.. _f08fr-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08frf.html

.. _f08fr-py2-py-parameters:

**Parameters**
**jobz** : str, length 1
Indicates whether eigenvectors are computed.

:math:\mathrm{jobz} = \texttt{'N'}

Only eigenvalues are computed.

:math:\mathrm{jobz} = \texttt{'V'}

Eigenvalues and eigenvectors are computed.

**erange** : str, length 1
If :math:\mathrm{erange} = \texttt{'A'}, all eigenvalues will be found.

If :math:\mathrm{erange} = \texttt{'V'}, all eigenvalues in the half-open interval :math:\left(\mathrm{vl}, \mathrm{vu}\right] will be found.

If :math:\mathrm{erange} = \texttt{'I'}, the :math:\mathrm{il}\ th to :math:\mathrm{iu}\ th eigenvalues will be found.

For :math:\mathrm{erange} = \texttt{'V'} or :math:\texttt{'I'} and :math:\mathrm{iu}-\mathrm{il} < n-1, :meth:dstebz and :meth:zstein are called.

**uplo** : str, length 1
If :math:\mathrm{uplo} = \texttt{'U'}, the upper triangular part of :math:A is stored.

If :math:\mathrm{uplo} = \texttt{'L'}, the lower triangular part of :math:A is stored.

**a** : complex, array-like, shape :math:\left(n, n\right)
The :math:n\times n Hermitian matrix :math:A.

**vl** : float
If :math:\mathrm{erange} = \texttt{'V'}, the lower and upper bounds of the interval to be searched for eigenvalues.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'I'}, :math:\mathrm{vl} and :math:\mathrm{vu} are not referenced.

**vu** : float
If :math:\mathrm{erange} = \texttt{'V'}, the lower and upper bounds of the interval to be searched for eigenvalues.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'I'}, :math:\mathrm{vl} and :math:\mathrm{vu} are not referenced.

**il** : int
If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{il} and :math:\mathrm{iu} specify the indices (in ascending order) of the smallest and largest eigenvalues to be returned, respectively.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}, :math:\mathrm{il} and :math:\mathrm{iu} are not referenced.

**iu** : int
If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{il} and :math:\mathrm{iu} specify the indices (in ascending order) of the smallest and largest eigenvalues to be returned, respectively.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}, :math:\mathrm{il} and :math:\mathrm{iu} are not referenced.

**abstol** : float
The absolute error tolerance for the eigenvalues. An approximate eigenvalue is accepted as converged when it is determined to lie in an interval :math:\left[a, b\right] of width less than or equal to

.. math::
\mathrm{abstol}+\epsilon \mathrm{max}\left(\left\lvert a\right\rvert, \left\lvert b\right\rvert \right)\text{,}

where :math:\epsilon is the machine precision. If :math:\mathrm{abstol} is less than or equal to zero, then :math:\epsilon \left\lVert T\right\rVert_1 will be used in its place, where :math:T is the real tridiagonal matrix obtained by reducing :math:A to tridiagonal form. See Demmel and Kahan (1990).

If high relative accuracy is important, set :math:\mathrm{abstol} to :math:\texttt{machine.real_safe}\left(\right), although doing so does not currently guarantee that eigenvalues are computed to high relative accuracy.

See Barlow and Demmel (1990) for a discussion of which matrices can define their eigenvalues to high relative accuracy.

**Returns**
**a** : complex, ndarray, shape :math:\left(n, n\right)
The lower triangle (if :math:\mathrm{uplo} = \texttt{'L'}) or the upper triangle (if :math:\mathrm{uplo} = \texttt{'U'}) of :math:\mathrm{a}, including the diagonal, is overwritten.

**m** : int
The total number of eigenvalues found. :math:0\leq \mathrm{m}\leq n.

If :math:\mathrm{erange} = \texttt{'A'}, :math:\mathrm{m} = n.

If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{m} = \mathrm{iu}-\mathrm{il}+1.

**w** : float, ndarray, shape :math:\left(n\right)
The first :math:\mathrm{m} elements contain the selected eigenvalues in ascending order.

**z** : complex, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobz} = \texttt{'V'}, the first :math:\mathrm{m} columns of :math:Z contain the orthonormal eigenvectors of the matrix :math:A corresponding to the selected eigenvalues, with the :math:i\ th column of :math:Z holding the eigenvector associated with :math:\mathrm{w}[i-1].

If :math:\mathrm{jobz} = \texttt{'N'}, :math:\mathrm{z} is not referenced.

**Note:** you must ensure that at least :math:\mathrm{max}\left(1, \mathrm{m}\right) columns are supplied in the array :math:\mathrm{z}; if :math:\mathrm{erange} = \texttt{'V'}, the exact value of :math:\mathrm{m} is not known in advance and an upper bound of at least :math:\textit{n} must be used.

**isuppz** : int, ndarray, shape :math:\left(:\right)
The support of the eigenvectors in :math:\mathrm{z}, i.e., the indices indicating the nonzero elements in :math:\mathrm{z}. The :math:i\ th eigenvector is nonzero only in elements :math:\mathrm{isuppz}[2\times i-2] through :math:\mathrm{isuppz}[2\times i-1]. Implemented only for :math:\mathrm{erange} = \texttt{'A'} or :math:\mathrm{erange} = \texttt{'I'} and :math:\mathrm{iu}-\mathrm{il} = n-1.

.. _f08fr-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{jobz}.

Constraint: :math:\mathrm{jobz} = \texttt{'N'} or :math:\texttt{'V'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{erange}.

Constraint: :math:\mathrm{erange} = \texttt{'A'}, :math:\texttt{'V'} or :math:\texttt{'I'}.

(errno :math:-3)
On entry, error in parameter :math:\mathrm{uplo}.

Constraint: :math:\mathrm{uplo} = \texttt{'U'} or :math:\texttt{'L'}.

(errno :math:-4)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

(errno :math:-8)
On entry, error in parameter :math:\mathrm{vu}.

Constraint: :math:\mathrm{vl} < \mathrm{vu}.

(errno :math:-9)
On entry, error in parameter :math:\mathrm{il}.

(errno :math:-10)
On entry, error in parameter :math:\mathrm{iu}.

(errno :math:i > 0)
zheevr failed to converge.

.. _f08fr-py2-py-notes:

**Notes**
The Hermitian matrix is first reduced to a real tridiagonal matrix :math:T, using unitary similarity transformations.
Then whenever possible, zheevr computes the eigenspectrum using Relatively Robust Representations. zheevr computes eigenvalues by the dqds algorithm, while orthogonal eigenvectors are computed from various 'good' :math:LDL^\mathrm{T} representations (also known as Relatively Robust Representations).
Gram--Schmidt orthogonalization is avoided as far as possible.
More specifically, the various steps of the algorithm are as follows.
For the :math:i\ th unreduced block of :math:T:

(a) compute :math:T-\sigma_iI = L_iD_iL_i^\mathrm{T}, such that :math:L_iD_iL_i^\mathrm{T} is a relatively robust representation,

(#) compute the eigenvalues, :math:\lambda_j, of :math:L_iD_iL_i^\mathrm{T} to high relative accuracy by the dqds algorithm,

(#) if there is a cluster of close eigenvalues, 'choose' :math:\sigma_i close to the cluster, and go to \(a),

(#) given the approximate eigenvalue :math:\lambda_j of :math:L_iD_iL_i^\mathrm{T}, compute the corresponding eigenvector by forming a rank-revealing twisted factorization.

The desired accuracy of the output can be specified by the argument :math:\mathrm{abstol}.
For more details, see Dhillon (1997) and Parlett and Dhillon (2000).

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

Barlow, J and Demmel, J W, 1990, Computing accurate eigensystems of scaled diagonally dominant matrices, SIAM J. Numer. Anal. (27), 762--791

Demmel, J W and Kahan, W, 1990, Accurate singular values of bidiagonal matrices, SIAM J. Sci. Statist. Comput. (11), 873--912

Dhillon, I, 1997, A new :math:\mathrm{O}\left(n^2\right) algorithm for the symmetric tridiagonal eigenvalue/eigenvector problem, Computer Science Division Technical Report No. UCB//CSD-97-971, UC Berkeley

Golub, G H and Van Loan, C F, 1996, Matrix Computations, (3rd Edition), Johns Hopkins University Press, Baltimore

Parlett, B N and Dhillon, I S, 2000, Relatively robust representations of symmetric tridiagonals, Linear Algebra Appl. (309), 121--151
"""
raise NotImplementedError

[docs]def zhetrd(uplo, a):
r"""
zhetrd reduces a complex Hermitian matrix to tridiagonal form.

.. _f08fs-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08fsf.html

.. _f08fs-py2-py-parameters:

**Parameters**
**uplo** : str, length 1
Indicates 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.

**a** : complex, array-like, shape :math:\left(n, n\right)
The :math:n\times n Hermitian matrix :math:A.

**Returns**
**a** : complex, ndarray, shape :math:\left(n, n\right)
:math:\mathrm{a} is overwritten by the tridiagonal matrix :math:T and details of the unitary matrix :math:Q as specified by :math:\mathrm{uplo}.

**d** : float, ndarray, shape :math:\left(n\right)
The diagonal elements of the tridiagonal matrix :math:T.

**e** : float, ndarray, shape :math:\left(\max\left(1,{n-1}\right)\right)
The off-diagonal elements of the tridiagonal matrix :math:T.

**tau** : complex, ndarray, shape :math:\left(\max\left(1,{n-1}\right)\right)
Further details of the unitary matrix :math:Q.

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

.. _f08fs-py2-py-notes:

**Notes**
zhetrd reduces a complex Hermitian matrix :math:A to real symmetric tridiagonal form :math:T by a unitary similarity transformation: :math:A = QTQ^\mathrm{H}.

The matrix :math:Q is not formed explicitly but is represented as a product of :math:n-1 elementary reflectors (see the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html>__ for details). Functions are provided to work with :math:Q in this representation (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08fsf.html#fcomments>__).

.. _f08fs-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 zungtr(uplo, a, tau):
r"""
zungtr generates the complex unitary matrix :math:Q, which was determined by :meth:zhetrd when reducing a Hermitian matrix to tridiagonal form.

.. _f08ft-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08ftf.html

.. _f08ft-py2-py-parameters:

**Parameters**
**uplo** : str, length 1
This **must** be the same argument :math:\mathrm{uplo} as supplied to :meth:zhetrd.

**a** : complex, array-like, shape :math:\left(n, n\right)
Details of the vectors which define the elementary reflectors, as returned by :meth:zhetrd.

**tau** : complex, array-like, shape :math:\left(\max\left(1,{n-1}\right)\right)
Further details of the elementary reflectors, as returned by :meth:zhetrd.

**Returns**
**a** : complex, ndarray, shape :math:\left(n, n\right)
The :math:n\times n unitary matrix :math:Q.

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

.. _f08ft-py2-py-notes:

**Notes**
zungtr is intended to be used after a call to :meth:zhetrd, which reduces a complex Hermitian matrix :math:A to real symmetric tridiagonal form :math:T by a unitary similarity transformation: :math:A = QTQ^\mathrm{H}. :meth:zhetrd represents the unitary matrix :math:Q as a product of :math:n-1 elementary reflectors.

This function may be used to generate :math:Q explicitly as a square matrix.

.. _f08ft-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 zunmtr(side, uplo, trans, a, tau, c):
r"""
zunmtr multiplies an arbitrary complex matrix :math:C by the complex unitary matrix :math:Q which was determined by :meth:zhetrd when reducing a complex Hermitian matrix to tridiagonal form.

.. _f08fu-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08fuf.html

.. _f08fu-py2-py-parameters:

**Parameters**
**side** : str, length 1
Indicates how :math:Q or :math:Q^\mathrm{H} is to be applied to :math:C.

:math:\mathrm{side} = \texttt{'L'}

:math:Q or :math:Q^\mathrm{H} is applied to :math:C from the left.

:math:\mathrm{side} = \texttt{'R'}

:math:Q or :math:Q^\mathrm{H} is applied to :math:C from the right.

**uplo** : str, length 1
This **must** be the same argument :math:\mathrm{uplo} as supplied to :meth:zhetrd.

**trans** : str, length 1
Indicates whether :math:Q or :math:Q^\mathrm{H} is to be applied to :math:C.

:math:\mathrm{trans} = \texttt{'N'}

:math:Q is applied to :math:C.

:math:\mathrm{trans} = \texttt{'C'}

:math:Q^\mathrm{H} is applied to :math:C.

**a** : complex, array-like, shape :math:\left(:, :\right)
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\mathrm{side}=\texttt{'L'}: :math:m; if :math:\mathrm{side}=\texttt{'R'}: :math:n; otherwise: :math:0.

Note: the required extent for this argument in dimension 2 is determined as follows: if :math:\mathrm{side}=\texttt{'L'}: :math:m; if :math:\mathrm{side}=\texttt{'R'}: :math:n; otherwise: :math:0.

Details of the vectors which define the elementary reflectors, as returned by :meth:zhetrd.

**tau** : complex, array-like, shape :math:\left(:\right)
Note: the required length for this argument is determined as follows: if :math:\mathrm{side}=\texttt{'L'}: :math:{m-1}; if :math:\mathrm{side}=\texttt{'R'}: :math:{n-1}; otherwise: :math:0.

Further details of the elementary reflectors, as returned by :meth:zhetrd.

**c** : complex, array-like, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:C.

**Returns**
**c** : complex, ndarray, shape :math:\left(m, n\right)
:math:\mathrm{c} is overwritten by :math:QC or :math:Q^\mathrm{H}C or :math:CQ or :math:CQ^\mathrm{H} as specified by :math:\mathrm{side} and :math:\mathrm{trans}.

.. _f08fu-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{side}.

Constraint: :math:\mathrm{side} = \texttt{'L'} or :math:\texttt{'R'}.

(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{trans}.

Constraint: :math:\mathrm{trans} = \texttt{'N'} or :math:\texttt{'C'}.

(errno :math:-4)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

(errno :math:-5)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

.. _f08fu-py2-py-notes:

**Notes**
zunmtr is intended to be used after a call to :meth:zhetrd, which reduces a complex Hermitian matrix :math:A to real symmetric tridiagonal form :math:T by a unitary similarity transformation: :math:A = QTQ^\mathrm{H}. :meth:zhetrd represents the unitary matrix :math:Q as a product of elementary reflectors.

This function may be used to form one of the matrix products

.. math::
QC,Q^\mathrm{H}C,CQ\text{ or }CQ^\mathrm{H}\text{,}

overwriting the result on :math:C (which may be any complex rectangular matrix).

A common application of this function is to transform a matrix :math:Z of eigenvectors of :math:T to the matrix :math:\textit{QZ} of eigenvectors of :math:A.

.. _f08fu-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 dspev(jobz, uplo, n, ap):
r"""
dspev computes all the eigenvalues and, optionally, all the eigenvectors of a real :math:n\times n symmetric matrix :math:A in packed storage.

.. _f08ga-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08gaf.html

.. _f08ga-py2-py-parameters:

**Parameters**
**jobz** : str, length 1
Indicates whether eigenvectors are computed.

:math:\mathrm{jobz} = \texttt{'N'}

Only eigenvalues are computed.

:math:\mathrm{jobz} = \texttt{'V'}

Eigenvalues and eigenvectors are computed.

**uplo** : str, length 1
If :math:\mathrm{uplo} = \texttt{'U'}, the upper triangular part of :math:A is stored.

If :math:\mathrm{uplo} = \texttt{'L'}, the lower triangular part 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 upper or lower triangle of 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:\mathrm{ap} is overwritten by the values generated during the reduction to tridiagonal form. The elements of the diagonal and the off-diagonal of the tridiagonal matrix overwrite the corresponding elements of :math:A.

**w** : float, ndarray, shape :math:\left(\mathrm{n}\right)
The eigenvalues in ascending order.

**z** : float, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobz} = \texttt{'V'}, :math:\mathrm{z} contains the orthonormal eigenvectors of the matrix :math:A, with the :math:i\ th column of :math:Z holding the eigenvector associated with :math:\mathrm{w}[i-1].

If :math:\mathrm{jobz} = \texttt{'N'}, :math:\mathrm{z} is not referenced.

.. _f08ga-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{jobz}.

Constraint: :math:\mathrm{jobz} = \texttt{'N'} or :math:\texttt{'V'}.

(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 algorithm failed to converge; :math:\langle\mathit{\boldsymbol{value}}\rangle off-diagonal elements of an intermediate tridiagonal form did not converge to zero.

.. _f08ga-py2-py-notes:

**Notes**
The symmetric matrix :math:A is first reduced to tridiagonal form, using orthogonal similarity transformations, and then the :math:QR algorithm is applied to the tridiagonal matrix to compute the eigenvalues and (optionally) the eigenvectors.

.. _f08ga-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 dspevx(jobz, erange, uplo, n, ap, vl, vu, il, iu, abstol):
r"""
dspevx computes selected eigenvalues and, optionally, eigenvectors of a real :math:n\times n symmetric matrix :math:A in packed storage.
Eigenvalues and eigenvectors can be selected by specifying either a range of values or a range of indices for the desired eigenvalues.

.. _f08gb-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08gbf.html

.. _f08gb-py2-py-parameters:

**Parameters**
**jobz** : str, length 1
Indicates whether eigenvectors are computed.

:math:\mathrm{jobz} = \texttt{'N'}

Only eigenvalues are computed.

:math:\mathrm{jobz} = \texttt{'V'}

Eigenvalues and eigenvectors are computed.

**erange** : str, length 1
If :math:\mathrm{erange} = \texttt{'A'}, all eigenvalues will be found.

If :math:\mathrm{erange} = \texttt{'V'}, all eigenvalues in the half-open interval :math:\left(\mathrm{vl}, \mathrm{vu}\right] will be found.

If :math:\mathrm{erange} = \texttt{'I'}, the :math:\mathrm{il}\ th to :math:\mathrm{iu}\ th eigenvalues will be found.

**uplo** : str, length 1
If :math:\mathrm{uplo} = \texttt{'U'}, the upper triangular part of :math:A is stored.

If :math:\mathrm{uplo} = \texttt{'L'}, the lower triangular part 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 upper or lower triangle of the :math:n\times n symmetric matrix :math:A, packed by columns.

**vl** : float
If :math:\mathrm{erange} = \texttt{'V'}, the lower and upper bounds of the interval to be searched for eigenvalues.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'I'}, :math:\mathrm{vl} and :math:\mathrm{vu} are not referenced.

**vu** : float
If :math:\mathrm{erange} = \texttt{'V'}, the lower and upper bounds of the interval to be searched for eigenvalues.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'I'}, :math:\mathrm{vl} and :math:\mathrm{vu} are not referenced.

**il** : int
If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{il} and :math:\mathrm{iu} specify the indices (in ascending order) of the smallest and largest eigenvalues to be returned, respectively.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}, :math:\mathrm{il} and :math:\mathrm{iu} are not referenced.

**iu** : int
If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{il} and :math:\mathrm{iu} specify the indices (in ascending order) of the smallest and largest eigenvalues to be returned, respectively.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}, :math:\mathrm{il} and :math:\mathrm{iu} are not referenced.

**abstol** : float
The absolute error tolerance for the eigenvalues. An approximate eigenvalue is accepted as converged when it is determined to lie in an interval :math:\left[a, b\right] of width less than or equal to

.. math::
\mathrm{abstol}+\epsilon \mathrm{max}\left(\left\lvert a\right\rvert, \left\lvert b\right\rvert \right)\text{,}

where :math:\epsilon is the machine precision. If :math:\mathrm{abstol} is less than or equal to zero, then :math:\epsilon \left\lVert T\right\rVert_1 will be used in its place, where :math:T is the tridiagonal matrix obtained by reducing :math:A to tridiagonal form. Eigenvalues will be computed most accurately when :math:\mathrm{abstol} is set to twice the underflow threshold :math:2\times \texttt{machine.real_safe}\left(\right), not zero. If this function returns with :math:\mathrm{errno} > 0, indicating that some eigenvectors did not converge, try setting :math:\mathrm{abstol} to :math:2\times \texttt{machine.real_safe}\left(\right). See Demmel and Kahan (1990).

**Returns**
**ap** : float, ndarray, shape :math:\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)
:math:\mathrm{ap} is overwritten by the values generated during the reduction to tridiagonal form. The elements of the diagonal and the off-diagonal of the tridiagonal matrix overwrite the corresponding elements of :math:A.

**m** : int
The total number of eigenvalues found. :math:0\leq \mathrm{m}\leq \mathrm{n}.

If :math:\mathrm{erange} = \texttt{'A'}, :math:\mathrm{m} = \mathrm{n}.

If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{m} = \mathrm{iu}-\mathrm{il}+1.

**w** : float, ndarray, shape :math:\left(\mathrm{n}\right)
The selected eigenvalues in ascending order.

**z** : float, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobz} = \texttt{'V'}, then

if no exception or warning is raised, the first :math:\mathrm{m} columns of :math:Z contain the orthonormal eigenvectors of the matrix :math:A corresponding to the selected eigenvalues, with the :math:i\ th column of :math:Z holding the eigenvector associated with :math:\mathrm{w}[i-1];

if an eigenvector fails to converge (:math:\mathrm{errno} > 0), then that column of :math:Z contains the latest approximation to the eigenvector, and the index of the eigenvector is returned in :math:\mathrm{jfail}.

If :math:\mathrm{jobz} = \texttt{'N'}, :math:\mathrm{z} is not referenced.

**Note:** you must ensure that at least :math:\mathrm{max}\left(1, \mathrm{m}\right) columns are supplied in the array :math:\mathrm{z}; if :math:\mathrm{erange} = \texttt{'V'}, the exact value of :math:\mathrm{m} is not known in advance and an upper bound of at least :math:\mathrm{n} must be used.

**jfail** : int, ndarray, shape :math:\left(\mathrm{n}\right)
If :math:\mathrm{jobz} = \texttt{'V'}, then

if no exception or warning is raised, the first :math:\mathrm{m} elements of :math:\mathrm{jfail} are zero;

if :math:\mathrm{errno} > 0, :math:\mathrm{jfail} contains the indices of the eigenvectors that failed to converge.

If :math:\mathrm{jobz} = \texttt{'N'}, :math:\mathrm{jfail} is not referenced.

.. _f08gb-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{jobz}.

Constraint: :math:\mathrm{jobz} = \texttt{'N'} or :math:\texttt{'V'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{erange}.

Constraint: :math:\mathrm{erange} = \texttt{'A'}, :math:\texttt{'V'} or :math:\texttt{'I'}.

(errno :math:-3)
On entry, error in parameter :math:\mathrm{uplo}.

Constraint: :math:\mathrm{uplo} = \texttt{'U'} or :math:\texttt{'L'}.

(errno :math:-4)
On entry, error in parameter :math:\mathrm{n}.

Constraint: :math:\mathrm{n}\geq 0.

(errno :math:-7)
On entry, error in parameter :math:\mathrm{vu}.

Constraint: :math:\mathrm{vl} < \mathrm{vu}.

(errno :math:-8)
On entry, error in parameter :math:\mathrm{il}.

(errno :math:-9)
On entry, error in parameter :math:\mathrm{iu}.

**Warns**
**NagAlgorithmicWarning**
(errno :math:i > 0)
The algorithm failed to converge; :math:\langle\mathit{\boldsymbol{value}}\rangle eigenvectors did not converge. Their indices are stored in array :math:\mathrm{jfail}.

.. _f08gb-py2-py-notes:

**Notes**
The symmetric matrix :math:A is first reduced to tridiagonal form, using orthogonal similarity transformations.
The required eigenvalues and eigenvectors are then computed from the tridiagonal matrix; the method used depends upon whether all, or selected, eigenvalues and eigenvectors are required.

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

Demmel, J W and Kahan, W, 1990, Accurate singular values of bidiagonal matrices, SIAM J. Sci. Statist. Comput. (11), 873--912

Golub, G H and Van Loan, C F, 1996, Matrix Computations, (3rd Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError

[docs]def dspevd(job, uplo, n, ap):
r"""
dspevd computes all the eigenvalues and, optionally, all the eigenvectors of a real symmetric matrix held in packed storage. If the eigenvectors are requested, then it uses a divide-and-conquer algorithm to compute eigenvalues and eigenvectors.
However, if only eigenvalues are required, then it uses the Pal--Walker--Kahan variant of the :math:QL or :math:QR algorithm.

.. _f08gc-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08gcf.html

.. _f08gc-py2-py-parameters:

**Parameters**
**job** : str, length 1
Indicates whether eigenvectors are computed.

:math:\mathrm{job} = \texttt{'N'}

Only eigenvalues are computed.

:math:\mathrm{job} = \texttt{'V'}

Eigenvalues and eigenvectors are computed.

**uplo** : str, length 1
Indicates 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 order of the matrix :math:A.

**ap** : float, array-like, shape :math:\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)
The upper or lower triangle of 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:\mathrm{ap} is overwritten by the values generated during the reduction to tridiagonal form. The elements of the diagonal and the off-diagonal of the tridiagonal matrix overwrite the corresponding elements of :math:A.

**w** : float, ndarray, shape :math:\left(\mathrm{n}\right)
The eigenvalues of the matrix :math:A in ascending order.

**z** : float, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{job} = \texttt{'V'}, :math:\mathrm{z} is overwritten by the orthogonal matrix :math:Z which contains the eigenvectors of :math:A.

If :math:\mathrm{job} = \texttt{'N'}, :math:\mathrm{z} is not referenced.

.. _f08gc-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{job}.

Constraint: :math:\mathrm{job} = \texttt{'N'} or :math:\texttt{'V'}.

(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)
If :math:\textit{errno} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{job} = \texttt{'N'}, the algorithm failed to converge; :math:\langle\mathit{\boldsymbol{value}}\rangle elements of an intermediate tridiagonal form did not converge to zero; if :math:\textit{errno} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{job} = \texttt{'V'}, then the algorithm failed to compute an eigenvalue while working on the submatrix lying in rows and column :math:\langle\mathit{\boldsymbol{value}}\rangle/\left(\mathrm{n}+1\right) through :math:\mathrm{mod}\left(\langle\mathit{\boldsymbol{value}}\rangle, {\mathrm{n}+1}\right).

.. _f08gc-py2-py-notes:

**Notes**
dspevd computes all the eigenvalues and, optionally, all the eigenvectors of a real symmetric matrix :math:A (held in packed storage). In other words, it can compute the spectral factorization of :math:A as

.. math::
A = Z\Lambda Z^\mathrm{T}\text{,}

where :math:\Lambda is a diagonal matrix whose diagonal elements are the eigenvalues :math:\lambda_i, and :math:Z is the orthogonal matrix whose columns are the eigenvectors :math:z_i.
Thus

.. math::
Az_i = \lambda_iz_i\text{, }\quad i = 1,2,\ldots,n\text{.}

.. _f08gc-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 dsptrd(uplo, n, ap):
r"""
dsptrd reduces a real symmetric matrix to tridiagonal form, using packed storage.

.. _f08ge-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08gef.html

.. _f08ge-py2-py-parameters:

**Parameters**
**uplo** : str, length 1
Indicates 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 order of the matrix :math:A.

**ap** : float, array-like, shape :math:\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)
The upper or lower triangle of 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:\mathrm{ap} is overwritten by the tridiagonal matrix :math:T and details of the orthogonal matrix :math:Q.

**d** : float, ndarray, shape :math:\left(\mathrm{n}\right)
The diagonal elements of the tridiagonal matrix :math:T.

**e** : float, ndarray, shape :math:\left(\max\left(1,{\mathrm{n}-1}\right)\right)
The off-diagonal elements of the tridiagonal matrix :math:T.

**tau** : float, ndarray, shape :math:\left(\max\left(1,{\mathrm{n}-1}\right)\right)
Further details of the orthogonal matrix :math:Q.

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

.. _f08ge-py2-py-notes:

**Notes**
dsptrd reduces a real symmetric matrix :math:A, held in packed storage, to symmetric tridiagonal form :math:T by an orthogonal similarity transformation: :math:A = QTQ^\mathrm{T}.

The matrix :math:Q is not formed explicitly but is represented as a product of :math:n-1 elementary reflectors (see the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html>__ for details). Functions are provided to work with :math:Q in this representation (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08gef.html#fcomments>__).

.. _f08ge-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 dopgtr(uplo, n, ap, tau):
r"""
dopgtr generates the real orthogonal matrix :math:Q, which was determined by :meth:dsptrd when reducing a symmetric matrix to tridiagonal form.

.. _f08gf-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08gff.html

.. _f08gf-py2-py-parameters:

**Parameters**
**uplo** : str, length 1
This **must** be the same argument :math:\mathrm{uplo} as supplied to :meth:dsptrd.

**n** : int
:math:n, the order of the matrix :math:Q.

**ap** : float, array-like, shape :math:\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)
Details of the vectors which define the elementary reflectors, as returned by :meth:dsptrd.

**tau** : float, array-like, shape :math:\left(\max\left(1,{\mathrm{n}-1}\right)\right)
Further details of the elementary reflectors, as returned by :meth:dsptrd.

**Returns**
**q** : float, ndarray, shape :math:\left(\mathrm{n}, \mathrm{n}\right)
The :math:n\times n orthogonal matrix :math:Q.

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

.. _f08gf-py2-py-notes:

**Notes**
dopgtr is intended to be used after a call to :meth:dsptrd, which reduces a real symmetric matrix :math:A to symmetric tridiagonal form :math:T by an orthogonal similarity transformation: :math:A = QTQ^\mathrm{T}. :meth:dsptrd represents the orthogonal matrix :math:Q as a product of :math:n-1 elementary reflectors.

This function may be used to generate :math:Q explicitly as a square matrix.

.. _f08gf-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 dopmtr(side, uplo, trans, ap, tau, c):
r"""
dopmtr multiplies an arbitrary real matrix :math:C by the real orthogonal matrix :math:Q which was determined by :meth:dsptrd when reducing a real symmetric matrix to tridiagonal form.

.. _f08gg-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08ggf.html

.. _f08gg-py2-py-parameters:

**Parameters**
**side** : str, length 1
Indicates how :math:Q or :math:Q^\mathrm{T} is to be applied to :math:C.

:math:\mathrm{side} = \texttt{'L'}

:math:Q or :math:Q^\mathrm{T} is applied to :math:C from the left.

:math:\mathrm{side} = \texttt{'R'}

:math:Q or :math:Q^\mathrm{T} is applied to :math:C from the right.

**uplo** : str, length 1
This **must** be the same argument :math:\mathrm{uplo} as supplied to :meth:dsptrd.

**trans** : str, length 1
Indicates whether :math:Q or :math:Q^\mathrm{T} is to be applied to :math:C.

:math:\mathrm{trans} = \texttt{'N'}

:math:Q is applied to :math:C.

:math:\mathrm{trans} = \texttt{'T'}

:math:Q^\mathrm{T} is applied to :math:C.

**ap** : float, array-like, shape :math:\left(:\right)
Note: the required length for this argument is determined as follows: if :math:\mathrm{side}=\texttt{'L'}: :math:{ m \times \left(m+1\right) / 2 }; if :math:\mathrm{side}=\texttt{'R'}: :math:{ n \times \left(n+1\right) / 2 }; otherwise: :math:0.

Details of the vectors which define the elementary reflectors, as returned by :meth:dsptrd.

**tau** : float, array-like, shape :math:\left(:\right)
Note: the required length for this argument is determined as follows: if :math:\mathrm{side}=\texttt{'L'}: :math:{m-1}; if :math:\mathrm{side}=\texttt{'R'}: :math:{n-1}; otherwise: :math:0.

Further details of the elementary reflectors, as returned by :meth:dsptrd.

**c** : float, array-like, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:C.

**Returns**
**ap** : float, ndarray, shape :math:\left(:\right)
Is used as internal workspace prior to being restored and hence is unchanged.

**c** : float, ndarray, shape :math:\left(m, n\right)
:math:\mathrm{c} is overwritten by :math:QC or :math:Q^\mathrm{T}C or :math:CQ or :math:CQ^\mathrm{T} as specified by :math:\mathrm{side} and :math:\mathrm{trans}.

.. _f08gg-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{side}.

Constraint: :math:\mathrm{side} = \texttt{'L'} or :math:\texttt{'R'}.

(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{trans}.

Constraint: :math:\mathrm{trans} = \texttt{'N'} or :math:\texttt{'T'}.

(errno :math:-4)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

(errno :math:-5)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

.. _f08gg-py2-py-notes:

**Notes**
dopmtr is intended to be used after a call to :meth:dsptrd, which reduces a real symmetric matrix :math:A to symmetric tridiagonal form :math:T by an orthogonal similarity transformation: :math:A = QTQ^\mathrm{T}. :meth:dsptrd represents the orthogonal matrix :math:Q as a product of elementary reflectors.

This function may be used to form one of the matrix products

.. math::
QC,Q^\mathrm{T}C,CQ\text{ or }CQ^\mathrm{T}\text{,}

overwriting the result on :math:C (which may be any real rectangular matrix).

A common application of this function is to transform a matrix :math:Z of eigenvectors of :math:T to the matrix :math:QZ of eigenvectors of :math:A.

.. _f08gg-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 zhpev(jobz, uplo, n, ap):
r"""
zhpev computes all the eigenvalues and, optionally, all the eigenvectors of a complex :math:n\times n Hermitian matrix :math:A in packed storage.

.. _f08gn-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08gnf.html

.. _f08gn-py2-py-parameters:

**Parameters**
**jobz** : str, length 1
Indicates whether eigenvectors are computed.

:math:\mathrm{jobz} = \texttt{'N'}

Only eigenvalues are computed.

:math:\mathrm{jobz} = \texttt{'V'}

Eigenvalues and eigenvectors are computed.

**uplo** : str, length 1
If :math:\mathrm{uplo} = \texttt{'U'}, the upper triangular part of :math:A is stored.

If :math:\mathrm{uplo} = \texttt{'L'}, the lower triangular part 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 upper or lower triangle of 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:\mathrm{ap} is overwritten by the values generated during the reduction to tridiagonal form. The elements of the diagonal and the off-diagonal of the tridiagonal matrix overwrite the corresponding elements of :math:A.

**w** : float, ndarray, shape :math:\left(\mathrm{n}\right)
The eigenvalues in ascending order.

**z** : complex, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobz} = \texttt{'V'}, :math:\mathrm{z} contains the orthonormal eigenvectors of the matrix :math:A, with the :math:i\ th column of :math:Z holding the eigenvector associated with :math:\mathrm{w}[i-1].

If :math:\mathrm{jobz} = \texttt{'N'}, :math:\mathrm{z} is not referenced.

.. _f08gn-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{jobz}.

Constraint: :math:\mathrm{jobz} = \texttt{'N'} or :math:\texttt{'V'}.

(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 algorithm failed to converge; :math:\langle\mathit{\boldsymbol{value}}\rangle off-diagonal elements of an intermediate tridiagonal form did not converge to zero.

.. _f08gn-py2-py-notes:

**Notes**
The Hermitian matrix :math:A is first reduced to real tridiagonal form, using unitary similarity transformations, and then the :math:QR algorithm is applied to the tridiagonal matrix to compute the eigenvalues and (optionally) the eigenvectors.

.. _f08gn-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 zhpevx(jobz, erange, uplo, n, ap, vl, vu, il, iu, abstol):
r"""
zhpevx computes selected eigenvalues and, optionally, eigenvectors of a complex :math:n\times n Hermitian matrix :math:A in packed storage.
Eigenvalues and eigenvectors can be selected by specifying either a range of values or a range of indices for the desired eigenvalues.

.. _f08gp-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08gpf.html

.. _f08gp-py2-py-parameters:

**Parameters**
**jobz** : str, length 1
Indicates whether eigenvectors are computed.

:math:\mathrm{jobz} = \texttt{'N'}

Only eigenvalues are computed.

:math:\mathrm{jobz} = \texttt{'V'}

Eigenvalues and eigenvectors are computed.

**erange** : str, length 1
If :math:\mathrm{erange} = \texttt{'A'}, all eigenvalues will be found.

If :math:\mathrm{erange} = \texttt{'V'}, all eigenvalues in the half-open interval :math:\left(\mathrm{vl}, \mathrm{vu}\right] will be found.

If :math:\mathrm{erange} = \texttt{'I'}, the :math:\mathrm{il}\ th to :math:\mathrm{iu}\ th eigenvalues will be found.

**uplo** : str, length 1
If :math:\mathrm{uplo} = \texttt{'U'}, the upper triangular part of :math:A is stored.

If :math:\mathrm{uplo} = \texttt{'L'}, the lower triangular part 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 upper or lower triangle of the :math:n\times n Hermitian matrix :math:A, packed by columns.

**vl** : float
If :math:\mathrm{erange} = \texttt{'V'}, the lower and upper bounds of the interval to be searched for eigenvalues.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'I'}, :math:\mathrm{vl} and :math:\mathrm{vu} are not referenced.

**vu** : float
If :math:\mathrm{erange} = \texttt{'V'}, the lower and upper bounds of the interval to be searched for eigenvalues.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'I'}, :math:\mathrm{vl} and :math:\mathrm{vu} are not referenced.

**il** : int
If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{il} and :math:\mathrm{iu} specify the indices (in ascending order) of the smallest and largest eigenvalues to be returned, respectively.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}, :math:\mathrm{il} and :math:\mathrm{iu} are not referenced.

**iu** : int
If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{il} and :math:\mathrm{iu} specify the indices (in ascending order) of the smallest and largest eigenvalues to be returned, respectively.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}, :math:\mathrm{il} and :math:\mathrm{iu} are not referenced.

**abstol** : float
The absolute error tolerance for the eigenvalues. An approximate eigenvalue is accepted as converged when it is determined to lie in an interval :math:\left[a, b\right] of width less than or equal to

.. math::
\mathrm{abstol}+\epsilon \mathrm{max}\left(\left\lvert a\right\rvert, \left\lvert b\right\rvert \right)\text{,}

where :math:\epsilon is the machine precision. If :math:\mathrm{abstol} is less than or equal to zero, then :math:\epsilon \left\lVert T\right\rVert_1 will be used in its place, where :math:T is the tridiagonal matrix obtained by reducing :math:A to tridiagonal form. Eigenvalues will be computed most accurately when :math:\mathrm{abstol} is set to twice the underflow threshold :math:2\times \texttt{machine.real_safe}\left(\right), not zero. If this function returns with :math:\mathrm{errno} > 0, indicating that some eigenvectors did not converge, try setting :math:\mathrm{abstol} to :math:2\times \texttt{machine.real_safe}\left(\right). See Demmel and Kahan (1990).

**Returns**
**ap** : complex, ndarray, shape :math:\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)
:math:\mathrm{ap} is overwritten by the values generated during the reduction to tridiagonal form. The elements of the diagonal and the off-diagonal of the tridiagonal matrix overwrite the corresponding elements of :math:A.

**m** : int
The total number of eigenvalues found. :math:0\leq \mathrm{m}\leq \mathrm{n}.

If :math:\mathrm{erange} = \texttt{'A'}, :math:\mathrm{m} = \mathrm{n}.

If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{m} = \mathrm{iu}-\mathrm{il}+1.

**w** : float, ndarray, shape :math:\left(\mathrm{n}\right)
The selected eigenvalues in ascending order.

**z** : complex, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobz} = \texttt{'V'}, then

if no exception or warning is raised, the first :math:\mathrm{m} columns of :math:Z contain the orthonormal eigenvectors of the matrix :math:A corresponding to the selected eigenvalues, with the :math:i\ th column of :math:Z holding the eigenvector associated with :math:\mathrm{w}[i-1];

if an eigenvector fails to converge (:math:\mathrm{errno} > 0), then that column of :math:Z contains the latest approximation to the eigenvector, and the index of the eigenvector is returned in :math:\mathrm{jfail}.

If :math:\mathrm{jobz} = \texttt{'N'}, :math:\mathrm{z} is not referenced.

**Note:** you must ensure that at least :math:\mathrm{max}\left(1, \mathrm{m}\right) columns are supplied in the array :math:\mathrm{z}; if :math:\mathrm{erange} = \texttt{'V'}, the exact value of :math:\mathrm{m} is not known in advance and an upper bound of at least :math:\mathrm{n} must be used.

**jfail** : int, ndarray, shape :math:\left(\mathrm{n}\right)
If :math:\mathrm{jobz} = \texttt{'V'}, then

if no exception or warning is raised, the first :math:\mathrm{m} elements of :math:\mathrm{jfail} are zero;

if :math:\mathrm{errno} > 0, :math:\mathrm{jfail} contains the indices of the eigenvectors that failed to converge.

If :math:\mathrm{jobz} = \texttt{'N'}, :math:\mathrm{jfail} is not referenced.

.. _f08gp-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{jobz}.

Constraint: :math:\mathrm{jobz} = \texttt{'N'} or :math:\texttt{'V'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{erange}.

Constraint: :math:\mathrm{erange} = \texttt{'A'}, :math:\texttt{'V'} or :math:\texttt{'I'}.

(errno :math:-3)
On entry, error in parameter :math:\mathrm{uplo}.

Constraint: :math:\mathrm{uplo} = \texttt{'U'} or :math:\texttt{'L'}.

(errno :math:-4)
On entry, error in parameter :math:\mathrm{n}.

Constraint: :math:\mathrm{n}\geq 0.

(errno :math:-7)
On entry, error in parameter :math:\mathrm{vu}.

Constraint: :math:\mathrm{vl} < \mathrm{vu}.

(errno :math:-8)
On entry, error in parameter :math:\mathrm{il}.

(errno :math:-9)
On entry, error in parameter :math:\mathrm{iu}.

(errno :math:i > 0)
The algorithm failed to converge; :math:\langle\mathit{\boldsymbol{value}}\rangle eigenvectors did not converge. Their indices are stored in array :math:\mathrm{jfail}.

.. _f08gp-py2-py-notes:

**Notes**
The Hermitian matrix :math:A is first reduced to real tridiagonal form, using unitary similarity transformations.
The required eigenvalues and eigenvectors are then computed from the tridiagonal matrix; the method used depends upon whether all, or selected, eigenvalues and eigenvectors are required.

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

Demmel, J W and Kahan, W, 1990, Accurate singular values of bidiagonal matrices, SIAM J. Sci. Statist. Comput. (11), 873--912

Golub, G H and Van Loan, C F, 1996, Matrix Computations, (3rd Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError

[docs]def zhpevd(job, uplo, n, ap):
r"""
zhpevd computes all the eigenvalues and, optionally, all the eigenvectors of a complex Hermitian matrix held in packed storage. If the eigenvectors are requested, then it uses a divide-and-conquer algorithm to compute eigenvalues and eigenvectors.
However, if only eigenvalues are required, then it uses the Pal--Walker--Kahan variant of the :math:QL or :math:QR algorithm.

.. _f08gq-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08gqf.html

.. _f08gq-py2-py-parameters:

**Parameters**
**job** : str, length 1
Indicates whether eigenvectors are computed.

:math:\mathrm{job} = \texttt{'N'}

Only eigenvalues are computed.

:math:\mathrm{job} = \texttt{'V'}

Eigenvalues and eigenvectors are computed.

**uplo** : str, length 1
Indicates 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 order of the matrix :math:A.

**ap** : complex, array-like, shape :math:\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)
The upper or lower triangle of 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:\mathrm{ap} is overwritten by the values generated during the reduction to tridiagonal form. The elements of the diagonal and the off-diagonal of the tridiagonal matrix overwrite the corresponding elements of :math:A.

**w** : float, ndarray, shape :math:\left(\mathrm{n}\right)
The eigenvalues of the matrix :math:A in ascending order.

**z** : complex, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{job} = \texttt{'V'}, :math:\mathrm{z} is overwritten by the unitary matrix :math:Z which contains the eigenvectors of :math:A.

If :math:\mathrm{job} = \texttt{'N'}, :math:\mathrm{z} is not referenced.

.. _f08gq-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{job}.

Constraint: :math:\mathrm{job} = \texttt{'N'} or :math:\texttt{'V'}.

(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)
If :math:\textit{errno} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{job} = \texttt{'N'}, the algorithm failed to converge; :math:\langle\mathit{\boldsymbol{value}}\rangle elements of an intermediate tridiagonal form did not converge to zero; if :math:\textit{errno} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{job} = \texttt{'V'}, then the algorithm failed to compute an eigenvalue while working on the submatrix lying in rows and column :math:\langle\mathit{\boldsymbol{value}}\rangle/\left(\mathrm{n}+1\right) through :math:\mathrm{mod}\left(\langle\mathit{\boldsymbol{value}}\rangle, {\mathrm{n}+1}\right).

.. _f08gq-py2-py-notes:

**Notes**
zhpevd computes all the eigenvalues and, optionally, all the eigenvectors of a complex Hermitian matrix :math:A (held in packed storage). In other words, it can compute the spectral factorization of :math:A as

.. math::
A = Z\Lambda Z^\mathrm{H}\text{,}

where :math:\Lambda is a real diagonal matrix whose diagonal elements are the eigenvalues :math:\lambda_i, and :math:Z is the (complex) unitary matrix whose columns are the eigenvectors :math:z_i.
Thus

.. math::
Az_i = \lambda_iz_i\text{, }\quad i = 1,2,\ldots,n\text{.}

.. _f08gq-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 zhptrd(uplo, n, ap):
r"""
zhptrd reduces a complex Hermitian matrix to tridiagonal form, using packed storage.

.. _f08gs-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08gsf.html

.. _f08gs-py2-py-parameters:

**Parameters**
**uplo** : str, length 1
Indicates 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 order of the matrix :math:A.

**ap** : complex, array-like, shape :math:\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)
The upper or lower triangle of 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:\mathrm{ap} is overwritten by the tridiagonal matrix :math:T and details of the unitary matrix :math:Q.

**d** : float, ndarray, shape :math:\left(\mathrm{n}\right)
The diagonal elements of the tridiagonal matrix :math:T.

**e** : float, ndarray, shape :math:\left(\max\left(1,{\mathrm{n}-1}\right)\right)
The off-diagonal elements of the tridiagonal matrix :math:T.

**tau** : complex, ndarray, shape :math:\left(\max\left(1,{\mathrm{n}-1}\right)\right)
Further details of the unitary matrix :math:Q.

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

.. _f08gs-py2-py-notes:

**Notes**
zhptrd reduces a complex Hermitian matrix :math:A, held in packed storage, to real symmetric tridiagonal form :math:T by a unitary similarity transformation: :math:A = QTQ^\mathrm{H}.

The matrix :math:Q is not formed explicitly but is represented as a product of :math:n-1 elementary reflectors (see the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html>__ for details). Functions are provided to work with :math:Q in this representation (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08gsf.html#fcomments>__).

.. _f08gs-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 zupgtr(uplo, n, ap, tau):
r"""
zupgtr generates the complex unitary matrix :math:Q, which was determined by :meth:zhptrd when reducing a Hermitian matrix to tridiagonal form.

.. _f08gt-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08gtf.html

.. _f08gt-py2-py-parameters:

**Parameters**
**uplo** : str, length 1
This **must** be the same argument :math:\mathrm{uplo} as supplied to :meth:zhptrd.

**n** : int
:math:n, the order of the matrix :math:Q.

**ap** : complex, array-like, shape :math:\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)
Details of the vectors which define the elementary reflectors, as returned by :meth:zhptrd.

**tau** : complex, array-like, shape :math:\left(\max\left(1,{\mathrm{n}-1}\right)\right)
Further details of the elementary reflectors, as returned by :meth:zhptrd.

**Returns**
**q** : complex, ndarray, shape :math:\left(\mathrm{n}, \mathrm{n}\right)
The :math:n\times n unitary matrix :math:Q.

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

.. _f08gt-py2-py-notes:

**Notes**
zupgtr is intended to be used after a call to :meth:zhptrd, which reduces a complex Hermitian matrix :math:A to real symmetric tridiagonal form :math:T by a unitary similarity transformation: :math:A = QTQ^\mathrm{H}. :meth:zhptrd represents the unitary matrix :math:Q as a product of :math:n-1 elementary reflectors.

This function may be used to generate :math:Q explicitly as a square matrix.

.. _f08gt-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 zupmtr(side, uplo, trans, ap, tau, c):
r"""
zupmtr multiplies an arbitrary complex matrix :math:C by the complex unitary matrix :math:Q which was determined by :meth:zhptrd when reducing a complex Hermitian matrix to tridiagonal form.

.. _f08gu-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08guf.html

.. _f08gu-py2-py-parameters:

**Parameters**
**side** : str, length 1
Indicates how :math:Q or :math:Q^\mathrm{H} is to be applied to :math:C.

:math:\mathrm{side} = \texttt{'L'}

:math:Q or :math:Q^\mathrm{H} is applied to :math:C from the left.

:math:\mathrm{side} = \texttt{'R'}

:math:Q or :math:Q^\mathrm{H} is applied to :math:C from the right.

**uplo** : str, length 1
This **must** be the same argument :math:\mathrm{uplo} as supplied to :meth:zhptrd.

**trans** : str, length 1
Indicates whether :math:Q or :math:Q^\mathrm{H} is to be applied to :math:C.

:math:\mathrm{trans} = \texttt{'N'}

:math:Q is applied to :math:C.

:math:\mathrm{trans} = \texttt{'C'}

:math:Q^\mathrm{H} is applied to :math:C.

**ap** : complex, array-like, shape :math:\left(:\right)
Note: the required length for this argument is determined as follows: if :math:\mathrm{side}=\texttt{'L'}: :math:{ m \times \left(m+1\right) / 2 }; if :math:\mathrm{side}=\texttt{'R'}: :math:{ n \times \left(n+1\right) / 2 }; otherwise: :math:0.

Details of the vectors which define the elementary reflectors, as returned by :meth:zhptrd.

**tau** : complex, array-like, shape :math:\left(:\right)
Note: the required length for this argument is determined as follows: if :math:\mathrm{side}=\texttt{'L'}: :math:\max\left(1,{m-1}\right); if :math:\mathrm{side}=\texttt{'R'}: :math:\max\left(1,{n-1}\right); otherwise: :math:0.

Further details of the elementary reflectors, as returned by :meth:zhptrd.

**c** : complex, array-like, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:C.

**Returns**
**ap** : complex, ndarray, shape :math:\left(:\right)
Is used as internal workspace prior to being restored and hence is unchanged.

**c** : complex, ndarray, shape :math:\left(m, n\right)
:math:\mathrm{c} is overwritten by :math:QC or :math:Q^\mathrm{H}C or :math:CQ or :math:CQ^\mathrm{H} as specified by :math:\mathrm{side} and :math:\mathrm{trans}.

.. _f08gu-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{side}.

Constraint: :math:\mathrm{side} = \texttt{'L'} or :math:\texttt{'R'}.

(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{trans}.

Constraint: :math:\mathrm{trans} = \texttt{'N'} or :math:\texttt{'C'}.

(errno :math:-4)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

(errno :math:-5)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

.. _f08gu-py2-py-notes:

**Notes**
zupmtr is intended to be used after a call to :meth:zhptrd, which reduces a complex Hermitian matrix :math:A to real symmetric tridiagonal form :math:T by a unitary similarity transformation: :math:A = QTQ^\mathrm{H}. :meth:zhptrd represents the unitary matrix :math:Q as a product of elementary reflectors.

This function may be used to form one of the matrix products

.. math::
QC,Q^\mathrm{H}C,CQ\text{ or }CQ^\mathrm{H}\text{,}

overwriting the result on :math:C (which may be any complex rectangular matrix).

A common application of this function is to transform a matrix :math:Z of eigenvectors of :math:T to the matrix :math:QZ of eigenvectors of :math:A.

.. _f08gu-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 dsbev(jobz, uplo, kd, ab):
r"""
dsbev computes all the eigenvalues and, optionally, all the eigenvectors of a real :math:n\times n symmetric band matrix :math:A of bandwidth :math:\left(2k_d+1\right).

.. _f08ha-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08haf.html

.. _f08ha-py2-py-parameters:

**Parameters**
**jobz** : str, length 1
Indicates whether eigenvectors are computed.

:math:\mathrm{jobz} = \texttt{'N'}

Only eigenvalues are computed.

:math:\mathrm{jobz} = \texttt{'V'}

Eigenvalues and eigenvectors are computed.

**uplo** : str, length 1
If :math:\mathrm{uplo} = \texttt{'U'}, the upper triangular part of :math:A is stored.

If :math:\mathrm{uplo} = \texttt{'L'}, the lower triangular part of :math:A is stored.

**kd** : int
If :math:\mathrm{uplo} = \texttt{'U'}, the number of superdiagonals, :math:k_d, of the matrix :math:A.

If :math:\mathrm{uplo} = \texttt{'L'}, the number of subdiagonals, :math:k_d, of the matrix :math:A.

**ab** : float, array-like, shape :math:\left(\mathrm{kd}+1, n\right)
The upper or lower triangle of the :math:n\times n symmetric band matrix :math:A.

**Returns**
**ab** : float, ndarray, shape :math:\left(\mathrm{kd}+1, n\right)
:math:\mathrm{ab} is overwritten by values generated during the reduction to tridiagonal form.

The first superdiagonal or subdiagonal and the diagonal of the tridiagonal matrix :math:T are returned in :math:\mathrm{ab} using the same storage format as described above.

**w** : float, ndarray, shape :math:\left(n\right)
The eigenvalues in ascending order.

**z** : float, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobz} = \texttt{'V'}, :math:\mathrm{z} contains the orthonormal eigenvectors of the matrix :math:A, with the :math:i\ th column of :math:Z holding the eigenvector associated with :math:\mathrm{w}[i-1].

If :math:\mathrm{jobz} = \texttt{'N'}, :math:\mathrm{z} is not referenced.

.. _f08ha-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{jobz}.

Constraint: :math:\mathrm{jobz} = \texttt{'N'} or :math:\texttt{'V'}.

(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{kd}.

Constraint: :math:\mathrm{kd}\geq 0.

(errno :math:i > 0)
The algorithm failed to converge; :math:\langle\mathit{\boldsymbol{value}}\rangle off-diagonal elements of an intermediate tridiagonal form did not converge to zero.

.. _f08ha-py2-py-notes:

**Notes**
The symmetric band matrix :math:A is first reduced to tridiagonal form, using orthogonal similarity transformations, and then the :math:QR algorithm is applied to the tridiagonal matrix to compute the eigenvalues and (optionally) the eigenvectors.

.. _f08ha-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 dsbevx(jobz, erange, uplo, kd, ab, vl, vu, il, iu, abstol):
r"""
dsbevx computes selected eigenvalues and, optionally, eigenvectors of a real :math:n\times n symmetric band matrix :math:A of bandwidth :math:\left(2k_d+1\right).
Eigenvalues and eigenvectors can be selected by specifying either a range of values or a range of indices for the desired eigenvalues.

.. _f08hb-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08hbf.html

.. _f08hb-py2-py-parameters:

**Parameters**
**jobz** : str, length 1
Indicates whether eigenvectors are computed.

:math:\mathrm{jobz} = \texttt{'N'}

Only eigenvalues are computed.

:math:\mathrm{jobz} = \texttt{'V'}

Eigenvalues and eigenvectors are computed.

**erange** : str, length 1
If :math:\mathrm{erange} = \texttt{'A'}, all eigenvalues will be found.

If :math:\mathrm{erange} = \texttt{'V'}, all eigenvalues in the half-open interval :math:\left(\mathrm{vl}, \mathrm{vu}\right] will be found.

If :math:\mathrm{erange} = \texttt{'I'}, the :math:\mathrm{il}\ th to :math:\mathrm{iu}\ th eigenvalues will be found.

**uplo** : str, length 1
If :math:\mathrm{uplo} = \texttt{'U'}, the upper triangular part of :math:A is stored.

If :math:\mathrm{uplo} = \texttt{'L'}, the lower triangular part of :math:A is stored.

**kd** : int
If :math:\mathrm{uplo} = \texttt{'U'}, the number of superdiagonals, :math:k_d, of the matrix :math:A.

If :math:\mathrm{uplo} = \texttt{'L'}, the number of subdiagonals, :math:k_d, of the matrix :math:A.

**ab** : float, array-like, shape :math:\left(\mathrm{kd}+1, n\right)
The upper or lower triangle of the :math:n\times n symmetric band matrix :math:A.

**vl** : float
If :math:\mathrm{erange} = \texttt{'V'}, the lower and upper bounds of the interval to be searched for eigenvalues.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'I'}, :math:\mathrm{vl} and :math:\mathrm{vu} are not referenced.

**vu** : float
If :math:\mathrm{erange} = \texttt{'V'}, the lower and upper bounds of the interval to be searched for eigenvalues.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'I'}, :math:\mathrm{vl} and :math:\mathrm{vu} are not referenced.

**il** : int
If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{il} and :math:\mathrm{iu} specify the indices (in ascending order) of the smallest and largest eigenvalues to be returned, respectively.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}, :math:\mathrm{il} and :math:\mathrm{iu} are not referenced.

**iu** : int
If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{il} and :math:\mathrm{iu} specify the indices (in ascending order) of the smallest and largest eigenvalues to be returned, respectively.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}, :math:\mathrm{il} and :math:\mathrm{iu} are not referenced.

**abstol** : float
The absolute error tolerance for the eigenvalues. An approximate eigenvalue is accepted as converged when it is determined to lie in an interval :math:\left[a, b\right] of width less than or equal to

.. math::
\mathrm{abstol}+\epsilon \mathrm{max}\left(\left\lvert a\right\rvert, \left\lvert b\right\rvert \right)\text{,}

where :math:\epsilon is the machine precision. If :math:\mathrm{abstol} is less than or equal to zero, then :math:\epsilon \left\lVert T\right\rVert_1 will be used in its place, where :math:T is the tridiagonal matrix obtained by reducing :math:A to tridiagonal form. Eigenvalues will be computed most accurately when :math:\mathrm{abstol} is set to twice the underflow threshold :math:2\times \texttt{machine.real_safe}\left(\right), not zero. If this function returns with :math:\mathrm{errno} > 0, indicating that some eigenvectors did not converge, try setting :math:\mathrm{abstol} to :math:2\times \texttt{machine.real_safe}\left(\right). See Demmel and Kahan (1990).

**Returns**
**ab** : float, ndarray, shape :math:\left(\mathrm{kd}+1, n\right)
:math:\mathrm{ab} is overwritten by values generated during the reduction to tridiagonal form.

The first superdiagonal or subdiagonal and the diagonal of the tridiagonal matrix :math:T are returned in :math:\mathrm{ab} using the same storage format as described above.

**q** : float, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobz} = \texttt{'V'}, the :math:n\times n orthogonal matrix used in the reduction to tridiagonal form.

If :math:\mathrm{jobz} = \texttt{'N'}, :math:\mathrm{q} is not referenced.

**m** : int
The total number of eigenvalues found. :math:0\leq \mathrm{m}\leq n.

If :math:\mathrm{erange} = \texttt{'A'}, :math:\mathrm{m} = n.

If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{m} = \mathrm{iu}-\mathrm{il}+1.

**w** : float, ndarray, shape :math:\left(n\right)
The first :math:\mathrm{m} elements contain the selected eigenvalues in ascending order.

**z** : float, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobz} = \texttt{'V'}, then

if no exception or warning is raised, the first :math:\mathrm{m} columns of :math:Z contain the orthonormal eigenvectors of the matrix :math:A corresponding to the selected eigenvalues, with the :math:i\ th column of :math:Z holding the eigenvector associated with :math:\mathrm{w}[i-1];

if an eigenvector fails to converge (:math:\mathrm{errno} > 0), then that column of :math:Z contains the latest approximation to the eigenvector, and the index of the eigenvector is returned in :math:\mathrm{jfail}.

If :math:\mathrm{jobz} = \texttt{'N'}, :math:\mathrm{z} is not referenced.

**Note:** you must ensure that at least :math:\mathrm{max}\left(1, \mathrm{m}\right) columns are supplied in the array :math:\mathrm{z}; if :math:\mathrm{erange} = \texttt{'V'}, the exact value of :math:\mathrm{m} is not known in advance and an upper bound of at least :math:\textit{n} must be used.

**jfail** : int, ndarray, shape :math:\left(n\right)
If :math:\mathrm{jobz} = \texttt{'V'}, then

if no exception or warning is raised, the first :math:\mathrm{m} elements of :math:\mathrm{jfail} are zero;

if :math:\mathrm{errno} > 0, :math:\mathrm{jfail} contains the indices of the eigenvectors that failed to converge.

If :math:\mathrm{jobz} = \texttt{'N'}, :math:\mathrm{jfail} is not referenced.

.. _f08hb-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{jobz}.

Constraint: :math:\mathrm{jobz} = \texttt{'N'} or :math:\texttt{'V'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{erange}.

Constraint: :math:\mathrm{erange} = \texttt{'A'}, :math:\texttt{'V'} or :math:\texttt{'I'}.

(errno :math:-3)
On entry, error in parameter :math:\mathrm{uplo}.

Constraint: :math:\mathrm{uplo} = \texttt{'U'} or :math:\texttt{'L'}.

(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:-11)
On entry, error in parameter :math:\mathrm{vu}.

Constraint: :math:\mathrm{vl} < \mathrm{vu}.

(errno :math:-12)
On entry, error in parameter :math:\mathrm{il}.

(errno :math:-13)
On entry, error in parameter :math:\mathrm{iu}.

**Warns**
**NagAlgorithmicWarning**
(errno :math:i > 0)
The algorithm failed to converge; :math:\langle\mathit{\boldsymbol{value}}\rangle eigenvectors did not converge. Their indices are stored in array :math:\mathrm{jfail}.

.. _f08hb-py2-py-notes:

**Notes**
The symmetric band matrix :math:A is first reduced to tridiagonal form, using orthogonal similarity transformations.
The required eigenvalues and eigenvectors are then computed from the tridiagonal matrix; the method used depends upon whether all, or selected, eigenvalues and eigenvectors are required.

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

Demmel, J W and Kahan, W, 1990, Accurate singular values of bidiagonal matrices, SIAM J. Sci. Statist. Comput. (11), 873--912

Golub, G H and Van Loan, C F, 1996, Matrix Computations, (3rd Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError

[docs]def dsbevd(job, uplo, kd, ab):
r"""
dsbevd computes all the eigenvalues and, optionally, all the eigenvectors of a real symmetric band matrix. If the eigenvectors are requested, then it uses a divide-and-conquer algorithm to compute eigenvalues and eigenvectors.
However, if only eigenvalues are required, then it uses the Pal--Walker--Kahan variant of the :math:QL or :math:QR algorithm.

.. _f08hc-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08hcf.html

.. _f08hc-py2-py-parameters:

**Parameters**
**job** : str, length 1
Indicates whether eigenvectors are computed.

:math:\mathrm{job} = \texttt{'N'}

Only eigenvalues are computed.

:math:\mathrm{job} = \texttt{'V'}

Eigenvalues and eigenvectors are computed.

**uplo** : str, length 1
Indicates 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.

**kd** : int
If :math:\mathrm{uplo} = \texttt{'U'}, the number of superdiagonals, :math:k_d, of the matrix :math:A.

If :math:\mathrm{uplo} = \texttt{'L'}, the number of subdiagonals, :math:k_d, of the matrix :math:A.

**ab** : float, array-like, shape :math:\left(\mathrm{kd}+1, n\right)
The upper or lower triangle of the :math:n\times n symmetric band matrix :math:A.

**Returns**
**ab** : float, ndarray, shape :math:\left(\mathrm{kd}+1, n\right)
:math:\mathrm{ab} is overwritten by values generated during the reduction to tridiagonal form.

The first superdiagonal or subdiagonal and the diagonal of the tridiagonal matrix :math:T are returned in :math:\mathrm{ab} using the same storage format as described above.

**w** : float, ndarray, shape :math:\left(n\right)
The eigenvalues of the matrix :math:A in ascending order.

**z** : float, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{job} = \texttt{'V'}, :math:\mathrm{z} is overwritten by the orthogonal matrix :math:Z which contains the eigenvectors of :math:A. The :math:i\ th column of :math:Z contains the eigenvector which corresponds to the eigenvalue :math:\mathrm{w}[i-1].

If :math:\mathrm{job} = \texttt{'N'}, :math:\mathrm{z} is not referenced.

.. _f08hc-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{job}.

Constraint: :math:\mathrm{job} = \texttt{'N'} or :math:\texttt{'V'}.

(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{kd}.

Constraint: :math:\mathrm{kd}\geq 0.

(errno :math:i > 0)
If :math:\textit{errno} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{job} = \texttt{'N'}, the algorithm failed to converge; :math:\langle\mathit{\boldsymbol{value}}\rangle elements of an intermediate tridiagonal form did not converge to zero; if :math:\textit{errno} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{job} = \texttt{'V'}, then the algorithm failed to compute an eigenvalue while working on the submatrix lying in rows and column :math:\langle\mathit{\boldsymbol{value}}\rangle/\left(n+1\right) through :math:\mathrm{mod}\left(\langle\mathit{\boldsymbol{value}}\rangle, {n+1}\right).

.. _f08hc-py2-py-notes:

**Notes**
dsbevd computes all the eigenvalues and, optionally, all the eigenvectors of a real symmetric band matrix :math:A. In other words, it can compute the spectral factorization of :math:A as

.. math::
A = Z\Lambda Z^\mathrm{T}\text{,}

where :math:\Lambda is a diagonal matrix whose diagonal elements are the eigenvalues :math:\lambda_i, and :math:Z is the orthogonal matrix whose columns are the eigenvectors :math:z_i.
Thus

.. math::
Az_i = \lambda_iz_i\text{, }\quad i = 1,2,\ldots,n\text{.}

.. _f08hc-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 dsbtrd(vect, uplo, kd, ab, q=None):
r"""
dsbtrd reduces a real symmetric band matrix to tridiagonal form.

.. _f08he-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08hef.html

.. _f08he-py2-py-parameters:

**Parameters**
**vect** : str, length 1
Indicates whether :math:Q is to be returned.

:math:\mathrm{vect} = \texttt{'V'}

:math:Q is returned.

:math:\mathrm{vect} = \texttt{'U'}

:math:Q is updated (and the array :math:\mathrm{q} must contain a matrix on entry).

:math:\mathrm{vect} = \texttt{'N'}

:math:Q is not required.

**uplo** : str, length 1
Indicates 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.

**kd** : int
If :math:\mathrm{uplo} = \texttt{'U'}, the number of superdiagonals, :math:k_d, of the matrix :math:A.

If :math:\mathrm{uplo} = \texttt{'L'}, the number of subdiagonals, :math:k_d, of the matrix :math:A.

**ab** : float, array-like, shape :math:\left(\mathrm{kd}+1, n\right)
The upper or lower triangle of the :math:n\times n symmetric band matrix :math:A.

**q** : None or float, array-like, shape :math:\left(:, :\right), optional
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\mathrm{vect}\text{ in } (\texttt{'V'}, \texttt{'U'}): :math:\max\left(1,n\right); if :math:\mathrm{vect}=\texttt{'N'}: :math:1; otherwise: :math:0.

Note: the required extent for this argument in dimension 2 is determined as follows: if :math:\mathrm{vect}\text{ in } (\texttt{'V'}, \texttt{'U'}): :math:n; if :math:\mathrm{vect}=\texttt{'N'}: :math:1; otherwise: :math:0.

If :math:\mathrm{vect} = \texttt{'U'}, :math:\mathrm{q} must contain the matrix formed in a previous stage of the reduction (for example, the reduction of a banded symmetric-definite generalized eigenproblem); otherwise :math:\mathrm{q} need not be set.

**Returns**
**ab** : float, ndarray, shape :math:\left(\mathrm{kd}+1, n\right)
:math:\mathrm{ab} is overwritten by values generated during the reduction to tridiagonal form.

The first superdiagonal or subdiagonal and the diagonal of the tridiagonal matrix :math:T are returned in :math:\mathrm{ab} using the same storage format as described above.

**d** : float, ndarray, shape :math:\left(n\right)
The diagonal elements of the tridiagonal matrix :math:T.

**e** : float, ndarray, shape :math:\left(\max\left(1,{n-1}\right)\right)
The off-diagonal elements of the tridiagonal matrix :math:T.

**q** : None or float, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{vect} = \texttt{'V'} or :math:\texttt{'U'}, the :math:n\times n matrix :math:Q.

If :math:\mathrm{vect} = \texttt{'N'}, :math:\mathrm{q} is not referenced.

.. _f08he-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{vect}.

Constraint: :math:\mathrm{vect} = \texttt{'V'}, :math:\texttt{'U'} 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{kd}.

Constraint: :math:\mathrm{kd}\geq 0.

.. _f08he-py2-py-notes:

**Notes**
dsbtrd reduces a symmetric band matrix :math:A to symmetric tridiagonal form :math:T by an orthogonal similarity transformation:

.. math::
T = Q^\mathrm{T}AQ\text{.}

The orthogonal matrix :math:Q is determined as a product of Givens rotation matrices, and may be formed explicitly by the function if required.

The function uses a vectorizable form of the reduction, due to Kaufman (1984).

.. _f08he-py2-py-references:

**References**
Kaufman, L, 1984, Banded eigenvalue solvers on vector machines, ACM Trans. Math. Software (10), 73--86

Parlett, B N, 1998, The Symmetric Eigenvalue Problem, SIAM, Philadelphia
"""
raise NotImplementedError

[docs]def zhbev(jobz, uplo, n, kd, ab):
r"""
zhbev computes all the eigenvalues and, optionally, all the eigenvectors of a complex :math:n\times n Hermitian band matrix :math:A of bandwidth :math:\left(2k_d+1\right).

.. _f08hn-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08hnf.html

.. _f08hn-py2-py-parameters:

**Parameters**
**jobz** : str, length 1
Indicates whether eigenvectors are computed.

:math:\mathrm{jobz} = \texttt{'N'}

Only eigenvalues are computed.

:math:\mathrm{jobz} = \texttt{'V'}

Eigenvalues and eigenvectors are computed.

**uplo** : str, length 1
If :math:\mathrm{uplo} = \texttt{'U'}, the upper triangular part of :math:A is stored.

If :math:\mathrm{uplo} = \texttt{'L'}, the lower triangular part of :math:A is stored.

**n** : int
:math:n, the order of the matrix :math:A.

**kd** : int
If :math:\mathrm{uplo} = \texttt{'U'}, the number of superdiagonals, :math:k_d, of the matrix :math:A.

If :math:\mathrm{uplo} = \texttt{'L'}, the number of subdiagonals, :math:k_d, of the matrix :math:A.

**ab** : complex, array-like, shape :math:\left(\mathrm{kd}+1, \mathrm{n}\right)
The upper or lower triangle of the :math:n\times n Hermitian band matrix :math:A.

**Returns**
**ab** : complex, ndarray, shape :math:\left(\mathrm{kd}+1, \mathrm{n}\right)
:math:\mathrm{ab} is overwritten by values generated during the reduction to tridiagonal form.

The first superdiagonal or subdiagonal and the diagonal of the tridiagonal matrix :math:T are returned in :math:\mathrm{ab} using the same storage format as described above.

**w** : float, ndarray, shape :math:\left(\mathrm{n}\right)
The eigenvalues in ascending order.

**z** : complex, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobz} = \texttt{'V'}, :math:\mathrm{z} contains the orthonormal eigenvectors of the matrix :math:A, with the :math:i\ th column of :math:Z holding the eigenvector associated with :math:\mathrm{w}[i-1].

If :math:\mathrm{jobz} = \texttt{'N'}, :math:\mathrm{z} is not referenced.

.. _f08hn-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{jobz}.

Constraint: :math:\mathrm{jobz} = \texttt{'N'} or :math:\texttt{'V'}.

(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:i > 0)
The algorithm failed to converge; :math:\langle\mathit{\boldsymbol{value}}\rangle off-diagonal elements of an intermediate tridiagonal form did not converge to zero.

.. _f08hn-py2-py-notes:

**Notes**
The Hermitian band matrix :math:A is first reduced to real tridiagonal form, using unitary similarity transformations, and then the :math:QR algorithm is applied to the tridiagonal matrix to compute the eigenvalues and (optionally) the eigenvectors.

.. _f08hn-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 zhbevx(jobz, erange, uplo, kd, ab, vl, vu, il, iu, abstol):
r"""
zhbevx computes selected eigenvalues and, optionally, eigenvectors of a complex :math:n\times n Hermitian band matrix :math:A of bandwidth :math:\left(2k_d+1\right).
Eigenvalues and eigenvectors can be selected by specifying either a range of values or a range of indices for the desired eigenvalues.

.. _f08hp-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08hpf.html

.. _f08hp-py2-py-parameters:

**Parameters**
**jobz** : str, length 1
Indicates whether eigenvectors are computed.

:math:\mathrm{jobz} = \texttt{'N'}

Only eigenvalues are computed.

:math:\mathrm{jobz} = \texttt{'V'}

Eigenvalues and eigenvectors are computed.

**erange** : str, length 1
If :math:\mathrm{erange} = \texttt{'A'}, all eigenvalues will be found.

If :math:\mathrm{erange} = \texttt{'V'}, all eigenvalues in the half-open interval :math:\left(\mathrm{vl}, \mathrm{vu}\right] will be found.

If :math:\mathrm{erange} = \texttt{'I'}, the :math:\mathrm{il}\ th to :math:\mathrm{iu}\ th eigenvalues will be found.

**uplo** : str, length 1
If :math:\mathrm{uplo} = \texttt{'U'}, the upper triangular part of :math:A is stored.

If :math:\mathrm{uplo} = \texttt{'L'}, the lower triangular part of :math:A is stored.

**kd** : int
If :math:\mathrm{uplo} = \texttt{'U'}, the number of superdiagonals, :math:k_d, of the matrix :math:A.

If :math:\mathrm{uplo} = \texttt{'L'}, the number of subdiagonals, :math:k_d, of the matrix :math:A.

**ab** : complex, array-like, shape :math:\left(\mathrm{kd}+1, n\right)
The upper or lower triangle of the :math:n\times n Hermitian band matrix :math:A.

**vl** : float
If :math:\mathrm{erange} = \texttt{'V'}, the lower and upper bounds of the interval to be searched for eigenvalues.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'I'}, :math:\mathrm{vl} and :math:\mathrm{vu} are not referenced.

**vu** : float
If :math:\mathrm{erange} = \texttt{'V'}, the lower and upper bounds of the interval to be searched for eigenvalues.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'I'}, :math:\mathrm{vl} and :math:\mathrm{vu} are not referenced.

**il** : int
If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{il} and :math:\mathrm{iu} specify the indices (in ascending order) of the smallest and largest eigenvalues to be returned, respectively.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}, :math:\mathrm{il} and :math:\mathrm{iu} are not referenced.

**iu** : int
If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{il} and :math:\mathrm{iu} specify the indices (in ascending order) of the smallest and largest eigenvalues to be returned, respectively.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}, :math:\mathrm{il} and :math:\mathrm{iu} are not referenced.

**abstol** : float
The absolute error tolerance for the eigenvalues. An approximate eigenvalue is accepted as converged when it is determined to lie in an interval :math:\left[a, b\right] of width less than or equal to

.. math::
\mathrm{abstol}+\epsilon \mathrm{max}\left(\left\lvert a\right\rvert, \left\lvert b\right\rvert \right)\text{,}

where :math:\epsilon is the machine precision. If :math:\mathrm{abstol} is less than or equal to zero, then :math:\epsilon \left\lVert T\right\rVert_1 will be used in its place, where :math:T is the tridiagonal matrix obtained by reducing :math:A to tridiagonal form. Eigenvalues will be computed most accurately when :math:\mathrm{abstol} is set to twice the underflow threshold :math:2\times \texttt{machine.real_safe}\left(\right), not zero. If this function returns with :math:\mathrm{errno} > 0, indicating that some eigenvectors did not converge, try setting :math:\mathrm{abstol} to :math:2\times \texttt{machine.real_safe}\left(\right). See Demmel and Kahan (1990).

**Returns**
**ab** : complex, ndarray, shape :math:\left(\mathrm{kd}+1, n\right)
:math:\mathrm{ab} is overwritten by values generated during the reduction to tridiagonal form.

The first superdiagonal or subdiagonal and the diagonal of the tridiagonal matrix :math:T are returned in :math:\mathrm{ab} using the same storage format as described above.

**q** : complex, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobz} = \texttt{'V'}, the :math:n\times n unitary matrix used in the reduction to tridiagonal form.

If :math:\mathrm{jobz} = \texttt{'N'}, :math:\mathrm{q} is not referenced.

**m** : int
The total number of eigenvalues found. :math:0\leq \mathrm{m}\leq n.

If :math:\mathrm{erange} = \texttt{'A'}, :math:\mathrm{m} = n.

If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{m} = \mathrm{iu}-\mathrm{il}+1.

**w** : float, ndarray, shape :math:\left(n\right)
The first :math:\mathrm{m} elements contain the selected eigenvalues in ascending order.

**z** : complex, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobz} = \texttt{'V'}, then

if no exception or warning is raised, the first :math:\mathrm{m} columns of :math:Z contain the orthonormal eigenvectors of the matrix :math:A corresponding to the selected eigenvalues, with the :math:i\ th column of :math:Z holding the eigenvector associated with :math:\mathrm{w}[i-1];

if an eigenvector fails to converge (:math:\mathrm{errno} > 0), then that column of :math:Z contains the latest approximation to the eigenvector, and the index of the eigenvector is returned in :math:\mathrm{jfail}.

If :math:\mathrm{jobz} = \texttt{'N'}, :math:\mathrm{z} is not referenced.

**Note:** you must ensure that at least :math:\mathrm{max}\left(1, \mathrm{m}\right) columns are supplied in the array :math:\mathrm{z}; if :math:\mathrm{erange} = \texttt{'V'}, the exact value of :math:\mathrm{m} is not known in advance and an upper bound of at least :math:\textit{n} must be used.

**jfail** : int, ndarray, shape :math:\left(n\right)
If :math:\mathrm{jobz} = \texttt{'V'}, then

if no exception or warning is raised, the first :math:\mathrm{m} elements of :math:\mathrm{jfail} are zero;

if :math:\mathrm{errno} > 0, :math:\mathrm{jfail} contains the indices of the eigenvectors that failed to converge.

If :math:\mathrm{jobz} = \texttt{'N'}, :math:\mathrm{jfail} is not referenced.

.. _f08hp-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{jobz}.

Constraint: :math:\mathrm{jobz} = \texttt{'N'} or :math:\texttt{'V'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{erange}.

Constraint: :math:\mathrm{erange} = \texttt{'A'}, :math:\texttt{'V'} or :math:\texttt{'I'}.

(errno :math:-3)
On entry, error in parameter :math:\mathrm{uplo}.

Constraint: :math:\mathrm{uplo} = \texttt{'U'} or :math:\texttt{'L'}.

(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:-11)
On entry, error in parameter :math:\mathrm{vu}.

Constraint: :math:\mathrm{vl} < \mathrm{vu}.

(errno :math:-12)
On entry, error in parameter :math:\mathrm{il}.

(errno :math:-13)
On entry, error in parameter :math:\mathrm{iu}.

**Warns**
**NagAlgorithmicWarning**
(errno :math:i > 0)
The algorithm failed to converge; :math:\langle\mathit{\boldsymbol{value}}\rangle eigenvectors did not converge. Their indices are stored in array :math:\mathrm{jfail}.

.. _f08hp-py2-py-notes:

**Notes**
The Hermitian band matrix :math:A is first reduced to real tridiagonal form, using unitary similarity transformations.
The required eigenvalues and eigenvectors are then computed from the tridiagonal matrix; the method used depends upon whether all, or selected, eigenvalues and eigenvectors are required.

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

Demmel, J W and Kahan, W, 1990, Accurate singular values of bidiagonal matrices, SIAM J. Sci. Statist. Comput. (11), 873--912

Golub, G H and Van Loan, C F, 1996, Matrix Computations, (3rd Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError

[docs]def zhbevd(job, uplo, kd, ab):
r"""
zhbevd computes all the eigenvalues and, optionally, all the eigenvectors of a complex Hermitian band matrix. If the eigenvectors are requested, then it uses a divide-and-conquer algorithm to compute eigenvalues and eigenvectors.
However, if only eigenvalues are required, then it uses the Pal--Walker--Kahan variant of the :math:QL or :math:QR algorithm.

.. _f08hq-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08hqf.html

.. _f08hq-py2-py-parameters:

**Parameters**
**job** : str, length 1
Indicates whether eigenvectors are computed.

:math:\mathrm{job} = \texttt{'N'}

Only eigenvalues are computed.

:math:\mathrm{job} = \texttt{'V'}

Eigenvalues and eigenvectors are computed.

**uplo** : str, length 1
Indicates 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.

**kd** : int
If :math:\mathrm{uplo} = \texttt{'U'}, the number of superdiagonals, :math:k_d, of the matrix :math:A.

If :math:\mathrm{uplo} = \texttt{'L'}, the number of subdiagonals, :math:k_d, of the matrix :math:A.

**ab** : complex, array-like, shape :math:\left(\mathrm{kd}+1, n\right)
The upper or lower triangle of the :math:n\times n Hermitian band matrix :math:A.

**Returns**
**ab** : complex, ndarray, shape :math:\left(\mathrm{kd}+1, n\right)
:math:\mathrm{ab} is overwritten by values generated during the reduction to tridiagonal form.

The first superdiagonal or subdiagonal and the diagonal of the tridiagonal matrix :math:T are returned in :math:\mathrm{ab} using the same storage format as described above.

**w** : float, ndarray, shape :math:\left(n\right)
The eigenvalues of the matrix :math:A in ascending order.

**z** : complex, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{job} = \texttt{'V'}, :math:\mathrm{z} is overwritten by the unitary matrix :math:Z which contains the eigenvectors of :math:A. The :math:i\ th column of :math:Z contains the eigenvector which corresponds to the eigenvalue :math:\mathrm{w}[i-1].

If :math:\mathrm{job} = \texttt{'N'}, :math:\mathrm{z} is not referenced.

.. _f08hq-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{job}.

Constraint: :math:\mathrm{job} = \texttt{'N'} or :math:\texttt{'V'}.

(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{kd}.

Constraint: :math:\mathrm{kd}\geq 0.

(errno :math:i > 0)
If :math:\textit{errno} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{job} = \texttt{'N'}, the algorithm failed to converge; :math:\langle\mathit{\boldsymbol{value}}\rangle elements of an intermediate tridiagonal form did not converge to zero; if :math:\textit{errno} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{job} = \texttt{'V'}, then the algorithm failed to compute an eigenvalue while working on the submatrix lying in rows and column :math:\langle\mathit{\boldsymbol{value}}\rangle/\left(n+1\right) through :math:\mathrm{mod}\left(\langle\mathit{\boldsymbol{value}}\rangle, {n+1}\right).

.. _f08hq-py2-py-notes:

**Notes**
zhbevd computes all the eigenvalues and, optionally, all the eigenvectors of a complex Hermitian band matrix :math:A. In other words, it can compute the spectral factorization of :math:A as

.. math::
A = Z\Lambda Z^\mathrm{H}\text{,}

where :math:\Lambda is a real diagonal matrix whose diagonal elements are the eigenvalues :math:\lambda_i, and :math:Z is the (complex) unitary matrix whose columns are the eigenvectors :math:z_i.
Thus

.. math::
Az_i = \lambda_iz_i\text{, }\quad i = 1,2,\ldots,n\text{.}

.. _f08hq-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 zhbtrd(vect, uplo, kd, ab, q=None):
r"""
zhbtrd reduces a complex Hermitian band matrix to tridiagonal form.

.. _f08hs-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08hsf.html

.. _f08hs-py2-py-parameters:

**Parameters**
**vect** : str, length 1
Indicates whether :math:Q is to be returned.

:math:\mathrm{vect} = \texttt{'V'}

:math:Q is returned.

:math:\mathrm{vect} = \texttt{'U'}

:math:Q is updated (and the array :math:\mathrm{q} must contain a matrix on entry).

:math:\mathrm{vect} = \texttt{'N'}

:math:Q is not required.

**uplo** : str, length 1
Indicates 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.

**kd** : int
If :math:\mathrm{uplo} = \texttt{'U'}, the number of superdiagonals, :math:k_d, of the matrix :math:A.

If :math:\mathrm{uplo} = \texttt{'L'}, the number of subdiagonals, :math:k_d, of the matrix :math:A.

**ab** : complex, array-like, shape :math:\left(\mathrm{kd}+1, n\right)
The upper or lower triangle of the :math:n\times n Hermitian band matrix :math:A.

**q** : None or complex, array-like, shape :math:\left(:, :\right), optional
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\mathrm{vect}\text{ in } (\texttt{'V'}, \texttt{'U'}): :math:\max\left(1,n\right); if :math:\mathrm{vect}=\texttt{'N'}: :math:1; otherwise: :math:0.

Note: the required extent for this argument in dimension 2 is determined as follows: if :math:\mathrm{vect}\text{ in } (\texttt{'V'}, \texttt{'U'}): :math:n; if :math:\mathrm{vect}=\texttt{'N'}: :math:1; otherwise: :math:0.

If :math:\mathrm{vect} = \texttt{'U'}, :math:\mathrm{q} must contain the matrix formed in a previous stage of the reduction (for example, the reduction of a banded Hermitian-definite generalized eigenproblem); otherwise :math:\mathrm{q} need not be set.

**Returns**
**ab** : complex, ndarray, shape :math:\left(\mathrm{kd}+1, n\right)
:math:\mathrm{ab} is overwritten by values generated during the reduction to tridiagonal form.

The first superdiagonal or subdiagonal and the diagonal of the tridiagonal matrix :math:T are returned in :math:\mathrm{ab} using the same storage format as described above.

**d** : float, ndarray, shape :math:\left(n\right)
The diagonal elements of the tridiagonal matrix :math:T.

**e** : float, ndarray, shape :math:\left(\max\left(1,{n-1}\right)\right)
The off-diagonal elements of the tridiagonal matrix :math:T.

**q** : None or complex, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{vect} = \texttt{'V'} or :math:\texttt{'U'}, the :math:n\times n matrix :math:Q.

If :math:\mathrm{vect} = \texttt{'N'}, :math:\mathrm{q} is not referenced.

.. _f08hs-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{vect}.

Constraint: :math:\mathrm{vect} = \texttt{'V'}, :math:\texttt{'U'} 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{kd}.

Constraint: :math:\mathrm{kd}\geq 0.

.. _f08hs-py2-py-notes:

**Notes**
zhbtrd reduces a Hermitian band matrix :math:A to real symmetric tridiagonal form :math:T by a unitary similarity transformation:

.. math::
T = Q^\mathrm{H}AQ\text{.}

The unitary matrix :math:Q is determined as a product of Givens rotation matrices, and may be formed explicitly by the function if required.

The function uses a vectorizable form of the reduction, due to Kaufman (1984).

.. _f08hs-py2-py-references:

**References**
Kaufman, L, 1984, Banded eigenvalue solvers on vector machines, ACM Trans. Math. Software (10), 73--86

Parlett, B N, 1998, The Symmetric Eigenvalue Problem, SIAM, Philadelphia
"""
raise NotImplementedError

[docs]def dstev(jobz, d, e):
r"""
dstev computes all the eigenvalues and, optionally, all the eigenvectors of a real :math:n\times n symmetric tridiagonal matrix :math:A.

.. _f08ja-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08jaf.html

.. _f08ja-py2-py-parameters:

**Parameters**
**jobz** : str, length 1
Indicates whether eigenvectors are computed.

:math:\mathrm{jobz} = \texttt{'N'}

Only eigenvalues are computed.

:math:\mathrm{jobz} = \texttt{'V'}

Eigenvalues and eigenvectors are computed.

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

**Returns**
**d** : float, ndarray, shape :math:\left(n\right)
If no exception or warning is raised, the eigenvalues in ascending order.

**e** : float, ndarray, shape :math:\left(n-1\right)
The contents of :math:\mathrm{e} are destroyed.

**z** : float, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobz} = \texttt{'V'}, then if no exception or warning is raised, :math:\mathrm{z} contains the orthonormal eigenvectors of the matrix :math:A, with the :math:i\ th column of :math:Z holding the eigenvector associated with :math:\mathrm{d}[i-1].

If :math:\mathrm{jobz} = \texttt{'N'}, :math:\mathrm{z} is not referenced.

.. _f08ja-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{jobz}.

Constraint: :math:\mathrm{jobz} = \texttt{'N'} or :math:\texttt{'V'}.

(errno :math:-2)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

(errno :math:i > 0)
The algorithm failed to converge; :math:\langle\mathit{\boldsymbol{value}}\rangle off-diagonal elements of :math:\mathrm{e} did not converge to zero.

.. _f08ja-py2-py-notes:

**Notes**
dstev computes all the eigenvalues and, optionally, all the eigenvectors of :math:A using a combination of the :math:QR and :math:QL algorithms, with an implicit shift.

.. _f08ja-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 dstevx(jobz, erange, d, e, vl, vu, il, iu, abstol):
r"""
dstevx computes selected eigenvalues and, optionally, eigenvectors of a real symmetric tridiagonal matrix :math:A.
Eigenvalues and eigenvectors can be selected by specifying either a range of values or a range of indices for the desired eigenvalues.

.. _f08jb-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08jbf.html

.. _f08jb-py2-py-parameters:

**Parameters**
**jobz** : str, length 1
Indicates whether eigenvectors are computed.

:math:\mathrm{jobz} = \texttt{'N'}

Only eigenvalues are computed.

:math:\mathrm{jobz} = \texttt{'V'}

Eigenvalues and eigenvectors are computed.

**erange** : str, length 1
If :math:\mathrm{erange} = \texttt{'A'}, all eigenvalues will be found.

If :math:\mathrm{erange} = \texttt{'V'}, all eigenvalues in the half-open interval :math:\left(\mathrm{vl}, \mathrm{vu}\right] will be found.

If :math:\mathrm{erange} = \texttt{'I'}, the :math:\mathrm{il}\ th to :math:\mathrm{iu}\ th eigenvalues will be found.

**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(\max\left(1,{n-1}\right)\right)
The :math:\left(n-1\right) subdiagonal elements of the tridiagonal matrix :math:A.

**vl** : float
If :math:\mathrm{erange} = \texttt{'V'}, the lower and upper bounds of the interval to be searched for eigenvalues.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'I'}, :math:\mathrm{vl} and :math:\mathrm{vu} are not referenced.

**vu** : float
If :math:\mathrm{erange} = \texttt{'V'}, the lower and upper bounds of the interval to be searched for eigenvalues.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'I'}, :math:\mathrm{vl} and :math:\mathrm{vu} are not referenced.

**il** : int
If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{il} and :math:\mathrm{iu} specify the indices (in ascending order) of the smallest and largest eigenvalues to be returned, respectively.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}, :math:\mathrm{il} and :math:\mathrm{iu} are not referenced.

**iu** : int
If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{il} and :math:\mathrm{iu} specify the indices (in ascending order) of the smallest and largest eigenvalues to be returned, respectively.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}, :math:\mathrm{il} and :math:\mathrm{iu} are not referenced.

**abstol** : float
The absolute error tolerance for the eigenvalues. An approximate eigenvalue is accepted as converged when it is determined to lie in an interval :math:\left[a, b\right] of width less than or equal to

.. math::
\mathrm{abstol}+\epsilon \mathrm{max}\left(\left\lvert a\right\rvert, \left\lvert b\right\rvert \right)\text{,}

where :math:\epsilon is the machine precision. If :math:\mathrm{abstol} is less than or equal to zero, then :math:\epsilon \left\lVert A\right\rVert_1 will be used in its place. Eigenvalues will be computed most accurately when :math:\mathrm{abstol} is set to twice the underflow threshold :math:2\times \texttt{machine.real_safe}\left(\right), not zero. If this function returns with :math:\mathrm{errno} > 0, indicating that some eigenvectors did not converge, try setting :math:\mathrm{abstol} to :math:2\times \texttt{machine.real_safe}\left(\right). See Demmel and Kahan (1990).

**Returns**
**d** : float, ndarray, shape :math:\left(n\right)
May be multiplied by a constant factor chosen to avoid over/underflow in computing the eigenvalues.

**e** : float, ndarray, shape :math:\left(\max\left(1,{n-1}\right)\right)
May be multiplied by a constant factor chosen to avoid over/underflow in computing the eigenvalues.

**m** : int
The total number of eigenvalues found. :math:0\leq \mathrm{m}\leq n.

If :math:\mathrm{erange} = \texttt{'A'}, :math:\mathrm{m} = n.

If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{m} = \mathrm{iu}-\mathrm{il}+1.

**w** : float, ndarray, shape :math:\left(n\right)
The first :math:\mathrm{m} elements contain the selected eigenvalues in ascending order.

**z** : float, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobz} = \texttt{'V'}, then

if no exception or warning is raised, the first :math:\mathrm{m} columns of :math:Z contain the orthonormal eigenvectors of the matrix :math:A corresponding to the selected eigenvalues, with the :math:i\ th column of :math:Z holding the eigenvector associated with :math:\mathrm{w}[i-1];

if an eigenvector fails to converge (:math:\mathrm{errno} > 0), then that column of :math:Z contains the latest approximation to the eigenvector, and the index of the eigenvector is returned in :math:\mathrm{jfail}.

If :math:\mathrm{jobz} = \texttt{'N'}, :math:\mathrm{z} is not referenced.

**Note:** you must ensure that at least :math:\mathrm{max}\left(1, \mathrm{m}\right) columns are supplied in the array :math:\mathrm{z}; if :math:\mathrm{erange} = \texttt{'V'}, the exact value of :math:\mathrm{m} is not known in advance and an upper bound of at least :math:\textit{n} must be used.

**jfail** : int, ndarray, shape :math:\left(n\right)
If :math:\mathrm{jobz} = \texttt{'V'}, then

if no exception or warning is raised, the first :math:\mathrm{m} elements of :math:\mathrm{jfail} are zero;

if :math:\mathrm{errno} > 0, :math:\mathrm{jfail} contains the indices of the eigenvectors that failed to converge.

If :math:\mathrm{jobz} = \texttt{'N'}, :math:\mathrm{jfail} is not referenced.

.. _f08jb-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{jobz}.

Constraint: :math:\mathrm{jobz} = \texttt{'N'} or :math:\texttt{'V'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{erange}.

Constraint: :math:\mathrm{erange} = \texttt{'A'}, :math:\texttt{'V'} or :math:\texttt{'I'}.

(errno :math:-3)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

(errno :math:-7)
On entry, error in parameter :math:\mathrm{vu}.

Constraint: :math:\mathrm{vl} < \mathrm{vu}.

(errno :math:-8)
On entry, error in parameter :math:\mathrm{il}.

(errno :math:-9)
On entry, error in parameter :math:\mathrm{iu}.

**Warns**
**NagAlgorithmicWarning**
(errno :math:i > 0)
The algorithm failed to converge; :math:\langle\mathit{\boldsymbol{value}}\rangle eigenvectors did not converge. Their indices are stored in array :math:\mathrm{jfail}.

.. _f08jb-py2-py-notes:

**Notes**
dstevx computes the required eigenvalues and eigenvectors of :math:A by reducing the tridiagonal matrix to diagonal form using the :math:QR algorithm.
Bisection is used to determine selected eigenvalues.

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

Demmel, J W and Kahan, W, 1990, Accurate singular values of bidiagonal matrices, SIAM J. Sci. Statist. Comput. (11), 873--912

Golub, G H and Van Loan, C F, 1996, Matrix Computations, (3rd Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError

[docs]def dstevd(job, d, e):
r"""
dstevd computes all the eigenvalues and, optionally, all the eigenvectors of a real symmetric tridiagonal matrix. If the eigenvectors are requested, then it uses a divide-and-conquer algorithm to compute eigenvalues and eigenvectors.
However, if only eigenvalues are required, then it uses the Pal--Walker--Kahan variant of the :math:QL or :math:QR algorithm.

.. _f08jc-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08jcf.html

.. _f08jc-py2-py-parameters:

**Parameters**
**job** : str, length 1
Indicates whether eigenvectors are computed.

:math:\mathrm{job} = \texttt{'N'}

Only eigenvalues are computed.

:math:\mathrm{job} = \texttt{'V'}

Eigenvalues and eigenvectors are computed.

**d** : float, array-like, shape :math:\left(n\right)
The :math:n diagonal elements of the tridiagonal matrix :math:T.

**e** : float, array-like, shape :math:\left(n\right)
The :math:n-1 off-diagonal elements of the tridiagonal matrix :math:T. The :math:n\ th element of this array is used as workspace.

**Returns**
**d** : float, ndarray, shape :math:\left(n\right)
The eigenvalues of the matrix :math:T in ascending order.

**e** : float, ndarray, shape :math:\left(n\right)
:math:\mathrm{e} is overwritten with intermediate results.

**z** : float, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{job} = \texttt{'V'}, :math:\mathrm{z} is overwritten by the orthogonal matrix :math:Z which contains the eigenvectors of :math:T.

If :math:\mathrm{job} = \texttt{'N'}, :math:\mathrm{z} is not referenced.

.. _f08jc-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{job}.

Constraint: :math:\mathrm{job} = \texttt{'N'} or :math:\texttt{'V'}.

(errno :math:-2)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

(errno :math:i > 0)
The algorithm failed to converge; :math:\langle\mathit{\boldsymbol{value}}\rangle off-diagonal elements of :math:\mathrm{e} did not converge to zero.

.. _f08jc-py2-py-notes:

**Notes**
dstevd computes all the eigenvalues and, optionally, all the eigenvectors of a real symmetric tridiagonal matrix :math:T. In other words, it can compute the spectral factorization of :math:T as

.. math::
T = Z\Lambda Z^\mathrm{T}\text{,}

where :math:\Lambda is a diagonal matrix whose diagonal elements are the eigenvalues :math:\lambda_i, and :math:Z is the orthogonal matrix whose columns are the eigenvectors :math:z_i.
Thus

.. math::
Tz_i = \lambda_iz_i\text{, }\quad i = 1,2,\ldots,n\text{.}

.. _f08jc-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 dstevr(jobz, erange, d, e, vl, vu, il, iu, abstol):
r"""
dstevr computes selected eigenvalues and, optionally, eigenvectors of a real :math:n\times n symmetric tridiagonal matrix :math:T.
Eigenvalues and eigenvectors can be selected by specifying either a range of values or a range of indices for the desired eigenvalues.

.. _f08jd-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08jdf.html

.. _f08jd-py2-py-parameters:

**Parameters**
**jobz** : str, length 1
Indicates whether eigenvectors are computed.

:math:\mathrm{jobz} = \texttt{'N'}

Only eigenvalues are computed.

:math:\mathrm{jobz} = \texttt{'V'}

Eigenvalues and eigenvectors are computed.

**erange** : str, length 1
If :math:\mathrm{erange} = \texttt{'A'}, all eigenvalues will be found.

If :math:\mathrm{erange} = \texttt{'V'}, all eigenvalues in the half-open interval :math:\left(\mathrm{vl}, \mathrm{vu}\right] will be found.

If :math:\mathrm{erange} = \texttt{'I'}, the :math:\mathrm{il}\ th to :math:\mathrm{iu}\ th eigenvalues will be found.

**d** : float, array-like, shape :math:\left(n\right)
The :math:n diagonal elements of the tridiagonal matrix :math:T.

**e** : float, array-like, shape :math:\left(n-1\right)
The :math:\left(n-1\right) subdiagonal elements of the tridiagonal matrix :math:T.

**vl** : float
If :math:\mathrm{erange} = \texttt{'V'}, the lower and upper bounds of the interval to be searched for eigenvalues.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'I'}, :math:\mathrm{vl} and :math:\mathrm{vu} are not referenced.

**vu** : float
If :math:\mathrm{erange} = \texttt{'V'}, the lower and upper bounds of the interval to be searched for eigenvalues.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'I'}, :math:\mathrm{vl} and :math:\mathrm{vu} are not referenced.

**il** : int
If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{il} and :math:\mathrm{iu} specify the indices (in ascending order) of the smallest and largest eigenvalues to be returned, respectively.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}, :math:\mathrm{il} and :math:\mathrm{iu} are not referenced.

**iu** : int
If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{il} and :math:\mathrm{iu} specify the indices (in ascending order) of the smallest and largest eigenvalues to be returned, respectively.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}, :math:\mathrm{il} and :math:\mathrm{iu} are not referenced.

**abstol** : float
The absolute error tolerance for the eigenvalues. An approximate eigenvalue is accepted as converged when it is determined to lie in an interval :math:\left[a, b\right] of width less than or equal to

.. math::
\mathrm{abstol}+\epsilon \mathrm{max}\left(\left\lvert a\right\rvert, \left\lvert b\right\rvert \right)\text{,}

where :math:\epsilon is the machine precision. If :math:\mathrm{abstol} is less than or equal to zero, then :math:\epsilon \left\lVert T\right\rVert_1 will be used in its place. See Demmel and Kahan (1990).

If high relative accuracy is important, set :math:\mathrm{abstol} to :math:\texttt{machine.real_safe}\left(\right), although doing so does not currently guarantee that eigenvalues are computed to high relative accuracy.

See Barlow and Demmel (1990) for a discussion of which matrices can define their eigenvalues to high relative accuracy.

**Returns**
**d** : float, ndarray, shape :math:\left(n\right)
May be multiplied by a constant factor chosen to avoid over/underflow in computing the eigenvalues.

**e** : float, ndarray, shape :math:\left(n-1\right)
May be multiplied by a constant factor chosen to avoid over/underflow in computing the eigenvalues.

**m** : int
The total number of eigenvalues found. :math:0\leq \mathrm{m}\leq n.

If :math:\mathrm{erange} = \texttt{'A'}, :math:\mathrm{m} = n.

If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{m} = \mathrm{iu}-\mathrm{il}+1.

**w** : float, ndarray, shape :math:\left(n\right)
The first :math:\mathrm{m} elements contain the selected eigenvalues in ascending order.

**z** : float, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobz} = \texttt{'V'}, the first :math:\mathrm{m} columns of :math:Z contain the orthonormal eigenvectors of the matrix :math:A corresponding to the selected eigenvalues, with the :math:i\ th column of :math:Z holding the eigenvector associated with :math:\mathrm{w}[i-1].

If :math:\mathrm{jobz} = \texttt{'N'}, :math:\mathrm{z} is not referenced.

**Note:** you must ensure that at least :math:\mathrm{max}\left(1, \mathrm{m}\right) columns are supplied in the array :math:\mathrm{z}; if :math:\mathrm{erange} = \texttt{'V'}, the exact value of :math:\mathrm{m} is not known in advance and an upper bound of at least :math:\textit{n} must be used.

**isuppz** : int, ndarray, shape :math:\left(:\right)
The support of the eigenvectors in :math:\mathrm{z}, i.e., the indices indicating the nonzero elements in :math:\mathrm{z}. The :math:i\ th eigenvector is nonzero only in elements :math:\mathrm{isuppz}[2\times i-2] through :math:\mathrm{isuppz}[2\times i-1]. Implemented only for :math:\mathrm{erange} = \texttt{'A'} or :math:\mathrm{erange} = \texttt{'I'} and :math:\mathrm{iu}-\mathrm{il} = n-1.

.. _f08jd-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{jobz}.

Constraint: :math:\mathrm{jobz} = \texttt{'N'} or :math:\texttt{'V'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{erange}.

Constraint: :math:\mathrm{erange} = \texttt{'A'}, :math:\texttt{'V'} or :math:\texttt{'I'}.

(errno :math:-3)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

(errno :math:-7)
On entry, error in parameter :math:\mathrm{vu}.

Constraint: :math:\mathrm{vl} < \mathrm{vu}.

(errno :math:-8)
On entry, error in parameter :math:\mathrm{il}.

(errno :math:-9)
On entry, error in parameter :math:\mathrm{iu}.

(errno :math:i > 0)
An internal error has occurred in this function. Please refer to :math:\textit{errno} in :meth:dstebz.

.. _f08jd-py2-py-notes:

**Notes**
Whenever possible dstevr computes the eigenspectrum using Relatively Robust Representations. dstevr computes eigenvalues by the dqds algorithm, while orthogonal eigenvectors are computed from various 'good' :math:LDL^\mathrm{T} representations (also known as Relatively Robust Representations).
Gram--Schmidt orthogonalization is avoided as far as possible.
More specifically, the various steps of the algorithm are as follows.
For the :math:i\ th unreduced block of :math:T:

(a) compute :math:T-\sigma_iI = L_iD_iL_i^\mathrm{T}, such that :math:L_iD_iL_i^\mathrm{T} is a relatively robust representation,

(#) compute the eigenvalues, :math:\lambda_j, of :math:L_iD_iL_i^\mathrm{T} to high relative accuracy by the dqds algorithm,

(#) if there is a cluster of close eigenvalues, 'choose' :math:\sigma_i close to the cluster, and go to \(a),

(#) given the approximate eigenvalue :math:\lambda_j of :math:L_iD_iL_i^\mathrm{T}, compute the corresponding eigenvector by forming a rank-revealing twisted factorization.

The desired accuracy of the output can be specified by the argument :math:\mathrm{abstol}.
For more details, see Dhillon (1997) and Parlett and Dhillon (2000).

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

Barlow, J and Demmel, J W, 1990, Computing accurate eigensystems of scaled diagonally dominant matrices, SIAM J. Numer. Anal. (27), 762--791

Demmel, J W and Kahan, W, 1990, Accurate singular values of bidiagonal matrices, SIAM J. Sci. Statist. Comput. (11), 873--912

Dhillon, I, 1997, A new :math:\mathrm{O}\left(n^2\right) algorithm for the symmetric tridiagonal eigenvalue/eigenvector problem, Computer Science Division Technical Report No. UCB//CSD-97-971, UC Berkeley

Golub, G H and Van Loan, C F, 1996, Matrix Computations, (3rd Edition), Johns Hopkins University Press, Baltimore

Parlett, B N and Dhillon, I S, 2000, Relatively robust representations of symmetric tridiagonals, Linear Algebra Appl. (309), 121--151
"""
raise NotImplementedError

[docs]def dsteqr(compz, d, e, z=None):
r"""
dsteqr computes all the eigenvalues and, optionally, all the eigenvectors of a real symmetric tridiagonal matrix, or of a real symmetric matrix which has been reduced to tridiagonal form.

.. _f08je-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08jef.html

.. _f08je-py2-py-parameters:

**Parameters**
**compz** : str, length 1
Indicates whether the eigenvectors are to be computed.

:math:\mathrm{compz} = \texttt{'N'}

Only the eigenvalues are computed (and the array :math:\mathrm{z} is not referenced).

:math:\mathrm{compz} = \texttt{'V'}

The eigenvalues and eigenvectors of :math:A are computed (and the array :math:\mathrm{z} must contain the matrix :math:Q on entry).

:math:\mathrm{compz} = \texttt{'I'}

The eigenvalues and eigenvectors of :math:T are computed (and the array :math:\mathrm{z} is initialized by the function).

**d** : float, array-like, shape :math:\left(n\right)
The diagonal elements of the tridiagonal matrix :math:T.

**e** : float, array-like, shape :math:\left(\max\left(1,{n-1}\right)\right)
The off-diagonal elements of the tridiagonal matrix :math:T.

**z** : None or float, array-like, shape :math:\left(:, :\right), optional
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\mathrm{compz}\text{ in } (\texttt{'V'}, \texttt{'I'}): :math:\max\left(1,n\right); if :math:\mathrm{compz}=\texttt{'N'}: :math:1; otherwise: :math:0.

Note: the required extent for this argument in dimension 2 is determined as follows: if :math:\mathrm{compz}\text{ in } (\texttt{'V'}, \texttt{'I'}): :math:n; otherwise: :math:0.

If :math:\mathrm{compz} = \texttt{'V'}, :math:\mathrm{z} must contain the orthogonal matrix :math:Q from the reduction to tridiagonal form.

If :math:\mathrm{compz} = \texttt{'I'}, :math:\mathrm{z} need not be set.

**Returns**
**d** : float, ndarray, shape :math:\left(n\right)
The :math:n eigenvalues in ascending order, unless :math:\mathrm{errno} > 0 (in which case see :ref:Exceptions <f08je-py2-py-errors>).

**e** : float, ndarray, shape :math:\left(\max\left(1,{n-1}\right)\right)
:math:\mathrm{e} is overwritten.

**z** : None or float, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{compz} = \texttt{'V'} or :math:\texttt{'I'}, the :math:n required orthonormal eigenvectors stored as columns of :math:Z; the :math:i\ th column corresponds to the :math:i\ th eigenvalue, where :math:i = 1,2,\ldots,n, unless :math:\mathrm{errno} > 0.

If :math:\mathrm{compz} = \texttt{'N'}, :math:\mathrm{z} is not referenced.

.. _f08je-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{compz}.

Constraint: :math:\mathrm{compz} = \texttt{'N'}, :math:\texttt{'V'} or :math:\texttt{'I'}.

(errno :math:-2)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

**Warns**
**NagAlgorithmicWarning**
(errno :math:i > 0)
The algorithm has failed to find all the eigenvalues after a total of :math:30\times n iterations. In this case, :math:\mathrm{d} and :math:\mathrm{e} contain on exit the diagonal and off-diagonal elements, respectively, of a tridiagonal matrix orthogonally similar to :math:T. :math:\langle\mathit{\boldsymbol{value}}\rangle off-diagonal elements have not converged to zero.

.. _f08je-py2-py-notes:

**Notes**
dsteqr computes all the eigenvalues and, optionally, all the eigenvectors of a real symmetric tridiagonal matrix :math:T. In other words, it can compute the spectral factorization of :math:T as

.. math::
T = Z\Lambda Z^\mathrm{T}\text{,}

where :math:\Lambda is a diagonal matrix whose diagonal elements are the eigenvalues :math:\lambda_i, and :math:Z is the orthogonal matrix whose columns are the eigenvectors :math:z_i.
Thus

.. math::
Tz_i = \lambda_iz_i\text{, }\quad i = 1,2,\ldots,n\text{.}

The function may also be used to compute all the eigenvalues and eigenvectors of a real symmetric matrix :math:A which has been reduced to tridiagonal form :math:T:

.. math::
\begin{array}{ll}A& = QTQ^\mathrm{T}\text{, where }Q\text{ is orthogonal}\\& = \left(QZ\right)\Lambda \left(QZ\right)^\mathrm{T}\text{.}\end{array}

In this case, the matrix :math:Q must be formed explicitly and passed to dsteqr, which must be called with :math:\mathrm{compz} = \texttt{'V'}.
The functions which must be called to perform the reduction to tridiagonal form and form :math:Q are:

+---------------------------+-----------------------------------------------------------+
|full matrix                |:meth:dsytrd and :meth:dorgtr                          |
+---------------------------+-----------------------------------------------------------+
|full matrix, packed storage|:meth:dsptrd and :meth:dopgtr                          |
+---------------------------+-----------------------------------------------------------+
|band matrix                |:meth:dsbtrd with :math:{\textit{vect}} = \texttt{'V'}.|
+---------------------------+-----------------------------------------------------------+

dsteqr uses the implicitly shifted :math:QR algorithm, switching between the :math:QR and :math:QL variants in order to handle graded matrices effectively (see Greenbaum and Dongarra (1980)).
The eigenvectors are normalized so that :math:\left\lVert z_i\right\rVert_2 = 1, but are determined only to within a factor :math:{\pm 1}.

If only the eigenvalues of :math:T are required, it is more efficient to call :meth:dsterf instead.
If :math:T is positive definite, small eigenvalues can be computed more accurately by :meth:dpteqr.

.. _f08je-py2-py-references:

**References**
Golub, G H and Van Loan, C F, 1996, Matrix Computations, (3rd Edition), Johns Hopkins University Press, Baltimore

Greenbaum, A and Dongarra, J J, 1980, Experiments with QR/QL methods for the symmetric triangular eigenproblem, LAPACK Working Note No. 17 (Technical Report CS-89-92), University of Tennessee, Knoxville, https://www.netlib.org/lapack/lawnspdf/lawn17.pdf

Parlett, B N, 1998, The Symmetric Eigenvalue Problem, SIAM, Philadelphia
"""
raise NotImplementedError

[docs]def dsterf(d, e):
r"""
dsterf computes all the eigenvalues of a real symmetric tridiagonal matrix.

.. _f08jf-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08jff.html

.. _f08jf-py2-py-parameters:

**Parameters**
**d** : float, array-like, shape :math:\left(n\right)
The diagonal elements of the tridiagonal matrix :math:T.

**e** : float, array-like, shape :math:\left(\max\left(1,{n-1}\right)\right)
The off-diagonal elements of the tridiagonal matrix :math:T.

**Returns**
**d** : float, ndarray, shape :math:\left(n\right)
The :math:n eigenvalues in ascending order, unless :math:\mathrm{errno} > 0 (in which case see :ref:Exceptions <f08jf-py2-py-errors>).

**e** : float, ndarray, shape :math:\left(\max\left(1,{n-1}\right)\right)
:math:\mathrm{e} is overwritten.

.. _f08jf-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)
The algorithm has failed to find all the eigenvalues after a total of :math:30\times n iterations; :math:\langle\mathit{\boldsymbol{value}}\rangle elements of :math:\mathrm{e} have not converged to zero.

.. _f08jf-py2-py-notes:

**Notes**
dsterf computes all the eigenvalues of a real symmetric tridiagonal matrix, using a square-root-free variant of the :math:QR algorithm.

The function uses an explicit shift, and, like :meth:dsteqr, switches between the :math:QR and :math:QL variants in order to handle graded matrices effectively (see Greenbaum and Dongarra (1980)).

.. _f08jf-py2-py-references:

**References**
Greenbaum, A and Dongarra, J J, 1980, Experiments with QR/QL methods for the symmetric triangular eigenproblem, LAPACK Working Note No. 17 (Technical Report CS-89-92), University of Tennessee, Knoxville, https://www.netlib.org/lapack/lawnspdf/lawn17.pdf

Parlett, B N, 1998, The Symmetric Eigenvalue Problem, SIAM, Philadelphia
"""
raise NotImplementedError

[docs]def dpteqr(compz, d, e, z):
r"""
dpteqr computes all the eigenvalues and, optionally, all the eigenvectors of a real symmetric positive definite tridiagonal matrix, or of a real symmetric positive definite matrix which has been reduced to tridiagonal form.

.. _f08jg-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08jgf.html

.. _f08jg-py2-py-parameters:

**Parameters**
**compz** : str, length 1
Indicates whether the eigenvectors are to be computed.

:math:\mathrm{compz} = \texttt{'N'}

Only the eigenvalues are computed (and the array :math:\mathrm{z} is not referenced).

:math:\mathrm{compz} = \texttt{'V'}

The eigenvalues and eigenvectors of :math:A are computed (and the array :math:\mathrm{z} must contain the matrix :math:Q on entry).

:math:\mathrm{compz} = \texttt{'I'}

The eigenvalues and eigenvectors of :math:T are computed (and the array :math:\mathrm{z} is initialized by the function).

**d** : float, array-like, shape :math:\left(n\right)
The diagonal elements of the tridiagonal matrix :math:T.

**e** : float, array-like, shape :math:\left(\max\left(1,{n-1}\right)\right)
The off-diagonal elements of the tridiagonal matrix :math:T.

**z** : float, array-like, shape :math:\left(:, :\right)
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\mathrm{compz}\text{ in } (\texttt{'V'}, \texttt{'I'}): :math:\max\left(1,n\right); if :math:\mathrm{compz}=\texttt{'N'}: :math:1; otherwise: :math:0.

Note: the required extent for this argument in dimension 2 is determined as follows: if :math:\mathrm{compz}\text{ in } (\texttt{'V'}, \texttt{'I'}): :math:n; if :math:\mathrm{compz}=\texttt{'N'}: :math:1; otherwise: :math:0.

If :math:\mathrm{compz} = \texttt{'V'}, :math:\mathrm{z} must contain the orthogonal matrix :math:Q from the reduction to tridiagonal form.

If :math:\mathrm{compz} = \texttt{'I'}, :math:\mathrm{z} need not be set.

**Returns**
**d** : float, ndarray, shape :math:\left(n\right)
The :math:n eigenvalues in descending order, unless :math:\mathrm{errno} > 0, in which case :math:\mathrm{d} is overwritten.

**e** : float, ndarray, shape :math:\left(\max\left(1,{n-1}\right)\right)
:math:\mathrm{e} is overwritten.

**z** : float, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{compz} = \texttt{'V'} or :math:\texttt{'I'}, the :math:n required orthonormal eigenvectors stored as columns of :math:Z; the :math:i\ th column corresponds to the :math:i\ th eigenvalue, where :math:i = 1,2,\ldots,n, unless :math:\mathrm{errno} > 0.

If :math:\mathrm{compz} = \texttt{'N'}, :math:\mathrm{z} is not referenced.

.. _f08jg-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{compz}.

Constraint: :math:\mathrm{compz} = \texttt{'N'}, :math:\texttt{'V'} or :math:\texttt{'I'}.

(errno :math:-2)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

(errno :math:i > 0\text{ and }i\leq n)
The leading minor of order :math:\langle\mathit{\boldsymbol{value}}\rangle is not positive definite and the Cholesky factorization of :math:T could not be completed. Hence :math:T itself is not positive definite.

(errno :math:i > n)
The algorithm to compute the singular values of the Cholesky factor :math:B failed to converge; :math:\langle\mathit{\boldsymbol{value}}\rangle off-diagonal elements did not converge to zero.

.. _f08jg-py2-py-notes:

**Notes**
dpteqr computes all the eigenvalues and, optionally, all the eigenvectors of a real symmetric positive definite tridiagonal matrix :math:T. In other words, it can compute the spectral factorization of :math:T as

.. math::
T = Z\Lambda Z^\mathrm{T}\text{,}

where :math:\Lambda is a diagonal matrix whose diagonal elements are the eigenvalues :math:\lambda_i, and :math:Z is the orthogonal matrix whose columns are the eigenvectors :math:z_i.
Thus

.. math::
Tz_i = \lambda_iz_i\text{, }\quad i = 1,2,\ldots,n\text{.}

The function may also be used to compute all the eigenvalues and eigenvectors of a real symmetric positive definite matrix :math:A which has been reduced to tridiagonal form :math:T:

.. math::
\begin{array}{ll}A& = QTQ^\mathrm{T}\text{, where }Q\text{ is orthogonal}\\& = \left(QZ\right)\Lambda \left(QZ\right)^\mathrm{T}\text{.}\end{array}

In this case, the matrix :math:Q must be formed explicitly and passed to dpteqr, which must be called with :math:\mathrm{compz} = \texttt{'V'}.
The functions which must be called to perform the reduction to tridiagonal form and form :math:Q are:

+---------------------------+-----------------------------------------------------------+
|full matrix                |:meth:dsytrd and :meth:dorgtr                          |
+---------------------------+-----------------------------------------------------------+
|full matrix, packed storage|:meth:dsptrd and :meth:dopgtr                          |
+---------------------------+-----------------------------------------------------------+
|band matrix                |:meth:dsbtrd with :math:{\textit{vect}} = \texttt{'V'}.|
+---------------------------+-----------------------------------------------------------+

dpteqr first factorizes :math:T as :math:LDL^\mathrm{T} where :math:L is unit lower bidiagonal and :math:D is diagonal.
It forms the bidiagonal matrix :math:B = LD^{{\frac{1}{2}}}, and then calls :meth:dbdsqr to compute the singular values of :math:B which are the same as the eigenvalues of :math:T.
The method used by the function allows high relative accuracy to be achieved in the small eigenvalues of :math:T.
The eigenvectors are normalized so that :math:\left\lVert z_i\right\rVert_2 = 1, but are determined only to within a factor :math:{\pm 1}.

.. _f08jg-py2-py-references:

**References**
Barlow, J and Demmel, J W, 1990, Computing accurate eigensystems of scaled diagonally dominant matrices, SIAM J. Numer. Anal. (27), 762--791
"""
raise NotImplementedError

[docs]def dstedc(compz, d, e, z):
r"""
dstedc computes all the eigenvalues and, optionally, all the eigenvectors of a real :math:n\times n symmetric tridiagonal matrix, or of a real full or banded symmetric matrix which has been reduced to tridiagonal form.

.. _f08jh-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08jhf.html

.. _f08jh-py2-py-parameters:

**Parameters**
**compz** : str, length 1
Indicates whether the eigenvectors are to be computed.

:math:\mathrm{compz} = \texttt{'N'}

Only the eigenvalues are computed (and the array :math:\mathrm{z} is not referenced).

:math:\mathrm{compz} = \texttt{'V'}

The eigenvalues and eigenvectors of :math:A are computed (and the array :math:\mathrm{z} must contain the matrix :math:Q on entry).

:math:\mathrm{compz} = \texttt{'I'}

The eigenvalues and eigenvectors of :math:T are computed (and the array :math:\mathrm{z} is initialized by the function).

**d** : float, array-like, shape :math:\left(n\right)
The diagonal elements of the tridiagonal matrix.

**e** : float, array-like, shape :math:\left(\max\left(1,{n-1}\right)\right)
The subdiagonal elements of the tridiagonal matrix.

**z** : float, array-like, shape :math:\left(:, :\right)
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\mathrm{compz}\text{ in } (\texttt{'V'}, \texttt{'I'}): :math:n; otherwise: :math:1.

Note: the required extent for this argument in dimension 2 is determined as follows: if :math:\mathrm{compz}\text{ in } (\texttt{'V'}, \texttt{'I'}): :math:n; otherwise: :math:1.

If :math:\mathrm{compz} = \texttt{'V'}, :math:\mathrm{z} must contain the orthogonal matrix :math:Q used in the reduction to tridiagonal form.

**Returns**
**d** : float, ndarray, shape :math:\left(n\right)
If no exception or warning is raised, the eigenvalues in ascending order.

**e** : float, ndarray, shape :math:\left(\max\left(1,{n-1}\right)\right)
:math:\mathrm{e} is overwritten.

**z** : float, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{compz} = \texttt{'V'}, :math:\mathrm{z} contains the orthonormal eigenvectors of the original symmetric matrix :math:A, and if :math:\mathrm{compz} = \texttt{'I'}, :math:\mathrm{z} contains the orthonormal eigenvectors of the symmetric tridiagonal matrix :math:T.

If :math:\mathrm{compz} = \texttt{'N'}, :math:\mathrm{z} is not referenced.

.. _f08jh-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{compz}.

Constraint: :math:\mathrm{compz} = \texttt{'N'}, :math:\texttt{'V'} or :math:\texttt{'I'}.

(errno :math:-2)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

**Warns**
**NagAlgorithmicWarning**
(errno :math:i > 0)
The algorithm failed to compute an eigenvalue while working on the submatrix lying in rows and columns :math:\langle\mathit{\boldsymbol{value}}\rangle/\left(n+1\right) through :math:\mathrm{mod}\left(\langle\mathit{\boldsymbol{value}}\rangle, {n+1}\right).

.. _f08jh-py2-py-notes:

**Notes**
dstedc computes all the eigenvalues and, optionally, the eigenvectors of a real symmetric tridiagonal matrix :math:T.
That is, the function computes the spectral factorization of :math:T given by

.. math::
T = Z\Lambda Z^\mathrm{T}\text{,}

where :math:\Lambda is a diagonal matrix whose diagonal elements are the eigenvalues, :math:\lambda_i, of :math:T and :math:Z is an orthogonal matrix whose columns are the eigenvectors, :math:z_i, of :math:T.
Thus

.. math::
Tz_i = \lambda_iz_i\text{, }\quad i = 1,2,\ldots,n\text{.}

The function may also be used to compute all the eigenvalues and vectors of a real full, or banded, symmetric matrix :math:A which has been reduced to tridiagonal form :math:T as

.. math::
A = {QTQ^\mathrm{T}}\text{,}

where :math:Q is orthogonal.
The spectral factorization of :math:A is then given by

.. math::
A = \left(QZ\right)\Lambda \left(QZ\right)^\mathrm{T}\text{.}

In this case :math:Q must be formed explicitly and passed to dstedc in the array :math:\mathrm{z}, and the function called with :math:\mathrm{compz} = \texttt{'V'}. Functions which may be called to form :math:T and :math:Q are

+---------------------------+-----------------------------------------------------------+
|full matrix                |:meth:dsytrd and :meth:dorgtr                          |
+---------------------------+-----------------------------------------------------------+
|full matrix, packed storage|:meth:dsptrd and :meth:dopgtr                          |
+---------------------------+-----------------------------------------------------------+
|band matrix                |:meth:dsbtrd, with :math:{\textit{vect}} = \texttt{'V'}|
+---------------------------+-----------------------------------------------------------+

When only eigenvalues are required then this function calls :meth:dsterf to compute the eigenvalues of the tridiagonal matrix :math:T, but when eigenvectors of :math:T are also required and the matrix is not too small, then a divide and conquer method is used, which can be much faster than :meth:dsteqr, although more storage is required.

.. _f08jh-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 dstebz(erange, order, vl, vu, il, iu, abstol, d, e):
r"""
dstebz computes some (or all) of the eigenvalues of a real symmetric tridiagonal matrix, by bisection.

.. _f08jj-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08jjf.html

.. _f08jj-py2-py-parameters:

**Parameters**
**erange** : str, length 1
Indicates which eigenvalues are required.

:math:\mathrm{erange} = \texttt{'A'}

All the eigenvalues are required.

:math:\mathrm{erange} = \texttt{'V'}

All the eigenvalues in the half-open interval (:math:\mathrm{vl},\ :math:\mathrm{vu}] are required.

:math:\mathrm{erange} = \texttt{'I'}

Eigenvalues with indices :math:\mathrm{il} to :math:\mathrm{iu} are required.

**order** : str, length 1
Indicates the order in which the eigenvalues and their block numbers are to be stored.

:math:\mathrm{order} = \texttt{'B'}

The eigenvalues are to be grouped by split-off block and ordered from smallest to largest within each block.

:math:\mathrm{order} = \texttt{'E'}

The eigenvalues for the entire matrix are to be ordered from smallest to largest.

**vl** : float
If :math:\mathrm{erange} = \texttt{'V'}, the lower and upper bounds, respectively, of the half-open interval :math:\left(\mathrm{vl}, \mathrm{vu}\right] within which the required eigenvalues lie.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'I'}, :math:\mathrm{vl} is not referenced.

**vu** : float
If :math:\mathrm{erange} = \texttt{'V'}, the lower and upper bounds, respectively, of the half-open interval :math:\left(\mathrm{vl}, \mathrm{vu}\right] within which the required eigenvalues lie.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'I'}, :math:\mathrm{vu} is not referenced.

**il** : int
If :math:\mathrm{erange} = \texttt{'I'}, the indices of the first and last eigenvalues, respectively, to be computed (assuming that the eigenvalues are in ascending order).

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}, :math:\mathrm{il} is not referenced.

**iu** : int
If :math:\mathrm{erange} = \texttt{'I'}, the indices of the first and last eigenvalues, respectively, to be computed (assuming that the eigenvalues are in ascending order).

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}, :math:\mathrm{iu} is not referenced.

**abstol** : float
The absolute tolerance to which each eigenvalue is required. An eigenvalue (or cluster) is considered to have converged if it lies in an interval of width :math:\text{}\leq \mathrm{abstol}. If :math:\mathrm{abstol}\leq 0.0, the tolerance is taken as :math:\text{machine precision}\times \left\lVert T\right\rVert_1.

**d** : float, array-like, shape :math:\left(n\right)
The diagonal elements of the tridiagonal matrix :math:T.

**e** : float, array-like, shape :math:\left(\max\left(1,{n-1}\right)\right)
The off-diagonal elements of the tridiagonal matrix :math:T.

**Returns**
**m** : int
:math:m, the actual number of eigenvalues found.

**nsplit** : int
The number of diagonal blocks which constitute the tridiagonal matrix :math:T.

**w** : float, ndarray, shape :math:\left(n\right)
The required eigenvalues of the tridiagonal matrix :math:T stored in :math:\mathrm{w} to :math:\mathrm{w}[m-1].

**iblock** : int, ndarray, shape :math:\left(n\right)
At each row/column :math:j where :math:\mathrm{e}[j-1] is zero or negligible, :math:T is considered to split into a block diagonal matrix and :math:\mathrm{iblock}[\textit{i}-1] contains the block number of the eigenvalue stored in :math:\mathrm{w}[\textit{i}-1], for :math:\textit{i} = 1,2,\ldots,m. Note that :math:\mathrm{iblock}[\textit{i}-1] < 0 for some :math:i whenever :math:\mathrm{errno} = 1 or 3 (see :ref:Exceptions <f08jj-py2-py-errors>) and :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}.

**isplit** : int, ndarray, shape :math:\left(n\right)
The leading :math:\mathrm{nsplit} elements contain the points at which :math:T splits up into sub-matrices as follows. The first sub-matrix consists of rows/columns :math:1 to :math:\mathrm{isplit}, the second sub-matrix consists of rows/columns :math:\mathrm{isplit}+1 to :math:\mathrm{isplit}, :math:\ldots, and the :math:\mathrm{nsplit}\ (th) sub-matrix consists of rows/columns :math:\mathrm{isplit}[\mathrm{nsplit}-2]+1 to :math:\mathrm{isplit}[\mathrm{nsplit}-1] (:math:\text{} = n).

.. _f08jj-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{erange}.

Constraint: :math:\mathrm{erange} = \texttt{'A'}, :math:\texttt{'V'} or :math:\texttt{'I'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{order}.

Constraint: :math:\mathrm{order} = \texttt{'B'} or :math:\texttt{'E'}.

(errno :math:-3)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

(errno :math:-5)
On entry, error in parameter :math:\mathrm{vu}.

Constraint: :math:\mathrm{vl} < \mathrm{vu}.

(errno :math:-6)
On entry, error in parameter :math:\mathrm{il}.

Constraint: :math:\mathrm{il}\geq 1 and :math:\mathrm{il}\leq \mathrm{max}\left(1, n\right).

(errno :math:-7)
On entry, error in parameter :math:\mathrm{iu}.

Constraint: :math:\mathrm{iu}\leq n and :math:\mathrm{iu}\geq \mathrm{min}\left(n, \mathrm{il}\right).

(errno :math:2)
If :math:\mathrm{erange} = \texttt{'I'}, the algorithm failed to compute some (or all) of the required eigenvalues. Try calling the function again with :math:\mathrm{erange} = \texttt{'A'}.

(errno :math:3)
If :math:\mathrm{erange} = \texttt{'I'}, the algorithm failed to compute some (or all) of the required eigenvalues. Try calling the function again with :math:\mathrm{erange} = \texttt{'A'}. If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}, the algorithm failed to compute some (or all) of the required eigenvalues to the required accuracy. More precisely, :math:\mathrm{iblock}[\langle\mathit{\boldsymbol{value}}\rangle] < 0 indicates that eigenvalue :math:\langle\mathit{\boldsymbol{value}}\rangle (stored in :math:\mathrm{w}[\langle\mathit{\boldsymbol{value}}\rangle]) failed to converge.

(errno :math:4)
No eigenvalues have been computed. The floating-point arithmetic on the computer is not behaving as expected.

**Warns**
**NagAlgorithmicWarning**
(errno :math:1)
If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}, the algorithm failed to compute some (or all) of the required eigenvalues to the required accuracy. More precisely, :math:\mathrm{iblock}[\langle\mathit{\boldsymbol{value}}\rangle] < 0 indicates that eigenvalue :math:\langle\mathit{\boldsymbol{value}}\rangle (stored in :math:\mathrm{w}[\langle\mathit{\boldsymbol{value}}\rangle]) failed to converge.

.. _f08jj-py2-py-notes:

**Notes**
dstebz uses bisection to compute some or all of the eigenvalues of a real symmetric tridiagonal matrix :math:T.

It searches for zero or negligible off-diagonal elements of :math:T to see if the matrix splits into block diagonal form:

.. math::
T = \begin{pmatrix}T_1&&&&&\\&T_2&&&&\\&&.&&&\\&&&.&&\\&&&&.&\\&&&&&T_p\end{pmatrix}\text{.}

It performs bisection on each of the blocks :math:T_i and returns the block index of each computed eigenvalue, so that a subsequent call to :meth:dstein to compute eigenvectors can also take advantage of the block structure.

.. _f08jj-py2-py-references:

**References**
Kahan, W, 1966, Accurate eigenvalues of a symmetric tridiagonal matrix, Report CS41, Stanford University
"""
raise NotImplementedError

[docs]def dstein(d, e, m, w, iblock, isplit):
r"""
dstein computes the eigenvectors of a real symmetric tridiagonal matrix corresponding to specified eigenvalues, by inverse iteration.

.. _f08jk-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08jkf.html

.. _f08jk-py2-py-parameters:

**Parameters**
**d** : float, array-like, shape :math:\left(n\right)
The diagonal elements of the tridiagonal matrix :math:T.

**e** : float, array-like, shape :math:\left(n-1\right)
The off-diagonal elements of the tridiagonal matrix :math:T.

**m** : int
:math:m, the number of eigenvectors to be returned.

**w** : float, array-like, shape :math:\left(n\right)
The eigenvalues of the tridiagonal matrix :math:T stored in :math:\mathrm{w} to :math:\mathrm{w}[m-1], as returned by :meth:dstebz with :math:{\textit{order}} = \texttt{'B'}. Eigenvalues associated with the first sub-matrix must be supplied first, in nondecreasing order; then those associated with the second sub-matrix, again in nondecreasing order; and so on.

**iblock** : int, array-like, shape :math:\left(n\right)
The first :math:m elements must contain the sub-matrix indices associated with the specified eigenvalues, as returned by :meth:dstebz with :math:{\textit{order}} = \texttt{'B'}. If the eigenvalues were not computed by :meth:dstebz with :math:{\textit{order}} = \texttt{'B'}, set :math:\mathrm{iblock}[\textit{i}-1] to :math:1, for :math:\textit{i} = 1,2,\ldots,m.

**isplit** : int, array-like, shape :math:\left(n\right)
The points at which :math:T breaks up into sub-matrices, as returned by :meth:dstebz with :math:{\textit{order}} = \texttt{'B'}. If the eigenvalues were not computed by :meth:dstebz with :math:{\textit{order}} = \texttt{'B'}, set :math:\mathrm{isplit} to :math:\textit{n}.

**Returns**
**z** : float, ndarray, shape :math:\left(n, \mathrm{m}\right)
The :math:m eigenvectors, stored as columns of :math:Z; the :math:i\ th column corresponds to the :math:i\ th specified eigenvalue, unless :math:\mathrm{errno} > 0 (in which case see :ref:Exceptions <f08jk-py2-py-errors>).

**ifailv** : int, ndarray, shape :math:\left(\mathrm{m}\right)
If :math:\textit{errno} = i > 0, the first :math:i elements of :math:\mathrm{ifailv} contain the indices of any eigenvectors which have failed to converge. The rest of the first :math:\mathrm{m} elements of :math:\mathrm{ifailv} are set to :math:0.

.. _f08jk-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

(errno :math:-4)
On entry, error in parameter :math:\mathrm{m}.

Constraint: :math:0\leq \mathrm{m}\leq n.

(errno -5)
On entry, error in parameter :math:\mathrm{w}.

Constraint: :math:\mathrm{w}[\textit{i}]\leq \mathrm{w}[\textit{i}+1].

(errno -6)
On entry, error in parameter :math:\mathrm{iblock}.

Constraint: :math:\mathrm{iblock}[\textit{i}]\leq \mathrm{iblock}[\textit{i}+1].

**Warns**
**NagAlgorithmicWarning**
(errno :math:i > 0)
:math:\langle\mathit{\boldsymbol{value}}\rangle eigenvectors (as indicated by argument :math:\mathrm{ifailv}) each failed to converge in five iterations. The current iterate after five iterations is stored in the corresponding column of :math:\mathrm{z}.

.. _f08jk-py2-py-notes:

**Notes**
dstein computes the eigenvectors of a real symmetric tridiagonal matrix :math:T corresponding to specified eigenvalues, by inverse iteration (see Jessup and Ipsen (1992)).
It is designed to be used in particular after the specified eigenvalues have been computed by :meth:dstebz with :math:{\textit{order}} = \texttt{'B'}, but may also be used when the eigenvalues have been computed by other functions in submodule lapackeig or submodule :mod:~naginterfaces.library.eigen.

If :math:T has been formed by reduction of a full real symmetric matrix :math:A to tridiagonal form, then eigenvectors of :math:T may be transformed to eigenvectors of :math:A by a call to :meth:dormtr or :meth:dopmtr.

:meth:dstebz determines whether the matrix :math:T splits into block diagonal form:

.. math::
T = \begin{pmatrix}T_1&&&&&\\&T_2&&&&\\&&.&&&\\&&&.&&\\&&&&.&\\&&&&&T_p\end{pmatrix}

and passes details of the block structure to this function in the arrays :math:\mathrm{iblock} and :math:\mathrm{isplit}.
This function can then take advantage of the block structure by performing inverse iteration on each block :math:T_i separately, which is more efficient than using the whole matrix.

.. _f08jk-py2-py-references:

**References**
Golub, G H and Van Loan, C F, 1996, Matrix Computations, (3rd Edition), Johns Hopkins University Press, Baltimore

Jessup, E and Ipsen, I C F, 1992, Improving the accuracy of inverse iteration, SIAM J. Sci. Statist. Comput. (13), 550--572
"""
raise NotImplementedError

[docs]def dstegr(jobz, erange, d, e, vl, vu, il, iu):
r"""
dstegr computes selected eigenvalues and, optionally, the corresponding eigenvectors of a real :math:n\times n symmetric tridiagonal matrix.

.. _f08jl-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08jlf.html

.. _f08jl-py2-py-parameters:

**Parameters**
**jobz** : str, length 1
Indicates whether eigenvectors are computed.

:math:\mathrm{jobz} = \texttt{'N'}

Only eigenvalues are computed.

:math:\mathrm{jobz} = \texttt{'V'}

Eigenvalues and eigenvectors are computed.

**erange** : str, length 1
Indicates which eigenvalues should be returned.

:math:\mathrm{erange} = \texttt{'A'}

All eigenvalues will be found.

:math:\mathrm{erange} = \texttt{'V'}

All eigenvalues in the half-open interval :math:\left(\mathrm{vl}, \mathrm{vu}\right] will be found.

:math:\mathrm{erange} = \texttt{'I'}

The :math:\mathrm{il}\ th through :math:\mathrm{iu}\ th eigenvectors will be found.

**d** : float, array-like, shape :math:\left(n\right)
The :math:n diagonal elements of the tridiagonal matrix :math:T.

**e** : float, array-like, shape :math:\left(n\right)
:math:\mathrm{e} to :math:\mathrm{e}[n-2] are the subdiagonal elements of the tridiagonal matrix :math:T. :math:\mathrm{e}[n-1] need not be set.

**vl** : float
If :math:\mathrm{erange} = \texttt{'V'}, :math:\mathrm{vl} and :math:\mathrm{vu} contain the lower and upper bounds respectively of the interval to be searched for eigenvalues.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'I'}, :math:\mathrm{vl} and :math:\mathrm{vu} are not referenced.

**vu** : float
If :math:\mathrm{erange} = \texttt{'V'}, :math:\mathrm{vl} and :math:\mathrm{vu} contain the lower and upper bounds respectively of the interval to be searched for eigenvalues.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'I'}, :math:\mathrm{vl} and :math:\mathrm{vu} are not referenced.

**il** : int
If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{il} and :math:\mathrm{iu} specify the indices (in ascending order) of the smallest and largest eigenvalues to be returned, respectively.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}, :math:\mathrm{il} and :math:\mathrm{iu} are not referenced.

**iu** : int
If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{il} and :math:\mathrm{iu} specify the indices (in ascending order) of the smallest and largest eigenvalues to be returned, respectively.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}, :math:\mathrm{il} and :math:\mathrm{iu} are not referenced.

**Returns**
**d** : float, ndarray, shape :math:\left(n\right)
:math:\mathrm{d} is overwritten.

**e** : float, ndarray, shape :math:\left(n\right)
:math:\mathrm{e} is overwritten.

**m** : int
The total number of eigenvalues found. :math:0\leq \mathrm{m}\leq n.

If :math:\mathrm{erange} = \texttt{'A'}, :math:\mathrm{m} = n.

If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{m} = \mathrm{iu}-\mathrm{il}+1.

**w** : float, ndarray, shape :math:\left(n\right)
The eigenvalues in ascending order.

**z** : float, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobz} = \texttt{'V'}, then if no exception or warning is raised, the columns of :math:\mathrm{z} contain the orthonormal eigenvectors of the matrix :math:T, with the :math:i\ th column of :math:Z holding the eigenvector associated with :math:\mathrm{w}[i-1].

If :math:\mathrm{jobz} = \texttt{'N'}, :math:\mathrm{z} is not referenced.

**Note:** you must ensure that at least :math:\mathrm{max}\left(1, \mathrm{m}\right) columns are supplied in the array :math:\mathrm{z}; if :math:\mathrm{erange} = \texttt{'V'}, the exact value of :math:\mathrm{m} is not known in advance and an upper bound of at least :math:\textit{n} must be used.

**isuppz** : int, ndarray, shape :math:\left(:\right)
The support of the eigenvectors in :math:Z, i.e., the indices indicating the nonzero elements in :math:Z. The :math:i\ th eigenvector is nonzero only in elements :math:\mathrm{isuppz}[2\times i-2] through :math:\mathrm{isuppz}[2\times i-1].

.. _f08jl-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{jobz}.

Constraint: :math:\mathrm{jobz} = \texttt{'N'} or :math:\texttt{'V'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{erange}.

Constraint: :math:\mathrm{erange} = \texttt{'A'}, :math:\texttt{'V'} or :math:\texttt{'I'}.

(errno :math:-3)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

(errno :math:-7)
On entry, error in parameter :math:\mathrm{vu}.

Constraint: :math:\mathrm{vl} < \mathrm{vu}.

(errno :math:-9)
On entry, error in parameter :math:\mathrm{iu}.

Constraint: :math:1\leq \mathrm{il}\leq \mathrm{iu}\leq n.

(errno :math:-9)
On entry, error in parameter :math:\mathrm{iu}.

Constraint: :math:\mathrm{il} = 1 and :math:\mathrm{iu} = 0.

(errno :math:i = 1)
The :math:\mathrm{dqds} algorithm failed to converge.

(errno :math:i = 2)
Inverse iteration failed to converge.

.. _f08jl-py2-py-notes:

**Notes**
dstegr computes selected eigenvalues and, optionally, the corresponding eigenvectors, of a real symmetric tridiagonal matrix :math:T.
That is, the function computes the (partial) spectral factorization of :math:T given by

.. math::
Z\Lambda Z^\mathrm{T}\text{,}

where :math:\Lambda is a diagonal matrix whose diagonal elements are the selected eigenvalues, :math:\lambda_i, of :math:T and :math:Z is an orthogonal matrix whose columns are the corresponding eigenvectors, :math:z_i, of :math:T.
Thus

.. math::
Tz_i = \lambda_iz_i\text{, }\quad i = 1,2,\ldots,m

where :math:m is the number of selected eigenvalues computed.

The function may also be used to compute selected eigenvalues and eigenvectors of a real symmetric matrix :math:A which has been reduced to tridiagonal form :math:T:

.. math::
\left(QZ\right)\Lambda \left(QZ\right)^\mathrm{T}\text{, where }Q\text{ is orthogonal.}

In this case, the matrix :math:Q must be explicitly applied to the output matrix :math:Z.
The functions which must be called to perform the reduction to tridiagonal form and apply :math:Q are:

+---------------------------+---------------------------------------------------------------------------------------------------------------------+
|full matrix                |:meth:dsytrd and :meth:dormtr                                                                                    |
+---------------------------+---------------------------------------------------------------------------------------------------------------------+
|full matrix, packed storage|:meth:dsptrd and :meth:dopmtr                                                                                    |
+---------------------------+---------------------------------------------------------------------------------------------------------------------+
|band matrix                |:meth:dsbtrd with :math:{\textit{vect}} = \texttt{'V'} and :meth:blas.dgemm <naginterfaces.library.blas.dgemm>.|
+---------------------------+---------------------------------------------------------------------------------------------------------------------+

This function uses the dqds and the Relatively Robust Representation algorithms to compute the eigenvalues and eigenvectors respectively; see for example Parlett and Dhillon (2000) and Dhillon and Parlett (2004) for further details. dstegr can usually compute all the eigenvalues and eigenvectors in :math:O\left(n^2\right) floating-point operations and so, for large matrices, is often considerably faster than the other symmetric tridiagonal functions in this module when all the eigenvectors are required, particularly so compared to those functions that are based on the :math:QR algorithm.

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

Barlow, J and Demmel, J W, 1990, Computing accurate eigensystems of scaled diagonally dominant matrices, SIAM J. Numer. Anal. (27), 762--791

Dhillon, I S and Parlett, B N, 2004, Orthogonal eigenvectors and relative gaps, SIAM J. Appl. Math. (25), 858--899

Parlett, B N and Dhillon, I S, 2000, Relatively robust representations of symmetric tridiagonals, Linear Algebra Appl. (309), 121--151
"""
raise NotImplementedError

[docs]def zsteqr(compz, d, e, z):
r"""
zsteqr computes all the eigenvalues and, optionally, all the eigenvectors of a complex Hermitian matrix which has been reduced to tridiagonal form.

.. _f08js-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08jsf.html

.. _f08js-py2-py-parameters:

**Parameters**
**compz** : str, length 1
Indicates whether the eigenvectors are to be computed.

:math:\mathrm{compz} = \texttt{'N'}

Only the eigenvalues are computed (and the array :math:\mathrm{z} is not referenced).

:math:\mathrm{compz} = \texttt{'V'}

The eigenvalues and eigenvectors of :math:A are computed (and the array :math:\mathrm{z} must contain the matrix :math:Q on entry).

:math:\mathrm{compz} = \texttt{'I'}

The eigenvalues and eigenvectors of :math:T are computed (and the array :math:\mathrm{z} is initialized by the function).

**d** : float, array-like, shape :math:\left(n\right)
The diagonal elements of the tridiagonal matrix :math:T.

**e** : float, array-like, shape :math:\left(\max\left(1,{n-1}\right)\right)
The off-diagonal elements of the tridiagonal matrix :math:T.

**z** : complex, array-like, shape :math:\left(:, :\right)
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\mathrm{compz}\text{ in } (\texttt{'V'}, \texttt{'I'}): :math:\max\left(1,n\right); if :math:\mathrm{compz}=\texttt{'N'}: :math:1; otherwise: :math:0.

Note: the required extent for this argument in dimension 2 is determined as follows: if :math:\mathrm{compz}\text{ in } (\texttt{'V'}, \texttt{'I'}): :math:n; if :math:\mathrm{compz}=\texttt{'N'}: :math:1; otherwise: :math:0.

If :math:\mathrm{compz} = \texttt{'V'}, :math:\mathrm{z} must contain the unitary matrix :math:Q from the reduction to tridiagonal form.

If :math:\mathrm{compz} = \texttt{'I'}, :math:\mathrm{z} need not be set.

**Returns**
**d** : float, ndarray, shape :math:\left(n\right)
The :math:n eigenvalues in ascending order, unless :math:\mathrm{errno} > 0 (in which case see :ref:Exceptions <f08js-py2-py-errors>).

**e** : float, ndarray, shape :math:\left(\max\left(1,{n-1}\right)\right)
:math:\mathrm{e} is overwritten.

**z** : complex, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{compz} = \texttt{'V'} or :math:\texttt{'I'}, the :math:n required orthonormal eigenvectors stored as columns of :math:Z; the :math:i\ th column corresponds to the :math:i\ th eigenvalue, where :math:i = 1,2,\ldots,n, unless :math:\mathrm{errno} > 0.

If :math:\mathrm{compz} = \texttt{'N'}, :math:\mathrm{z} is not referenced.

.. _f08js-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{compz}.

Constraint: :math:\mathrm{compz} = \texttt{'N'}, :math:\texttt{'V'} or :math:\texttt{'I'}.

(errno :math:-2)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

**Warns**
**NagAlgorithmicWarning**
(errno :math:i > 0)
The algorithm has failed to find all the eigenvalues after a total of :math:30\times n iterations. In this case, :math:\mathrm{d} and :math:\mathrm{e} contain on exit the diagonal and off-diagonal elements, respectively, of a tridiagonal matrix unitarily similar to :math:T. :math:\langle\mathit{\boldsymbol{value}}\rangle off-diagonal elements have not converged to zero.

.. _f08js-py2-py-notes:

**Notes**
zsteqr computes all the eigenvalues and, optionally, all the eigenvectors of a real symmetric tridiagonal matrix :math:T. In other words, it can compute the spectral factorization of :math:T as

.. math::
T = Z\Lambda Z^\mathrm{T}\text{,}

where :math:\Lambda is a diagonal matrix whose diagonal elements are the eigenvalues :math:\lambda_i, and :math:Z is the orthogonal matrix whose columns are the eigenvectors :math:z_i.
Thus

.. math::
Tz_i = \lambda_iz_i\text{, }\quad i = 1,2,\ldots,n\text{.}

The function stores the real orthogonal matrix :math:Z in a complex array, so that it may also be used to compute all the eigenvalues and eigenvectors of a complex Hermitian matrix :math:A which has been reduced to tridiagonal form :math:T:

.. math::
\begin{array}{ll}A& = QTQ^\mathrm{H}\text{, where }Q\text{ is unitary}\\& = \left(QZ\right)\Lambda \left(QZ\right)^\mathrm{H}\text{.}\end{array}

In this case, the matrix :math:Q must be formed explicitly and passed to zsteqr, which must be called with :math:\mathrm{compz} = \texttt{'V'}.
The functions which must be called to perform the reduction to tridiagonal form and form :math:Q are:

+---------------------------+-----------------------------------------------------------+
|full matrix                |:meth:zhetrd and :meth:zungtr                          |
+---------------------------+-----------------------------------------------------------+
|full matrix, packed storage|:meth:zhptrd and :meth:zupgtr                          |
+---------------------------+-----------------------------------------------------------+
|band matrix                |:meth:zhbtrd with :math:{\textit{vect}} = \texttt{'V'}.|
+---------------------------+-----------------------------------------------------------+

zsteqr uses the implicitly shifted :math:QR algorithm, switching between the :math:QR and :math:QL variants in order to handle graded matrices effectively (see Greenbaum and Dongarra (1980)).
The eigenvectors are normalized so that :math:\left\lVert z_i\right\rVert_2 = 1, but are determined only to within a complex factor of absolute value :math:1.

If only the eigenvalues of :math:T are required, it is more efficient to call :meth:dsterf instead.
If :math:T is positive definite, small eigenvalues can be computed more accurately by :meth:zpteqr.

.. _f08js-py2-py-references:

**References**
Golub, G H and Van Loan, C F, 1996, Matrix Computations, (3rd Edition), Johns Hopkins University Press, Baltimore

Greenbaum, A and Dongarra, J J, 1980, Experiments with QR/QL methods for the symmetric triangular eigenproblem, LAPACK Working Note No. 17 (Technical Report CS-89-92), University of Tennessee, Knoxville, https://www.netlib.org/lapack/lawnspdf/lawn17.pdf

Parlett, B N, 1998, The Symmetric Eigenvalue Problem, SIAM, Philadelphia
"""
raise NotImplementedError

[docs]def zpteqr(compz, d, e, z):
r"""
zpteqr computes all the eigenvalues and, optionally, all the eigenvectors of a complex Hermitian positive definite matrix which has been reduced to tridiagonal form.

.. _f08ju-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08juf.html

.. _f08ju-py2-py-parameters:

**Parameters**
**compz** : str, length 1
Indicates whether the eigenvectors are to be computed.

:math:\mathrm{compz} = \texttt{'N'}

Only the eigenvalues are computed (and the array :math:\mathrm{z} is not referenced).

:math:\mathrm{compz} = \texttt{'V'}

The eigenvalues and eigenvectors of :math:A are computed (and the array :math:\mathrm{z} must contain the matrix :math:Q on entry).

:math:\mathrm{compz} = \texttt{'I'}

The eigenvalues and eigenvectors of :math:T are computed (and the array :math:\mathrm{z} is initialized by the function).

**d** : float, array-like, shape :math:\left(n\right)
The diagonal elements of the tridiagonal matrix :math:T.

**e** : float, array-like, shape :math:\left(\max\left(1,{n-1}\right)\right)
The off-diagonal elements of the tridiagonal matrix :math:T.

**z** : complex, array-like, shape :math:\left(:, :\right)
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\mathrm{compz}\text{ in } (\texttt{'V'}, \texttt{'I'}): :math:\max\left(1,n\right); if :math:\mathrm{compz}=\texttt{'N'}: :math:1; otherwise: :math:0.

Note: the required extent for this argument in dimension 2 is determined as follows: if :math:\mathrm{compz}\text{ in } (\texttt{'V'}, \texttt{'I'}): :math:n; if :math:\mathrm{compz}=\texttt{'N'}: :math:1; otherwise: :math:0.

If :math:\mathrm{compz} = \texttt{'V'}, :math:\mathrm{z} must contain the unitary matrix :math:Q from the reduction to tridiagonal form.

If :math:\mathrm{compz} = \texttt{'I'}, :math:\mathrm{z} need not be set.

**Returns**
**d** : float, ndarray, shape :math:\left(n\right)
The :math:n eigenvalues in descending order, unless :math:\mathrm{errno} > 0, in which case :math:\mathrm{d} is overwritten.

**e** : float, ndarray, shape :math:\left(\max\left(1,{n-1}\right)\right)
:math:\mathrm{e} is overwritten.

**z** : complex, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{compz} = \texttt{'V'} or :math:\texttt{'I'}, the :math:n required orthonormal eigenvectors stored as columns of :math:Z; the :math:i\ th column corresponds to the :math:i\ th eigenvalue, where :math:i = 1,2,\ldots,n, unless :math:\mathrm{errno} > 0.

If :math:\mathrm{compz} = \texttt{'N'}, :math:\mathrm{z} is not referenced.

.. _f08ju-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{compz}.

Constraint: :math:\mathrm{compz} = \texttt{'N'}, :math:\texttt{'V'} or :math:\texttt{'I'}.

(errno :math:-2)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

(errno :math:i > 0\text{ and }i\leq n)
The leading minor of order :math:\langle\mathit{\boldsymbol{value}}\rangle is not positive definite and the Cholesky factorization of :math:T could not be completed. Hence :math:T itself is not positive definite.

(errno :math:i > n)
The algorithm to compute the singular values of the Cholesky factor :math:B failed to converge; :math:\langle\mathit{\boldsymbol{value}}\rangle off-diagonal elements did not converge to zero.

.. _f08ju-py2-py-notes:

**Notes**
zpteqr computes all the eigenvalues and, optionally, all the eigenvectors of a real symmetric positive definite tridiagonal matrix :math:T. In other words, it can compute the spectral factorization of :math:T as

.. math::
T = Z\Lambda Z^\mathrm{T}\text{,}

where :math:\Lambda is a diagonal matrix whose diagonal elements are the eigenvalues :math:\lambda_i, and :math:Z is the orthogonal matrix whose columns are the eigenvectors :math:z_i.
Thus

.. math::
Tz_i = \lambda_iz_i\text{, }\quad i = 1,2,\ldots,n\text{.}

The function stores the real orthogonal matrix :math:Z in a complex array, so that it may be used to compute all the eigenvalues and eigenvectors of a complex Hermitian positive definite matrix :math:A which has been reduced to tridiagonal form :math:T:

.. math::
\begin{array}{ll}A& = QTQ^\mathrm{H}\text{, where }Q\text{ is unitary}\\& = \left(QZ\right)\Lambda \left(QZ\right)^\mathrm{H}\text{.}\end{array}

In this case, the matrix :math:Q must be formed explicitly and passed to zpteqr, which must be called with :math:\mathrm{compz} = \texttt{'V'}.
The functions which must be called to perform the reduction to tridiagonal form and form :math:Q are:

+---------------------------+-----------------------------------------------------------+
|full matrix                |:meth:zhetrd and :meth:zungtr                          |
+---------------------------+-----------------------------------------------------------+
|full matrix, packed storage|:meth:zhptrd and :meth:zupgtr                          |
+---------------------------+-----------------------------------------------------------+
|band matrix                |:meth:zhbtrd with :math:{\textit{vect}} = \texttt{'V'}.|
+---------------------------+-----------------------------------------------------------+

zpteqr first factorizes :math:T as :math:LDL^\mathrm{H} where :math:L is unit lower bidiagonal and :math:D is diagonal.
It forms the bidiagonal matrix :math:B = LD^{{\frac{1}{2}}}, and then calls :meth:zbdsqr to compute the singular values of :math:B which are the same as the eigenvalues of :math:T.
The method used by the function allows high relative accuracy to be achieved in the small eigenvalues of :math:T.
The eigenvectors are normalized so that :math:\left\lVert z_i\right\rVert_2 = 1, but are determined only to within a complex factor of absolute value :math:1.

.. _f08ju-py2-py-references:

**References**
Barlow, J and Demmel, J W, 1990, Computing accurate eigensystems of scaled diagonally dominant matrices, SIAM J. Numer. Anal. (27), 762--791
"""
raise NotImplementedError

[docs]def zstedc(compz, d, e, z):
r"""
zstedc computes all the eigenvalues and, optionally, all the eigenvectors of a real :math:n\times n symmetric tridiagonal matrix, or of a complex full or banded Hermitian matrix which has been reduced to tridiagonal form.

.. _f08jv-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08jvf.html

.. _f08jv-py2-py-parameters:

**Parameters**
**compz** : str, length 1
Indicates whether the eigenvectors are to be computed.

:math:\mathrm{compz} = \texttt{'N'}

Only the eigenvalues are computed (and the array :math:\mathrm{z} is not referenced).

:math:\mathrm{compz} = \texttt{'V'}

The eigenvalues and eigenvectors of :math:A are computed (and the array :math:\mathrm{z} must contain the matrix :math:Q on entry).

:math:\mathrm{compz} = \texttt{'I'}

The eigenvalues and eigenvectors of :math:T are computed (and the array :math:\mathrm{z} is initialized by the function).

**d** : float, array-like, shape :math:\left(n\right)
The diagonal elements of the tridiagonal matrix.

**e** : float, array-like, shape :math:\left(\max\left(1,{n-1}\right)\right)
The subdiagonal elements of the tridiagonal matrix.

**z** : complex, array-like, shape :math:\left(:, :\right)
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\mathrm{compz}\text{ in } (\texttt{'V'}, \texttt{'I'}): :math:n; otherwise: :math:1.

Note: the required extent for this argument in dimension 2 is determined as follows: if :math:\mathrm{compz}\text{ in } (\texttt{'V'}, \texttt{'I'}): :math:n; otherwise: :math:1.

If :math:\mathrm{compz} = \texttt{'V'}, :math:\mathrm{z} must contain the unitary matrix :math:Q used in the reduction to tridiagonal form.

**Returns**
**d** : float, ndarray, shape :math:\left(n\right)
If no exception or warning is raised, the eigenvalues in ascending order.

**e** : float, ndarray, shape :math:\left(\max\left(1,{n-1}\right)\right)
:math:\mathrm{e} is overwritten.

**z** : complex, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{compz} = \texttt{'V'}, :math:\mathrm{z} contains the orthonormal eigenvectors of the original Hermitian matrix :math:A, and if :math:\mathrm{compz} = \texttt{'I'}, :math:\mathrm{z} contains the orthonormal eigenvectors of the symmetric tridiagonal matrix :math:T.

If :math:\mathrm{compz} = \texttt{'N'}, :math:\mathrm{z} is not referenced.

.. _f08jv-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{compz}.

Constraint: :math:\mathrm{compz} = \texttt{'N'}, :math:\texttt{'V'} or :math:\texttt{'I'}.

(errno :math:-2)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

(errno :math:i > 0)
The algorithm failed to compute an eigenvalue while working on the submatrix lying in rows and columns :math:\langle\mathit{\boldsymbol{value}}\rangle/\left(n+1\right) through :math:\mathrm{mod}\left(\langle\mathit{\boldsymbol{value}}\rangle, {n+1}\right).

.. _f08jv-py2-py-notes:

**Notes**
zstedc computes all the eigenvalues and, optionally, the eigenvectors of a real symmetric tridiagonal matrix :math:T.
That is, the function computes the spectral factorization of :math:T given by

.. math::
T = Z\Lambda Z^\mathrm{T}\text{,}

where :math:\Lambda is a diagonal matrix whose diagonal elements are the eigenvalues, :math:\lambda_i, of :math:T and :math:Z is an orthogonal matrix whose columns are the eigenvectors, :math:z_i, of :math:T.
Thus

.. math::
Tz_i = \lambda_iz_i\text{, }\quad i = 1,2,\ldots,n\text{.}

The function may also be used to compute all the eigenvalues and eigenvectors of a complex full, or banded, Hermitian matrix :math:A which has been reduced to real tridiagonal form :math:T as

.. math::
A = {QTQ^\mathrm{H}}\text{,}

where :math:Q is unitary.
The spectral factorization of :math:A is then given by

.. math::
A = \left(QZ\right)\Lambda \left(QZ\right)^\mathrm{H}\text{.}

In this case :math:Q must be formed explicitly and passed to zstedc in the array :math:\mathrm{z}, and the function called with :math:\mathrm{compz} = \texttt{'V'}. Functions which may be called to form :math:T and :math:Q are

+---------------------------+-----------------------------------------------------------+
|full matrix                |:meth:zhetrd and :meth:zungtr                          |
+---------------------------+-----------------------------------------------------------+
|full matrix, packed storage|:meth:zhptrd and :meth:zupgtr                          |
+---------------------------+-----------------------------------------------------------+
|band matrix                |:meth:zhbtrd, with :math:{\textit{vect}} = \texttt{'V'}|
+---------------------------+-----------------------------------------------------------+

When only eigenvalues are required then this function calls :meth:dsterf to compute the eigenvalues of the tridiagonal matrix :math:T, but when eigenvectors of :math:T are also required and the matrix is not too small, then a divide and conquer method is used, which can be much faster than :meth:zsteqr, although more storage is required.

.. _f08jv-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 zstein(d, e, m, w, iblock, isplit):
r"""
zstein computes the eigenvectors of a real symmetric tridiagonal matrix corresponding to specified eigenvalues, by inverse iteration, storing the eigenvectors in a complex array.

.. _f08jx-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08jxf.html

.. _f08jx-py2-py-parameters:

**Parameters**
**d** : float, array-like, shape :math:\left(n\right)
The diagonal elements of the tridiagonal matrix :math:T.

**e** : float, array-like, shape :math:\left(n-1\right)
The off-diagonal elements of the tridiagonal matrix :math:T.

**m** : int
:math:m, the number of eigenvectors to be returned.

**w** : float, array-like, shape :math:\left(n\right)
The eigenvalues of the tridiagonal matrix :math:T stored in :math:\mathrm{w} to :math:\mathrm{w}[m-1], as returned by :meth:dstebz with :math:{\textit{order}} = \texttt{'B'}. Eigenvalues associated with the first sub-matrix must be supplied first, in nondecreasing order; then those associated with the second sub-matrix, again in nondecreasing order; and so on.

**iblock** : int, array-like, shape :math:\left(n\right)
The first :math:m elements must contain the sub-matrix indices associated with the specified eigenvalues, as returned by :meth:dstebz with :math:{\textit{order}} = \texttt{'B'}. If the eigenvalues were not computed by :meth:dstebz with :math:{\textit{order}} = \texttt{'B'}, set :math:\mathrm{iblock}[\textit{i}-1] to :math:1, for :math:\textit{i} = 1,2,\ldots,m.

**isplit** : int, array-like, shape :math:\left(n\right)
The points at which :math:T breaks up into sub-matrices, as returned by :meth:dstebz with :math:{\textit{order}} = \texttt{'B'}. If the eigenvalues were not computed by :meth:dstebz with :math:{\textit{order}} = \texttt{'B'}, set :math:\mathrm{isplit} to :math:\textit{n}.

**Returns**
**z** : complex, ndarray, shape :math:\left(n, \mathrm{m}\right)
The :math:m eigenvectors, stored as columns of :math:Z; the :math:i\ th column corresponds to the :math:i\ th specified eigenvalue, unless :math:\mathrm{errno} > 0 (in which case see :ref:Exceptions <f08jx-py2-py-errors>).

**ifailv** : int, ndarray, shape :math:\left(\mathrm{m}\right)
If :math:\textit{errno} = i > 0, the first :math:i elements of :math:\mathrm{ifailv} contain the indices of any eigenvectors which have failed to converge. The rest of the first :math:\mathrm{m} elements of :math:\mathrm{ifailv} are set to :math:0.

.. _f08jx-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

(errno :math:-4)
On entry, error in parameter :math:\mathrm{m}.

Constraint: :math:0\leq \mathrm{m}\leq n.

(errno -5)
On entry, error in parameter :math:\mathrm{w}.

Constraint: :math:\mathrm{w}[\textit{i}]\leq \mathrm{w}[\textit{i}+1].

(errno -6)
On entry, error in parameter :math:\mathrm{iblock}.

Constraint: :math:\mathrm{iblock}[\textit{i}]\leq \mathrm{iblock}[\textit{i}+1].

**Warns**
**NagAlgorithmicWarning**
(errno :math:i > 0)
:math:\langle\mathit{\boldsymbol{value}}\rangle eigenvectors (as indicated by argument :math:\mathrm{ifailv}) each failed to converge in five iterations. The current iterate after five iterations is stored in the corresponding column of :math:\mathrm{z}.

.. _f08jx-py2-py-notes:

**Notes**
zstein computes the eigenvectors of a real symmetric tridiagonal matrix :math:T corresponding to specified eigenvalues, by inverse iteration (see Jessup and Ipsen (1992)).
It is designed to be used in particular after the specified eigenvalues have been computed by :meth:dstebz with :math:{\textit{order}} = \texttt{'B'}, but may also be used when the eigenvalues have been computed by other functions in submodule lapackeig or submodule :mod:~naginterfaces.library.eigen.

The eigenvectors of :math:T are real, but are stored by this function in a complex array.
If :math:T has been formed by reduction of a full complex Hermitian matrix :math:A to tridiagonal form, then eigenvectors of :math:T may be transformed to (complex) eigenvectors of :math:A by a call to :meth:zunmtr or :meth:zupmtr.

:meth:dstebz determines whether the matrix :math:T splits into block diagonal form:

.. math::
T = \begin{pmatrix}T_1&&&&&\\&T_2&&&&\\&&.&&&\\&&&.&&\\&&&&.&\\&&&&&T_p\end{pmatrix}

and passes details of the block structure to this function in the arrays :math:\mathrm{iblock} and :math:\mathrm{isplit}.
This function can then take advantage of the block structure by performing inverse iteration on each block :math:T_i separately, which is more efficient than using the whole matrix.

.. _f08jx-py2-py-references:

**References**
Golub, G H and Van Loan, C F, 1996, Matrix Computations, (3rd Edition), Johns Hopkins University Press, Baltimore

Jessup, E and Ipsen, I C F, 1992, Improving the accuracy of inverse iteration, SIAM J. Sci. Statist. Comput. (13), 550--572
"""
raise NotImplementedError

[docs]def zstegr(jobz, erange, d, e, vl, vu, il, iu):
r"""
zstegr computes selected eigenvalues and, optionally, the corresponding eigenvectors of a real :math:n\times n symmetric tridiagonal matrix.

.. _f08jy-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08jyf.html

.. _f08jy-py2-py-parameters:

**Parameters**
**jobz** : str, length 1
Indicates whether eigenvectors are computed.

:math:\mathrm{jobz} = \texttt{'N'}

Only eigenvalues are computed.

:math:\mathrm{jobz} = \texttt{'V'}

Eigenvalues and eigenvectors are computed.

**erange** : str, length 1
Indicates which eigenvalues should be returned.

:math:\mathrm{erange} = \texttt{'A'}

All eigenvalues will be found.

:math:\mathrm{erange} = \texttt{'V'}

All eigenvalues in the half-open interval :math:\left(\mathrm{vl}, \mathrm{vu}\right] will be found.

:math:\mathrm{erange} = \texttt{'I'}

The :math:\mathrm{il}\ th through :math:\mathrm{iu}\ th eigenvectors will be found.

**d** : float, array-like, shape :math:\left(n\right)
The :math:n diagonal elements of the tridiagonal matrix :math:T.

**e** : float, array-like, shape :math:\left(n\right)
:math:\mathrm{e} to :math:\mathrm{e}[n-2] are the subdiagonal elements of the tridiagonal matrix :math:T. :math:\mathrm{e}[n-1] need not be set.

**vl** : float
If :math:\mathrm{erange} = \texttt{'V'}, :math:\mathrm{vl} and :math:\mathrm{vu} contain the lower and upper bounds respectively of the interval to be searched for eigenvalues.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'I'}, :math:\mathrm{vl} and :math:\mathrm{vu} are not referenced.

**vu** : float
If :math:\mathrm{erange} = \texttt{'V'}, :math:\mathrm{vl} and :math:\mathrm{vu} contain the lower and upper bounds respectively of the interval to be searched for eigenvalues.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'I'}, :math:\mathrm{vl} and :math:\mathrm{vu} are not referenced.

**il** : int
If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{il} and :math:\mathrm{iu} specify the indices (in ascending order) of the smallest and largest eigenvalues to be returned, respectively.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}, :math:\mathrm{il} and :math:\mathrm{iu} are not referenced.

**iu** : int
If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{il} and :math:\mathrm{iu} specify the indices (in ascending order) of the smallest and largest eigenvalues to be returned, respectively.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}, :math:\mathrm{il} and :math:\mathrm{iu} are not referenced.

**Returns**
**d** : float, ndarray, shape :math:\left(n\right)
:math:\mathrm{d} is overwritten.

**e** : float, ndarray, shape :math:\left(n\right)
:math:\mathrm{e} is overwritten.

**m** : int
The total number of eigenvalues found. :math:0\leq \mathrm{m}\leq n.

If :math:\mathrm{erange} = \texttt{'A'}, :math:\mathrm{m} = n.

If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{m} = \mathrm{iu}-\mathrm{il}+1.

**w** : float, ndarray, shape :math:\left(n\right)
The eigenvalues in ascending order.

**z** : complex, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobz} = \texttt{'V'}, then if no exception or warning is raised, the columns of :math:\mathrm{z} contain the orthonormal eigenvectors of the matrix :math:T, with the :math:i\ th column of :math:Z holding the eigenvector associated with :math:\mathrm{w}[i-1].

If :math:\mathrm{jobz} = \texttt{'N'}, :math:\mathrm{z} is not referenced.

**Note:** you must ensure that at least :math:\mathrm{max}\left(1, \mathrm{m}\right) columns are supplied in the array :math:\mathrm{z}; if :math:\mathrm{erange} = \texttt{'V'}, the exact value of :math:\mathrm{m} is not known in advance and an upper bound of at least :math:\textit{n} must be used.

**isuppz** : int, ndarray, shape :math:\left(:\right)
The support of the eigenvectors in :math:Z, i.e., the indices indicating the nonzero elements in :math:Z. The :math:i\ th eigenvector is nonzero only in elements :math:\mathrm{isuppz}[2\times i-2] through :math:\mathrm{isuppz}[2\times i-1].

.. _f08jy-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{jobz}.

Constraint: :math:\mathrm{jobz} = \texttt{'N'} or :math:\texttt{'V'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{erange}.

Constraint: :math:\mathrm{erange} = \texttt{'A'}, :math:\texttt{'V'} or :math:\texttt{'I'}.

(errno :math:-3)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

(errno :math:-7)
On entry, error in parameter :math:\mathrm{vu}.

Constraint: :math:\mathrm{vl} < \mathrm{vu}.

(errno :math:-9)
On entry, error in parameter :math:\mathrm{iu}.

Constraint: :math:1\leq \mathrm{il}\leq \mathrm{iu}\leq n.

(errno :math:-9)
On entry, error in parameter :math:\mathrm{iu}.

Constraint: :math:\mathrm{il} = 1 and :math:\mathrm{iu} = 0.

(errno :math:\left(i > 0\right)\text{ and }\left(i = 1\right))
The :math:\mathrm{dqds} algorithm failed to converge.

(errno :math:\left(i > 0\right)\text{ and }\left(i = 2\right))
Inverse iteration failed to converge.

.. _f08jy-py2-py-notes:

**Notes**
zstegr computes selected eigenvalues and, optionally, the corresponding eigenvectors, of a real symmetric tridiagonal matrix :math:T.
That is, the function computes the (partial) spectral factorization of :math:T given by

.. math::
Z\Lambda Z^\mathrm{T}\text{,}

where :math:\Lambda is a diagonal matrix whose diagonal elements are the selected eigenvalues, :math:\lambda_i, of :math:T and :math:Z is an orthogonal matrix whose columns are the corresponding eigenvectors, :math:z_i, of :math:T.
Thus

.. math::
Tz_i = \lambda_iz_i\text{, }\quad i = 1,2,\ldots,m

where :math:m is the number of selected eigenvectors computed.

The function stores the real orthogonal matrix :math:Z in a complex array, so that it may also be used to compute selected eigenvalues and the corresponding eigenvectors of a complex Hermitian matrix :math:A which has been reduced to tridiagonal form :math:T:

.. math::
\left(QZ\right)\Lambda \left(QZ\right)^\mathrm{H}\text{, where }Q\text{ is unitary.}

In this case, the matrix :math:Q must be explicitly applied to the output matrix :math:Z.
The functions which must be called to perform the reduction to tridiagonal form and apply :math:Q are:

+---------------------------+---------------------------------------------------------------------------------------------------------------------+
|full matrix                |:meth:zhetrd and :meth:zunmtr                                                                                    |
+---------------------------+---------------------------------------------------------------------------------------------------------------------+
|full matrix, packed storage|:meth:zhptrd and :meth:zupmtr                                                                                    |
+---------------------------+---------------------------------------------------------------------------------------------------------------------+
|band matrix                |:meth:zhbtrd with :math:{\textit{vect}} = \texttt{'V'} and :meth:blas.zgemm <naginterfaces.library.blas.zgemm>.|
+---------------------------+---------------------------------------------------------------------------------------------------------------------+

This function uses the dqds and the Relatively Robust Representation algorithms to compute the eigenvalues and eigenvectors respectively; see for example Parlett and Dhillon (2000) and Dhillon and Parlett (2004) for further details. zstegr can usually compute all the eigenvalues and eigenvectors in :math:O\left(n^2\right) floating-point operations and so, for large matrices, is often considerably faster than the other symmetric tridiagonal functions in this module when all the eigenvectors are required, particularly so compared to those functions that are based on the :math:QR algorithm.

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

Barlow, J and Demmel, J W, 1990, Computing accurate eigensystems of scaled diagonally dominant matrices, SIAM J. Numer. Anal. (27), 762--791

Dhillon, I S and Parlett, B N, 2004, Orthogonal eigenvectors and relative gaps, SIAM J. Appl. Math. (25), 858--899

Parlett, B N and Dhillon, I S, 2000, Relatively robust representations of symmetric tridiagonals, Linear Algebra Appl. (309), 121--151
"""
raise NotImplementedError

[docs]def dgelss(a, b, rcond):
r"""
dgelss computes the minimum norm solution to a real linear least squares problem

.. math::
\mathrm{min}_x\left\lVert b-Ax\right\rVert_2\text{.}

.. _f08ka-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08kaf.html

.. _f08ka-py2-py-parameters:

**Parameters**
**a** : float, array-like, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:A.

**b** : float, array-like, shape :math:\left(\max\left(m,n\right), \textit{nrhs}\right)
The :math:m\times r right-hand side matrix :math:B.

**rcond** : float
Used to determine the effective rank of :math:A. Singular values :math:\mathrm{s}[i-1]\leq \mathrm{rcond}\times \mathrm{s} are treated as zero. If :math:\mathrm{rcond} < 0, machine precision is used instead.

**Returns**
**a** : float, ndarray, shape :math:\left(m, n\right)
The first :math:\mathrm{min}\left(m, n\right) rows of :math:A are overwritten with its right singular vectors, stored row-wise.

**b** : float, ndarray, shape :math:\left(\max\left(m,n\right), \textit{nrhs}\right)
:math:\mathrm{b} is overwritten by the :math:n\times r solution matrix :math:X. If :math:m\geq n and :math:\mathrm{rank} = n, the residual sum of squares for the solution in the :math:i\ th column is given by the sum of squares of elements :math:n+1,\ldots,m in that column.

**s** : float, ndarray, shape :math:\left(\min\left(m,n\right)\right)
The singular values of :math:A in decreasing order.

**rank** : int
The effective rank of :math:A, i.e., the number of singular values which are greater than :math:\mathrm{rcond}\times \mathrm{s}.

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

(errno :math:-3)
On entry, error in parameter :math:\textit{nrhs}.

Constraint: :math:\textit{nrhs}\geq 0.

(errno :math:i > 0)
The algorithm for computing the SVD failed to converge; :math:\langle\mathit{\boldsymbol{value}}\rangle off-diagonal elements of an intermediate bidiagonal form did not converge to zero.

.. _f08ka-py2-py-notes:

**Notes**
dgelss uses the singular value decomposition (SVD) of :math:A, where :math:A is an :math:m\times n matrix which may be rank-deficient.

Several right-hand side vectors :math:b and solution vectors :math:x can be handled in a single call; they are stored as the columns of the :math:m\times r right-hand side matrix :math:B and the :math:n\times r solution matrix :math:X.

The effective rank of :math:A is determined by treating as zero those singular values which are less than :math:\mathrm{rcond} times the largest singular value.

.. _f08ka-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 dgesvd(jobu, jobvt, a):
r"""
dgesvd computes the singular value decomposition (SVD) of a real :math:m\times n matrix :math:A, optionally computing the left and/or right singular vectors.

.. _f08kb-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08kbf.html

.. _f08kb-py2-py-parameters:

**Parameters**
**jobu** : str, length 1
Specifies options for computing all or part of the matrix :math:U.

:math:\mathrm{jobu} = \texttt{'A'}

All :math:m columns of :math:U are returned in array :math:\mathrm{u}.

:math:\mathrm{jobu} = \texttt{'S'}

The first :math:\mathrm{min}\left(m, n\right) columns of :math:U (the left singular vectors) are returned in the array :math:\mathrm{u}.

:math:\mathrm{jobu} = \texttt{'O'}

The first :math:\mathrm{min}\left(m, n\right) columns of :math:U (the left singular vectors) are overwritten on the array :math:\mathrm{a}.

:math:\mathrm{jobu} = \texttt{'N'}

No columns of :math:U (no left singular vectors) are computed.

**jobvt** : str, length 1
Specifies options for computing all or part of the matrix :math:V^\mathrm{T}.

:math:\mathrm{jobvt} = \texttt{'A'}

All :math:n rows of :math:V^\mathrm{T} are returned in the array :math:\mathrm{vt}.

:math:\mathrm{jobvt} = \texttt{'S'}

The first :math:\mathrm{min}\left(m, n\right) rows of :math:V^\mathrm{T} (the right singular vectors) are returned in the array :math:\mathrm{vt}.

:math:\mathrm{jobvt} = \texttt{'O'}

The first :math:\mathrm{min}\left(m, n\right) rows of :math:V^\mathrm{T} (the right singular vectors) are overwritten on the array :math:\mathrm{a}.

:math:\mathrm{jobvt} = \texttt{'N'}

No rows of :math:V^\mathrm{T} (no right singular vectors) are computed.

**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)
If :math:\mathrm{jobu} = \texttt{'O'}, :math:\mathrm{a} is overwritten with the first :math:\mathrm{min}\left(m, n\right) columns of :math:U (the left singular vectors, stored column-wise).

If :math:\mathrm{jobvt} = \texttt{'O'}, :math:\mathrm{a} is overwritten with the first :math:\mathrm{min}\left(m, n\right) rows of :math:V^\mathrm{T} (the right singular vectors, stored row-wise).

If :math:\mathrm{jobu} \neq \texttt{'O'} and :math:\mathrm{jobvt} \neq \texttt{'O'}, the contents of :math:\mathrm{a} are destroyed.

**s** : float, ndarray, shape :math:\left(\min\left(m,n\right)\right)
The singular values of :math:A, sorted so that :math:\mathrm{s}[i-1]\geq \mathrm{s}[i].

**u** : float, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobu} = \texttt{'A'}, :math:\mathrm{u} contains the :math:m\times m orthogonal matrix :math:U.

If :math:\mathrm{jobu} = \texttt{'S'}, :math:\mathrm{u} contains the first :math:\mathrm{min}\left(m, n\right) columns of :math:U (the left singular vectors, stored column-wise).

If :math:\mathrm{jobu} = \texttt{'N'} or :math:\texttt{'O'}, :math:\mathrm{u} is not referenced.

**vt** : float, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobvt} = \texttt{'A'}, :math:\mathrm{vt} contains the :math:n\times n orthogonal matrix :math:V^T.

If :math:\mathrm{jobvt} = \texttt{'S'}, :math:\mathrm{vt} contains the first :math:\mathrm{min}\left(m, n\right) rows of :math:V^\mathrm{T} (the right singular vectors, stored row-wise).

If :math:\mathrm{jobvt} = \texttt{'N'} or :math:\texttt{'O'}, :math:\mathrm{vt} is not referenced.

**workb** : float, ndarray, shape :math:\left(\min\left(m,n\right)\right)
If :math:\mathrm{errno} > 0, :math:\mathrm{workb}[1:\mathrm{min}\left(m, n\right)] contains the unconverged superdiagonal elements of an upper bidiagonal matrix :math:B whose diagonal is in :math:\mathrm{s} (not necessarily sorted). :math:B satisfies :math:A = UBV^\mathrm{T}, so it has the same singular values as :math:A, and singular vectors related by :math:U and :math:V^\mathrm{T}.

.. _f08kb-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{jobu}.

Constraint: :math:\mathrm{jobu} = \texttt{'A'}, :math:\texttt{'S'}, :math:\texttt{'O'} or :math:\texttt{'N'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{jobvt}.

Constraint: :math:\mathrm{jobvt} = \texttt{'A'}, :math:\texttt{'S'}, :math:\texttt{'O'} or :math:\texttt{'N'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{jobvt}.

Constraint: :math:\mathrm{jobvt} \neq \texttt{'O'} or :math:\mathrm{jobu} \neq \texttt{'O'}.

(errno :math:-3)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

(errno :math:-4)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

(errno :math:i > 0)
If dgesvd did not converge, :math:\textit{errno} specifies how many superdiagonals of an intermediate bidiagonal form did not converge to zero.

.. _f08kb-py2-py-notes:

**Notes**
The SVD is written as

.. math::
A = U\Sigma V^\mathrm{T}\text{,}

where :math:\Sigma is an :math:m\times n matrix which is zero except for its :math:\mathrm{min}\left(m, n\right) diagonal elements, :math:U is an :math:m\times m orthogonal matrix, and :math:V is an :math:n\times n orthogonal matrix.
The diagonal elements of :math:\Sigma are the singular values of :math:A; they are real and non-negative, and are returned in descending order.
The first :math:\mathrm{min}\left(m, n\right) columns of :math:U and :math:V are the left and right singular vectors of :math:A.

Note that the function returns :math:V^\mathrm{T}, not :math:V.

.. _f08kb-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 dgelsd(a, b, rcond):
r"""
dgelsd computes the minimum norm solution to a real linear least squares problem

.. math::
\mathrm{min}_x\left\lVert b-Ax\right\rVert_2\text{.}

.. _f08kc-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08kcf.html

.. _f08kc-py2-py-parameters:

**Parameters**
**a** : float, array-like, shape :math:\left(m, n\right)
The :math:m\times n coefficient matrix :math:A.

**b** : float, array-like, shape :math:\left(\max\left(m,n\right), \textit{nrhs}\right)
The :math:m\times r right-hand side matrix :math:B.

**rcond** : float
Used to determine the effective rank of :math:A. Singular values :math:\mathrm{s}[i-1]\leq \mathrm{rcond}\times \mathrm{s} are treated as zero. If :math:\mathrm{rcond} < 0, machine precision is used instead.

**Returns**
**a** : float, ndarray, shape :math:\left(m, n\right)
The contents of :math:\mathrm{a} are destroyed.

**b** : float, ndarray, shape :math:\left(\max\left(m,n\right), \textit{nrhs}\right)
:math:\mathrm{b} is overwritten by the :math:n\times r solution matrix :math:X. If :math:m\geq n and :math:\mathrm{rank} = n, the residual sum of squares for the solution in the :math:i\ th column is given by the sum of squares of elements :math:n+1,\ldots,m in that column.

**s** : float, ndarray, shape :math:\left(\min\left(m,n\right)\right)
The singular values of :math:A in decreasing order.

**rank** : int
The effective rank of :math:A, i.e., the number of singular values which are greater than :math:\mathrm{rcond}\times \mathrm{s}.

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

(errno :math:-3)
On entry, error in parameter :math:\textit{nrhs}.

Constraint: :math:\textit{nrhs}\geq 0.

(errno :math:i > 0)
The algorithm for computing the SVD failed to converge; :math:\langle\mathit{\boldsymbol{value}}\rangle off-diagonal elements of an intermediate bidiagonal form did not converge to zero.

.. _f08kc-py2-py-notes:

**Notes**
dgelsd uses the singular value decomposition (SVD) of :math:A, where :math:A is a real :math:m\times n matrix which may be rank-deficient.

Several right-hand side vectors :math:b and solution vectors :math:x can be handled in a single call; they are stored as the columns of the :math:m\times r right-hand side matrix :math:B and the :math:n\times r solution matrix :math:X.

The problem is solved in three steps:

(1) reduce the coefficient matrix :math:A to bidiagonal form with Householder transformations, reducing the original problem into a 'bidiagonal least squares problem' (BLS);

(#) solve the BLS using a divide-and-conquer approach;

(#) apply back all the Householder transformations to solve the original least squares problem.

The effective rank of :math:A is determined by treating as zero those singular values which are less than :math:\mathrm{rcond} times the largest singular value.

.. _f08kc-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 dgesdd(jobz, a):
r"""
dgesdd computes the singular value decomposition (SVD) of a real :math:m\times n matrix :math:A, optionally computing the left and/or right singular vectors, by using a divide-and-conquer method.

.. _f08kd-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08kdf.html

.. _f08kd-py2-py-parameters:

**Parameters**
**jobz** : str, length 1
Specifies options for computing all or part of the matrix :math:U.

:math:\mathrm{jobz} = \texttt{'A'}

All :math:m columns of :math:U and all :math:n rows of :math:V^\mathrm{T} are returned in the arrays :math:\mathrm{u} and :math:\mathrm{vt}.

:math:\mathrm{jobz} = \texttt{'S'}

The first :math:\mathrm{min}\left(m, n\right) columns of :math:U and the first :math:\mathrm{min}\left(m, n\right) rows of :math:V^\mathrm{T} are returned in the arrays :math:\mathrm{u} and :math:\mathrm{vt}.

:math:\mathrm{jobz} = \texttt{'O'}

If :math:m\geq n, the first :math:n columns of :math:U are overwritten on the array :math:\mathrm{a} and all rows of :math:V^\mathrm{T} are returned in the array :math:\mathrm{vt}. Otherwise, all columns of :math:U are returned in the array :math:\mathrm{u} and the first :math:m rows of :math:V^\mathrm{T} are overwritten in the array :math:\mathrm{vt}.

:math:\mathrm{jobz} = \texttt{'N'}

No columns of :math:U or rows of :math:V^\mathrm{T} are computed.

**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)
If :math:\mathrm{jobz} = \texttt{'O'}, :math:\mathrm{a} is overwritten with the first :math:n columns of :math:U (the left singular vectors, stored column-wise) if :math:m\geq n; :math:\mathrm{a} is overwritten with the first :math:m rows of :math:V^\mathrm{T} (the right singular vectors, stored row-wise) otherwise.

If :math:\mathrm{jobz} \neq \texttt{'O'}, the contents of :math:\mathrm{a} are destroyed.

**s** : float, ndarray, shape :math:\left(\min\left(m,n\right)\right)
The singular values of :math:A, sorted so that :math:\mathrm{s}[i-1]\geq \mathrm{s}[i].

**u** : float, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobz} = \texttt{'A'} or :math:\mathrm{jobz} = \texttt{'O'} and :math:m < n, :math:\mathrm{u} contains the :math:m\times m orthogonal matrix :math:U.

If :math:\mathrm{jobz} = \texttt{'S'}, :math:\mathrm{u} contains the first :math:\mathrm{min}\left(m, n\right) columns of :math:U (the left singular vectors, stored column-wise).

If :math:\mathrm{jobz} = \texttt{'O'} and :math:m\geq n, or :math:\mathrm{jobz} = \texttt{'N'}, :math:\mathrm{u} is not referenced.

**vt** : float, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobz} = \texttt{'A'} or :math:\mathrm{jobz} = \texttt{'O'} and :math:m\geq n, :math:\mathrm{vt} contains the :math:n\times n orthogonal matrix :math:V^T.

If :math:\mathrm{jobz} = \texttt{'S'}, :math:\mathrm{vt} contains the first :math:\mathrm{min}\left(m, n\right) rows of :math:V^\mathrm{T} (the right singular vectors, stored row-wise).

If :math:\mathrm{jobz} = \texttt{'O'} and :math:m < n, or :math:\mathrm{jobz} = \texttt{'N'}, :math:\mathrm{vt} is not referenced.

.. _f08kd-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{jobz}.

Constraint: :math:\mathrm{jobz} = \texttt{'A'}, :math:\texttt{'S'}, :math:\texttt{'O'} or :math:\texttt{'N'}.

(errno :math:-2)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

(errno :math:-3)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

(errno :math:i > 0)
dgesdd did not converge, the updating process failed.

.. _f08kd-py2-py-notes:

**Notes**
The SVD is written as

.. math::
A = U\Sigma V^\mathrm{T}\text{,}

where :math:\Sigma is an :math:m\times n matrix which is zero except for its :math:\mathrm{min}\left(m, n\right) diagonal elements, :math:U is an :math:m\times m orthogonal matrix, and :math:V is an :math:n\times n orthogonal matrix.
The diagonal elements of :math:\Sigma are the singular values of :math:A; they are real and non-negative, and are returned in descending order.
The first :math:\mathrm{min}\left(m, n\right) columns of :math:U and :math:V are the left and right singular vectors of :math:A.

Note that the function returns :math:V^\mathrm{T}, not :math:V.

.. _f08kd-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 dgebrd(a):
r"""
dgebrd reduces a real :math:m\times n matrix to bidiagonal form.

.. _f08ke-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08kef.html

.. _f08ke-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)
If :math:m\geq n, the diagonal and first superdiagonal are overwritten by the upper bidiagonal matrix :math:B, elements below the diagonal are overwritten by details of the orthogonal matrix :math:Q and elements above the first superdiagonal are overwritten by details of the orthogonal matrix :math:P.

If :math:m < n, the diagonal and first subdiagonal are overwritten by the lower bidiagonal matrix :math:B, elements below the first subdiagonal are overwritten by details of the orthogonal matrix :math:Q and elements above the diagonal are overwritten by details of the orthogonal matrix :math:P.

**d** : float, ndarray, shape :math:\left(\min\left(m,n\right)\right)
The diagonal elements of the bidiagonal matrix :math:B.

**e** : float, ndarray, shape :math:\left(\min\left(m,n\right)-1\right)
The off-diagonal elements of the bidiagonal matrix :math:B.

**tauq** : float, ndarray, shape :math:\left(\min\left(m,n\right)\right)
Further details of the orthogonal matrix :math:Q.

**taup** : float, ndarray, shape :math:\left(\min\left(m,n\right)\right)
Further details of the orthogonal matrix :math:P.

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

.. _f08ke-py2-py-notes:

**Notes**
dgebrd reduces a real :math:m\times n matrix :math:A to bidiagonal form :math:B by an orthogonal transformation: :math:A = QBP^\mathrm{T}, where :math:Q and :math:P^\mathrm{T} are orthogonal matrices of order :math:m and :math:n respectively.

If :math:m\geq n, the reduction is given by:

.. math::
A = Q\begin{pmatrix}B_1\\0\end{pmatrix}P^\mathrm{T} = Q_1B_1P^\mathrm{T}\text{,}

where :math:B_1 is an :math:n\times n upper bidiagonal matrix and :math:Q_1 consists of the first :math:n columns of :math:Q.

If :math:m < n, the reduction is given by

.. math::
A = Q\begin{pmatrix}B_1&0\end{pmatrix}P^\mathrm{T} = QB_1P_1^\mathrm{T}\text{,}

where :math:B_1 is an :math:m\times m lower bidiagonal matrix and :math:P_1^\mathrm{T} consists of the first :math:m rows of :math:P^\mathrm{T}.

The orthogonal matrices :math:Q and :math:P are not formed explicitly but are represented as products of elementary reflectors (see the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html>__ for details). Functions are provided to work with :math:Q and :math:P in this representation (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08kef.html#fcomments>__).

.. _f08ke-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 dorgbr(vect, k, a, tau):
r"""
dorgbr generates one of the real orthogonal matrices :math:Q or :math:P^\mathrm{T} which were determined by :meth:dgebrd when reducing a real matrix to bidiagonal form.

.. _f08kf-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08kff.html

.. _f08kf-py2-py-parameters:

**Parameters**
**vect** : str, length 1
Indicates whether the orthogonal matrix :math:Q or :math:P^\mathrm{T} is generated.

:math:\mathrm{vect} = \texttt{'Q'}

:math:Q is generated.

:math:\mathrm{vect} = \texttt{'P'}

:math:P^\mathrm{T} is generated.

**k** : int
If :math:\mathrm{vect} = \texttt{'Q'}, the number of columns in the original matrix :math:A.

If :math:\mathrm{vect} = \texttt{'P'}, the number of rows in the original matrix :math:A.

**a** : float, array-like, shape :math:\left(m, n\right)
Details of the vectors which define the elementary reflectors, as returned by :meth:dgebrd.

**tau** : float, array-like, shape :math:\left(:\right)
Note: the required length for this argument is determined as follows: if :math:\mathrm{vect}=\texttt{'Q'}: :math:\max\left(1,\min\left(m,\mathrm{k}\right)\right); if :math:\mathrm{vect}=\texttt{'P'}: :math:\max\left(1,\min\left(n,\mathrm{k}\right)\right); otherwise: :math:0.

Further details of the elementary reflectors, as returned by :meth:dgebrd in its argument :math:\textit{tauq} if :math:\mathrm{vect} = \texttt{'Q'}, or in its argument :math:\textit{taup} if :math:\mathrm{vect} = \texttt{'P'}.

**Returns**
**a** : float, ndarray, shape :math:\left(m, n\right)
The orthogonal matrix :math:Q or :math:P^\mathrm{T}, or the leading rows or columns thereof, as specified by :math:\mathrm{vect}, :math:\mathrm{m} and :math:\mathrm{n}.

.. _f08kf-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{vect}.

Constraint: :math:\mathrm{vect} = \texttt{'Q'} or :math:\texttt{'P'}.

(errno :math:-2)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

(errno :math:-3)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

(errno :math:-3)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:m\geq n\geq \mathrm{k}.

(errno :math:-3)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:m = n.

(errno :math:-3)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq m\geq \mathrm{k}.

(errno :math:-3)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n = m.

(errno :math:-4)
On entry, error in parameter :math:\mathrm{k}.

Constraint: :math:\mathrm{k}\geq 0.

.. _f08kf-py2-py-notes:

**Notes**
dorgbr is intended to be used after a call to :meth:dgebrd, which reduces a real rectangular matrix :math:A to bidiagonal form :math:B by an orthogonal transformation: :math:A = QBP^\mathrm{T}. :meth:dgebrd represents the matrices :math:Q and :math:P^\mathrm{T} as products of elementary reflectors.

This function may be used to generate :math:Q or :math:P^\mathrm{T} explicitly as square matrices, or in some cases just the leading columns of :math:Q or the leading rows of :math:P^\mathrm{T}.

The various possibilities are specified by the arguments :math:\mathrm{vect}, :math:\textit{m}, :math:\textit{n} and :math:\mathrm{k}.
The appropriate values to cover the most likely cases are as follows (assuming that :math:A was an :math:m\times n matrix):

(1) To form the full :math:m\times m matrix :math:Q: set :math:\mathrm{vect} = \texttt{'Q'}, :math:n = m and :math:\mathrm{k} = n (note that the array :math:\mathrm{a} must have at least :math:m columns).

(#) If :math:m > n, to form the :math:n leading columns of :math:Q: set :math:\mathrm{vect} = \texttt{'Q'}, and :math:\mathrm{k} = n

(#) To form the full :math:n\times n matrix :math:P^\mathrm{T}: set :math:\mathrm{vect} = \texttt{'P'}, :math:m = n and :math:\mathrm{k} = m (note that the array :math:\mathrm{a} must have at least :math:n rows).

(#) If :math:m < n, to form the :math:m leading rows of :math:P^\mathrm{T}: set :math:\mathrm{vect} = \texttt{'P'} and :math:\mathrm{k} = m

.. _f08kf-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 dormbr(vect, side, trans, k, a, tau, c):
r"""
dormbr multiplies an arbitrary real :math:m\times n matrix :math:C by one of the real orthogonal matrices :math:Q or :math:P which were determined by :meth:dgebrd when reducing a real matrix to bidiagonal form.

.. _f08kg-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08kgf.html

.. _f08kg-py2-py-parameters:

**Parameters**
**vect** : str, length 1
Indicates whether :math:Q or :math:Q^\mathrm{T} or :math:P or :math:P^\mathrm{T} is to be applied to :math:C.

:math:\mathrm{vect} = \texttt{'Q'}

:math:Q or :math:Q^\mathrm{T} is applied to :math:C.

:math:\mathrm{vect} = \texttt{'P'}

:math:P or :math:P^\mathrm{T} is applied to :math:C.

**side** : str, length 1
Indicates how :math:Q or :math:Q^\mathrm{T} or :math:P or :math:P^\mathrm{T} is to be applied to :math:C.

:math:\mathrm{side} = \texttt{'L'}

:math:Q or :math:Q^\mathrm{T} or :math:P or :math:P^\mathrm{T} is applied to :math:C from the left.

:math:\mathrm{side} = \texttt{'R'}

:math:Q or :math:Q^\mathrm{T} or :math:P or :math:P^\mathrm{T} is applied to :math:C from the right.

**trans** : str, length 1
Indicates whether :math:Q or :math:P or :math:Q^\mathrm{T} or :math:P^\mathrm{T} is to be applied to :math:C.

:math:\mathrm{trans} = \texttt{'N'}

:math:Q or :math:P is applied to :math:C.

:math:\mathrm{trans} = \texttt{'T'}

:math:Q^\mathrm{T} or :math:P^\mathrm{T} is applied to :math:C.

**k** : int
If :math:\mathrm{vect} = \texttt{'Q'}, the number of columns in the original matrix :math:A.

If :math:\mathrm{vect} = \texttt{'P'}, the number of rows in the original matrix :math:A.

**a** : float, array-like, shape :math:\left(:, :\right)
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\mathrm{vect}=\texttt{'Q'}: :math:\textit{r}; if :math:\mathrm{vect}=\texttt{'P'}: :math:\min\left(\textit{r},\mathrm{k}\right); otherwise: :math:0.

Note: the required extent for this argument in dimension 2 is determined as follows: if :math:\mathrm{vect}=\texttt{'Q'}: :math:\min\left(\textit{r},\mathrm{k}\right); if :math:\mathrm{vect}=\texttt{'P'}: :math:\textit{r}; otherwise: :math:0.

Details of the vectors which define the elementary reflectors, as returned by :meth:dgebrd.

**tau** : float, array-like, shape :math:\left(\min\left(\textit{r},\mathrm{k}\right)\right)
Further details of the elementary reflectors, as returned by :meth:dgebrd in its argument :math:\textit{tauq} if :math:\mathrm{vect} = \texttt{'Q'}, or in its argument :math:\textit{taup} if :math:\mathrm{vect} = \texttt{'P'}.

**c** : float, array-like, shape :math:\left(m, n\right)
The matrix :math:C.

**Returns**
**c** : float, ndarray, shape :math:\left(m, n\right)
:math:\mathrm{c} is overwritten by :math:QC or :math:Q^\mathrm{T}C or :math:CQ or :math:C^\mathrm{T}Q or :math:PC or :math:P^\mathrm{T}C or :math:CP or :math:C^\mathrm{T}P as specified by :math:\mathrm{vect}, :math:\mathrm{side} and :math:\mathrm{trans}.

.. _f08kg-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{vect}.

Constraint: :math:\mathrm{vect} = \texttt{'Q'} or :math:\texttt{'P'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{side}.

Constraint: :math:\mathrm{side} = \texttt{'L'} or :math:\texttt{'R'}.

(errno :math:-3)
On entry, error in parameter :math:\mathrm{trans}.

Constraint: :math:\mathrm{trans} = \texttt{'N'} or :math:\texttt{'T'}.

(errno :math:-4)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

(errno :math:-5)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

(errno :math:-6)
On entry, error in parameter :math:\mathrm{k}.

Constraint: :math:\mathrm{k}\geq 0.

.. _f08kg-py2-py-notes:

**Notes**
dormbr is intended to be used after a call to :meth:dgebrd, which reduces a real rectangular matrix :math:A to bidiagonal form :math:B by an orthogonal transformation: :math:A = QBP^\mathrm{T}. :meth:dgebrd represents the matrices :math:Q and :math:P^\mathrm{T} as products of elementary reflectors.

This function may be used to form one of the matrix products

.. math::
QC,Q^\mathrm{T}C,CQ,CQ^\mathrm{T},PC,P^\mathrm{T}C,CP\text{ or }CP^\mathrm{T}\text{,}

overwriting the result on :math:C (which may be any real rectangular matrix).

.. _f08kg-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 dgejsv(joba, jobu, jobv, jobr, jobt, jobp, a):
r"""
dgejsv computes the singular value decomposition (SVD) of a real :math:m\times n matrix :math:A, where :math:m\geq n, and optionally computes the left and/or right singular vectors. dgejsv implements the preconditioned Jacobi SVD of Drmač and Veselić (2008a) and Drmač and Veselić (2008b).
This is the expert driver function that calls :meth:dgesvj after certain preconditioning.
In most cases :meth:dgesvd or :meth:dgesdd, employing fast scaled rotations and de Rijk's pivoting strategy, is sufficient to obtain the SVD of a real matrix.
These are much simpler to use and also handle the case :math:m < n.

.. _f08kh-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08khf.html

.. _f08kh-py2-py-parameters:

**Parameters**
**joba** : str, length 1
Specifies the form of pivoting for the :math:QR factorization stage; whether an estimate of the condition number of the scaled matrix is required; and the form of rank reduction that is performed.

:math:\mathrm{joba} = \texttt{'C'}

The initial :math:QR factorization of the input matrix is performed with column pivoting; no estimate of condition number is computed; and, the rank is reduced by only the underflowed part of the triangular factor :math:R. This option works well (high relative accuracy) if :math:A can be written in the form :math:A = BD, with well-conditioned :math:B and arbitrary diagonal matrix :math:D. The accuracy cannot be spoiled by column scaling. The accuracy of the computed output depends on the condition of :math:B, and the procedure attempts to achieve the best theoretical accuracy.

:math:\mathrm{joba} = \texttt{'E'}

Computation as with :math:\mathrm{joba} = \texttt{'C'} with an additional estimate of the condition number of :math:B. It provides a realistic error bound.

:math:\mathrm{joba} = \texttt{'F'}

The initial :math:QR factorization of the input matrix is performed with full row and column pivoting; no estimate of condition number is computed; and, the rank is reduced by only the underflowed part of the triangular factor :math:R. If :math:A = D_1\times C\times D_2 with ill-conditioned diagonal scalings :math:D_1, :math:D_2, and well-conditioned matrix :math:C, this option gives higher accuracy than the :math:\mathrm{joba} = \texttt{'C'} option. If the structure of the input matrix is not known, and relative accuracy is desirable, then this option is advisable.

:math:\mathrm{joba} = \texttt{'G'}

Computation as with :math:\mathrm{joba} = \texttt{'F'} with an additional estimate of the condition number of :math:B, where :math:A = DB (i.e., :math:B = C\times D_2). If :math:A has heavily weighted rows, then using this condition number gives too pessimistic an error bound.

:math:\mathrm{joba} = \texttt{'A'}

Computation as with :math:\mathrm{joba} = \texttt{'C'} except in the treatment of rank reduction. In this case, small singular values are to be considered as noise and, if found, the matrix is treated as numerically rank deficient. The computed SVD, :math:A = U\Sigma V^\mathrm{T}, is such that the relative residual norm (when comparing against :math:A) is of the order :math:\mathrm{O}\left(m\right)\times \epsilon, where :math:\epsilon is machine precision. This gives the procedure licence to discard (set to zero) all singular values below :math:n\times \epsilon \times \left\lVert A\right\rVert.

:math:\mathrm{joba} = \texttt{'R'}

Similar to :math:\mathrm{joba} = \texttt{'A'}. The rank revealing property of the initial :math:QR factorization is used to reveal (using the upper triangular factor) a gap, :math:\sigma_{{r+1}} < \epsilon \sigma_r, in which case the numerical rank is declared to be :math:r. The SVD is computed with absolute error bounds, but more accurately than with :math:\mathrm{joba} = \texttt{'A'}.

**jobu** : str, length 1
Specifies options for computing the left singular vectors :math:U.

:math:\mathrm{jobu} = \texttt{'U'}

The first :math:n left singular vectors (columns of :math:U) are computed and returned in the array :math:\mathrm{u}.

:math:\mathrm{jobu} = \texttt{'F'}

All :math:m left singular vectors are computed and returned in the array :math:\mathrm{u}.

:math:\mathrm{jobu} = \texttt{'W'}

No left singular vectors are computed, but the array :math:\mathrm{u} (with :math:\textit{ldu}\geq m and second dimension at least :math:\textit{n}) is available as workspace for computing right singular values. See the description of :math:\mathrm{u}.

:math:\mathrm{jobu} = \texttt{'N'}

No left singular vectors are computed. :math:\mathrm{u} is not referenced when :math:\mathrm{jobv} = \texttt{'W'} or :math:\texttt{'N'}.

**jobv** : str, length 1
Specifies options for computing the right singular vectors :math:V.

:math:\mathrm{jobv} = \texttt{'V'}

The :math:n right singular vectors (columns of :math:V) are computed and returned in the array :math:\mathrm{v}; Jacobi rotations are not explicitly accumulated.

:math:\mathrm{jobv} = \texttt{'J'}

The :math:n right singular vectors (columns of :math:V) are computed and returned in the array :math:\mathrm{v}, but they are computed as the product of Jacobi rotations. This option is allowed only if :math:\mathrm{jobu} = \texttt{'U'} or :math:\texttt{'F'}, i.e., in computing the full SVD.

This is equivalent to multiplying the input matrix, on the right, by the matrix :math:V.

:math:\mathrm{jobv} = \texttt{'W'}

No right singular values are computed, but the array :math:\mathrm{v} (with :math:\textit{ldv}\geq n and second dimension at least :math:\textit{n}) is available as workspace for computing left singular values. See the description of :math:\mathrm{v}.

:math:\mathrm{jobv} = \texttt{'N'}

No right singular vectors are computed. :math:\mathrm{v} is not referenced when :math:\mathrm{jobu} = \texttt{'W'} or :math:\texttt{'N'} or :math:\mathrm{jobt} = \texttt{'N'} or :math:m\neq n.

**jobr** : str, length 1
Specifies the conditions under which columns of :math:A are to be set to zero. This effectively specifies a lower limit on the range of singular values; any singular values below this limit are (through column zeroing) set to zero. If :math:A\neq 0 is scaled so that the largest column (in the Euclidean norm) of :math:cA is equal to the square root of the overflow threshold, then :math:\mathrm{jobr} allows the function to kill columns of :math:A whose norm in :math:cA is less than :math:\sqrt{\textit{sfmin}} (for :math:\mathrm{jobr} = \texttt{'R'}), or less than :math:\textit{sfmin}/\epsilon (otherwise). :math:\textit{sfmin} is the safe range parameter, as returned by function :meth:machine.real_safe <naginterfaces.library.machine.real_safe>.

:math:\mathrm{jobr} = \texttt{'N'}

Only set to zero those columns of :math:A for which the norm of corresponding column of :math:cA < \textit{sfmin}/\epsilon, that is, those columns that are effectively zero (to machine precision) anyway. If the condition number of :math:A is greater than the overflow threshold :math:\lambda, where :math:\lambda is the value returned by :meth:machine.real_largest <naginterfaces.library.machine.real_largest>, you are recommended to use function :meth:dgesvj.

:math:\mathrm{jobr} = \texttt{'R'}

Set to zero those columns of :math:A for which the norm of the corresponding column of :math:cA < \sqrt{\textit{sfmin}}. This approximately represents a restricted range for :math:\sigma \left(cA\right) of :math:\left[\sqrt{\textit{sfmin}}, \sqrt{\lambda }\right].

For computing the singular values in the full range from the safe minimum up to the overflow threshold use :meth:dgesvj.

Suggested value: :math:\mathrm{jobr} = \texttt{'R'}.

**jobt** : str, length 1
Specifies, in the case :math:n = m, whether the function is permitted to use the transpose of :math:A for improved efficiency. If the matrix is square, then the procedure may use :math:A^\mathrm{T} if it seems to be better with respect to convergence. If the matrix is not square, :math:\mathrm{jobt} is ignored. The decision is based on two values of entropy over the adjoint orbit of :math:A^\mathrm{T}A. See the descriptions of :math:\textit{work} and :math:\textit{work}.

:math:\mathrm{jobt} = \texttt{'T'}

If :math:n = m, perform an entropy test and, if the test indicates possibly faster convergence of the Jacobi process when using :math:A^\mathrm{T}, then form the transpose :math:A^\mathrm{T}. If :math:A is replaced with :math:A^\mathrm{T}, then the row pivoting is included automatically.

:math:\mathrm{jobt} = \texttt{'N'}

No entropy test and no transposition is performed.

The option :math:\mathrm{jobt} = \texttt{'T'} can be used to compute only the singular values, or the full SVD (:math:U, :math:\Sigma and :math:V).

In the case where only one set of singular vectors (:math:U or :math:V) is required, the caller must still provide both :math:\mathrm{u} and :math:\mathrm{v}, as one of the matrices is used as workspace if the matrix :math:A is transposed.

See the descriptions of :math:\mathrm{u} and :math:\mathrm{v}.

**jobp** : str, length 1
Specifies whether the function should be allowed to introduce structured perturbations to drown denormalized numbers. For details see Drmač and Veselić (2008a) and Drmač and Veselić (2008b). For the sake of simplicity, these perturbations are included only when the full SVD or only the singular values are requested.

:math:\mathrm{jobp} = \texttt{'P'}

Introduce perturbation if :math:A is found to be very badly scaled (introducing denormalized numbers).

:math:\mathrm{jobp} = \texttt{'N'}

Do not perturb.

**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 contents of :math:\mathrm{a} are overwritten.

**sva** : float, ndarray, shape :math:\left(n\right)
The, possibly scaled, singular values of :math:A.

The singular values of :math:A are :math:\sigma_{\textit{i}} = \alpha \times \mathrm{sva}[\textit{i}-1], for :math:\textit{i} = 1,2,\ldots,n, where :math:\alpha = \textit{work}/\textit{work}.

Normally :math:\alpha = 1 and no scaling is required to obtain the singular values.

However, if the largest singular value of :math:A overflows or if small singular values have been saved from underflow by scaling the input matrix :math:A, then :math:\alpha \neq 1.

If :math:\mathrm{jobr} = \texttt{'R'}, then some of the singular values may be returned as exact zeros because they are below the numerical rank threshold or are denormalized numbers.

**u** : float, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobu} = \texttt{'U'}, :math:\mathrm{u} contains the :math:m\times n matrix of left singular vectors.

If :math:\mathrm{jobu} = \texttt{'F'}, :math:\mathrm{u} contains the :math:m\times m matrix of left singular vectors, including an orthonormal basis of the orthogonal complement of Range(:math:A).

:math:\mathrm{u} is not referenced when :math:\mathrm{jobu} = \texttt{'W'} or :math:\texttt{'N'} and one of the following is satisfied:

:math:\mathrm{jobv} = \texttt{'W'} or :math:\texttt{'N'}, or

:math:n = 1, or

:math:A is the zero matrix.

**v** : float, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobv} = \texttt{'V'} or :math:\texttt{'J'}, :math:\mathrm{v} contains the :math:n\times n matrix of right singular vectors.

:math:\mathrm{v} is not referenced when :math:\mathrm{jobv} = \texttt{'W'} or :math:\texttt{'N'} and one of the following is satisfied:

:math:\mathrm{jobu} = \texttt{'U'} or :math:\texttt{'F'} and :math:\mathrm{jobt} = \texttt{'T'}, or

:math:n = 1, or

:math:A is the zero matrix.

**workb** : float, ndarray, shape :math:\left(7\right)
Contains information about the completed job.

:math:\mathrm{workb}

:math:\alpha = \mathrm{workb}/\mathrm{workb} is the scaling factor such that :math:\sigma_{\textit{i}} = \alpha \times \mathrm{sva}[\textit{i}-1], for :math:\textit{i} = 1,2,\ldots,n are the computed singular values of :math:A. (See the description of :math:\mathrm{sva}.)

:math:\mathrm{workb}

See the description of :math:\mathrm{workb}.

:math:\mathrm{workb}

sconda, an estimate for the condition number of column equilibrated :math:A (if :math:\mathrm{joba} = \texttt{'E'} or :math:\texttt{'G'}). sconda is an estimate of :math:\sqrt{\left(\left\lVert \left(R^\mathrm{T}R\right)^{-1}\right\rVert_1\right)}. It is computed using :meth:lapacklin.dpocon <naginterfaces.library.lapacklin.dpocon>. It satisfies :math:n^{{-\frac{1}{4}}}\times \textit{sconda}\leq \left\lVert R^{-1}\right\rVert_2\leq n^{\frac{1}{4}}\times \textit{sconda} where :math:R is the triangular factor from the :math:QR factorization of :math:A. However, if :math:R is truncated and the numerical rank is determined to be strictly smaller than :math:n, sconda is returned as :math:-1, thus indicating that the smallest singular values might be lost.

If full SVD is needed, and you are familiar with the details of the method, the following two condition numbers are useful for the analysis of the algorithm.

:math:\mathrm{workb}

An estimate of the scaled condition number of the triangular factor in the first :math:QR factorization.

:math:\mathrm{workb}

An estimate of the scaled condition number of the triangular factor in the second :math:QR factorization.

The following two parameters are computed if :math:\mathrm{jobt} = \texttt{'T'}.

:math:\mathrm{workb}

The entropy of :math:A^\mathrm{T}A: this is the Shannon entropy of :math:\mathrm{diag}\left({A^\mathrm{T}A}\right)/\mathrm{trace}\left({A^\mathrm{T}A}\right) taken as a point in the probability simplex.

:math:\mathrm{workb}

The entropy of :math:AA^\mathrm{T}.

**iworkb** : None or int, ndarray, shape :math:\left(:\right)
Contains information about the completed job.

:math:\mathrm{iworkb}

The numerical rank of :math:A determined after the initial :math:QR factorization with pivoting. See the descriptions of :math:\mathrm{joba} and :math:\mathrm{jobr}.

:math:\mathrm{iworkb}

The number of computed nonzero singular values.

:math:\mathrm{iworkb}

If nonzero, a warning message. If :math:\mathrm{iworkb} = 1, then some of the column norms of :math:A were denormalized (tiny) numbers. The requested high accuracy is not warranted by the data.

.. _f08kh-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{joba}.

Constraint: :math:\mathrm{joba} = \texttt{'C'}, :math:\texttt{'E'}, :math:\texttt{'F'}, :math:\texttt{'G'}, :math:\texttt{'A'} or :math:\texttt{'R'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{jobu}.

Constraint: :math:\mathrm{jobu} = \texttt{'U'}, :math:\texttt{'F'}, :math:\texttt{'W'} or :math:\texttt{'N'}.

(errno :math:-3)
On entry, error in parameter :math:\mathrm{jobv}.

Constraint: :math:\mathrm{jobv} = \texttt{'V'}, :math:\texttt{'J'}, :math:\texttt{'W'} or :math:\texttt{'N'}.

(errno :math:-3)
On entry, error in parameter :math:\mathrm{jobv}.

Constraint: :math:\mathrm{jobv} \neq \texttt{'J'}.

(errno :math:-4)
On entry, error in parameter :math:\mathrm{jobr}.

Constraint: :math:\mathrm{jobr} = \texttt{'N'} or :math:\texttt{'R'}.

(errno :math:-5)
On entry, error in parameter :math:\mathrm{jobt}.

Constraint: :math:\mathrm{jobt} = \texttt{'T'} or :math:\texttt{'N'}.

(errno :math:-6)
On entry, error in parameter :math:\mathrm{jobp}.

Constraint: :math:\mathrm{jobp} = \texttt{'P'} or :math:\texttt{'N'}.

(errno :math:-7)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

(errno :math:-8)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:m\geq n\geq 0.

**Warns**
**NagAlgorithmicWarning**
(errno :math:i > 0)
dgejsv did not converge in the allowed number of iterations (:math:30). The computed values might be inaccurate.

.. _f08kh-py2-py-notes:

**Notes**
The SVD is written as

.. math::
A = U\Sigma V^\mathrm{T}\text{,}

where :math:\Sigma is an :math:m\times n matrix which is zero except for its :math:n diagonal elements, :math:U is an :math:m\times m orthogonal matrix, and :math:V is an :math:n\times n orthogonal matrix.
The diagonal elements of :math:\Sigma are the singular values of :math:A in descending order of magnitude.
The columns of :math:U and :math:V are the left and the right singular vectors of :math:A, respectively.

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

Drmač, Z and Veselić, K, 2008, New fast and accurate Jacobi SVD Algorithm I, SIAM J. Matrix Anal. Appl. (29 4)

Drmač, Z and Veselić, K, 2008, New fast and accurate Jacobi SVD Algorithm II, SIAM J. Matrix Anal. Appl. (29 4)

Golub, G H and Van Loan, C F, 1996, Matrix Computations, (3rd Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError

[docs]def dgesvj(joba, jobu, jobv, a, mv, v, ctol):
r"""
dgesvj computes the one-sided Jacobi singular value decomposition (SVD) of a real :math:m\times n matrix :math:A, :math:m\geq n, with fast scaled rotations and de Rijk’s pivoting, optionally computing the left and/or right singular vectors.
For :math:m < n, the functions :meth:dgesvd or :meth:dgesdd may be used.

.. _f08kj-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08kjf.html

.. _f08kj-py2-py-parameters:

**Parameters**
**joba** : str, length 1
Specifies the structure of matrix :math:A.

:math:\mathrm{joba} = \texttt{'L'}

The input matrix :math:A is lower triangular.

:math:\mathrm{joba} = \texttt{'U'}

The input matrix :math:A is upper triangular.

:math:\mathrm{joba} = \texttt{'G'}

The input matrix :math:A is a general :math:m\times n matrix, :math:m\geq n.

**jobu** : str, length 1
Specifies whether to compute the left singular vectors and if so whether you want to control their numerical orthogonality threshold.

:math:\mathrm{jobu} = \texttt{'U'}

The left singular vectors corresponding to the nonzero singular values are computed and returned in the leading columns of :math:\mathrm{a}. See more details in the description of :math:\mathrm{a}. The numerical orthogonality threshold is set to approximately :math:\textit{tol} = \textit{ctol}\times \epsilon, where :math:\epsilon is the machine precision and :math:\textit{ctol} = \sqrt{m}.

:math:\mathrm{jobu} = \texttt{'C'}

Analogous to :math:\mathrm{jobu} = \texttt{'U'}, except that you can control the level of numerical orthogonality of the computed left singular vectors. The orthogonality threshold is set to :math:\textit{tol} = \mathrm{ctol}\times \epsilon. The option :math:\mathrm{jobu} = \texttt{'C'} can be used if :math:m\times \epsilon is a satisfactory orthogonality of the computed left singular vectors, so :math:\mathrm{ctol} = m could save a few sweeps of Jacobi rotations. See the descriptions of :math:\mathrm{a} and :math:\mathrm{ctol}.

:math:\mathrm{jobu} = \texttt{'N'}

The matrix :math:U is not computed. However, see the description of :math:\mathrm{a}.

**jobv** : str, length 1
Specifies whether and how to compute the right singular vectors.

:math:\mathrm{jobv} = \texttt{'V'}

The matrix :math:V is computed and returned in the array :math:\mathrm{v}.

:math:\mathrm{jobv} = \texttt{'A'}

The Jacobi rotations are applied to the leading :math:m_v\times n part of the array :math:\mathrm{v}. In other words, the right singular vector matrix :math:V is not computed explicitly, instead it is applied to an :math:m_v\times n matrix initially stored in the first :math:\mathrm{mv} rows of :math:\mathrm{v}.

:math:\mathrm{jobv} = \texttt{'N'}

The matrix :math:V is not computed and the array :math:\mathrm{v} is not referenced.

**a** : float, array-like, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:A.

**mv** : int
If :math:\mathrm{jobv} = \texttt{'A'}, the product of Jacobi rotations is applied to the first :math:m_v rows of :math:\mathrm{v}.

If :math:\mathrm{jobv} \neq \texttt{'A'}, :math:\mathrm{mv} is ignored.

See the description of :math:\mathrm{jobv}.

**v** : float, array-like, shape :math:\left(:, :\right)
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\mathrm{jobv}=\texttt{'V'}: :math:n; if :math:\mathrm{jobv}=\texttt{'A'}: :math:\mathrm{mv}; otherwise: :math:1.

Note: the required extent for this argument in dimension 2 is determined as follows: if :math:\mathrm{jobv}\text{ in } (\texttt{'V'}, \texttt{'A'}): :math:n; otherwise: :math:1.

If :math:\mathrm{jobv} = \texttt{'A'}, :math:\mathrm{v} must contain an :math:m_v\times n matrix to be premultiplied by the matrix :math:V of right singular vectors.

**ctol** : float
If :math:\mathrm{jobu} = \texttt{'C'}, :math:\mathrm{ctol} = \textit{ctol}, the threshold for convergence. The process stops if all columns of :math:A are mutually orthogonal up to :math:\textit{ctol}\times \epsilon. It is required that :math:\textit{ctol}\geq 1, i.e., it is not possible to force the function to obtain orthogonality below :math:\epsilon. :math:\textit{ctol} greater than :math:1/\epsilon is meaningless, where :math:\epsilon is the machine precision.

**Returns**
**a** : float, ndarray, shape :math:\left(m, n\right)
The matrix :math:U containing the left singular vectors of :math:A.

If :math:\mathrm{jobu} = \texttt{'U'} or :math:\texttt{'C'}

if :math:\textit{errno} = 0

:math:\mathrm{rank}\left(A\right) orthonormal columns of :math:U are returned in the leading :math:\mathrm{rank}\left(A\right) columns of the array :math:\mathrm{a}. Here :math:\mathrm{rank}\left(A\right)\leq n is the number of computed singular values of :math:A that are above the safe range parameter, as returned by :meth:machine.real_safe <naginterfaces.library.machine.real_safe>. The singular vectors corresponding to underflowed or zero singular values are not computed. The value of :math:\mathrm{rank}\left(A\right) is returned by rounding :math:\mathrm{work} to the nearest whole number. Also see the descriptions of :math:\mathrm{sva} and :math:\mathrm{work}. The computed columns of :math:U are mutually numerically orthogonal up to approximately :math:\textit{tol} = \sqrt{m}\times \epsilon; or :math:\textit{tol} = \mathrm{ctol}\times \epsilon (:math:\mathrm{jobu} = \texttt{'C'}), where :math:\epsilon is the machine precision, see the description of :math:\mathrm{jobu}.

if :math:\textit{errno} > 0

dgesvj did not converge in :math:30 iterations (sweeps). In this case, the computed columns of :math:U may not be orthogonal up to :math:\textit{tol}. The output :math:U (stored in :math:\mathrm{a}), :math:\Sigma (given by the computed singular values in :math:\mathrm{sva}) and :math:V is still a decomposition of the input matrix :math:A in the sense that the residual :math:\left\lVert A-\alpha \times U\times \Sigma \times V^\mathrm{T}\right\rVert_2/\left\lVert A\right\rVert_2 is small, where :math:\alpha is the value returned in :math:\mathrm{work}.

If :math:\mathrm{jobu} = \texttt{'N'}

if :math:\textit{errno} = 0

Note that the left singular vectors are 'for free' in the one-sided Jacobi SVD algorithm. However, if only the singular values are needed, the level of numerical orthogonality of :math:U is not an issue and iterations are stopped when the columns of the iterated matrix are numerically orthogonal up to approximately :math:m\times \epsilon. Thus, on exit, :math:\mathrm{a} contains the columns of :math:U scaled with the corresponding singular values.

if :math:\textit{errno} > 0

dgesvj did not converge in :math:30 iterations (sweeps).

**sva** : float, ndarray, shape :math:\left(n\right)
The, possibly scaled, singular values of :math:A.

If :math:\textit{errno} = 0

The singular values of :math:A are :math:\sigma_{\textit{i}} = \alpha \mathrm{sva}[\textit{i}-1], for :math:\textit{i} = 1,2,\ldots,n, where :math:\alpha is the scale factor stored in :math:\mathrm{work}. Normally :math:\alpha = 1, however, if some of the singular values of :math:A might underflow or overflow, then :math:\alpha \neq 1 and the scale factor needs to be applied to obtain the singular values.

If :math:\textit{errno} > 0

dgesvj did not converge in :math:30 iterations and :math:\alpha \times \mathrm{sva} may not be accurate.

**v** : float, ndarray, shape :math:\left(:, :\right)
The right singular vectors of :math:A.

If :math:\mathrm{jobv} = \texttt{'V'}, :math:\mathrm{v} contains the :math:n\times n matrix of the right singular vectors.

If :math:\mathrm{jobv} = \texttt{'A'}, :math:\mathrm{v} contains the product of the computed right singular vector matrix and the initial matrix in the array :math:\mathrm{v}.

If :math:\mathrm{jobv} = \texttt{'N'}, :math:\mathrm{v} is not referenced.

**work** : float, ndarray, shape :math:\left(6\right)
Contains information about the completed job.

:math:\mathrm{work}

The scaling factor, :math:\alpha, such that :math:\sigma_{\textit{i}} = \alpha \mathrm{sva}[\textit{i}-1], for :math:\textit{i} = 1,2,\ldots,n are the computed singular values of :math:A. (See the description of :math:\mathrm{sva}.)

:math:\mathrm{work}

:math:\mathrm{nint}\left(\mathrm{work}\right) gives the number of the computed nonzero singular values.

:math:\mathrm{work}

:math:\mathrm{nint}\left(\mathrm{work}\right) gives the number of the computed singular values that are larger than the underflow threshold.

:math:\mathrm{work}

:math:\mathrm{nint}\left(\mathrm{work}\right) gives the number of iterations (sweeps of Jacobi rotations) needed for numerical convergence.

:math:\mathrm{work}

:math:\mathrm{max}_{{i\neq j}}\left\lvert \cos\left({A\left(:, i\right)}, {A\left(:, j\right)}\right)\right\rvert in the last iteration (sweep). This is useful information in cases when dgesvj did not converge, as it can be used to estimate whether the output is still useful and for subsequent analysis.

:math:\mathrm{work}

The largest absolute value over all sines of the Jacobi rotation angles in the last sweep. It can be useful for subsequent analysis.

.. _f08kj-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{joba}.

Constraint: :math:\mathrm{joba} = \texttt{'L'}, :math:\texttt{'U'} or :math:\texttt{'G'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{jobu}.

Constraint: :math:\mathrm{jobu} = \texttt{'U'}, :math:\texttt{'C'} or :math:\texttt{'N'}.

(errno :math:-3)
On entry, error in parameter :math:\mathrm{jobv}.

Constraint: :math:\mathrm{jobv} = \texttt{'V'}, :math:\texttt{'A'} or :math:\texttt{'N'}.

(errno :math:-4)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

(errno :math:-5)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:m\geq n\geq 0.

(errno :math:-9)
On entry, error in parameter :math:\mathrm{mv}.

Constraint: :math:\mathrm{mv}\geq 0.

(errno :math:-12)
On entry, error in parameter :math:\mathrm{ctol}.

Constraint: :math:\mathrm{ctol}\geq 1.0.

**Warns**
**NagAlgorithmicWarning**
(errno :math:i > 0)
dgesvj did not converge in the allowed number of iterations (:math:30), but its output might still be useful.

.. _f08kj-py2-py-notes:

**Notes**
The SVD is written as

.. math::
A = U\Sigma V^\mathrm{T}\text{,}

where :math:\Sigma is an :math:n\times n diagonal matrix, :math:U is an :math:m\times n orthonormal matrix, and :math:V is an :math:n\times n orthogonal matrix.
The diagonal elements of :math:\Sigma are the singular values of :math:A in descending order of magnitude.
The columns of :math:U and :math:V are the left and the right singular vectors of :math:A.

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

Drmač, Z and Veselić, K, 2008, New fast and accurate Jacobi SVD Algorithm I, SIAM J. Matrix Anal. Appl. (29 4)

Drmač, Z and Veselić, K, 2008, New fast and accurate Jacobi SVD Algorithm II, SIAM J. Matrix Anal. Appl. (29 4)

Golub, G H and Van Loan, C F, 1996, Matrix Computations, (3rd Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError

[docs]def dgesvdx(jobu, jobvt, erange, a, vl, vu, il, iu):
r"""
dgesvdx computes the singular value decomposition (SVD) of a real :math:m\times n matrix :math:A, optionally computing the left and/or right singular vectors.
All singular values or a selected set of singular values may be computed.

.. _f08km-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08kmf.html

.. _f08km-py2-py-parameters:

**Parameters**
**jobu** : str, length 1
Specifies options for computing all or part of the matrix :math:U.

:math:\mathrm{jobu} = \texttt{'V'}

The :math:\mathrm{ns} columns of :math:U, as specified by :math:\mathrm{erange}, are returned in array :math:\mathrm{u}.

:math:\mathrm{jobu} = \texttt{'N'}

No columns of :math:U (no left singular vectors) are computed.

**jobvt** : str, length 1
Specifies options for computing all or part of the matrix :math:V^\mathrm{T}.

:math:\mathrm{jobvt} = \texttt{'V'}

The :math:\mathrm{ns} rows of :math:V^\mathrm{T}, as specified by :math:\mathrm{erange}, are returned in the array :math:\mathrm{vt}.

:math:\mathrm{jobvt} = \texttt{'N'}

No rows of :math:V^\mathrm{T} (no right singular vectors) are computed.

**erange** : str, length 1
Indicates which singular values should be returned.

:math:\mathrm{erange} = \texttt{'A'}

All singular values will be found.

:math:\mathrm{erange} = \texttt{'V'}

All singular values in the half-open interval :math:\left(\mathrm{vl}, \mathrm{vu}\right] will be found.

:math:\mathrm{erange} = \texttt{'I'}

The :math:\mathrm{il}\ th through :math:\mathrm{iu}\ th singular values will be found.

**a** : float, array-like, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:A.

**vl** : float
If :math:\mathrm{erange} = \texttt{'V'}, the lower bound of the interval to be searched for singular values.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'I'}, :math:\mathrm{vl} is not referenced.

**vu** : float
If :math:\mathrm{erange} = \texttt{'V'}, the upper bound of the interval to be searched for singular values.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'I'}, :math:\mathrm{vu} is not referenced.

**il** : int
If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{il} and :math:\mathrm{iu} specify the indices (in ascending order) of the smallest and largest singular values to be returned, respectively.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}, :math:\mathrm{il} and :math:\mathrm{iu} are not referenced.

**iu** : int
If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{il} and :math:\mathrm{iu} specify the indices (in ascending order) of the smallest and largest singular values to be returned, respectively.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}, :math:\mathrm{il} and :math:\mathrm{iu} are not referenced.

**Returns**
**a** : float, ndarray, shape :math:\left(m, n\right)
If :math:\mathrm{jobu} \neq \texttt{'N'} and :math:\mathrm{jobvt} \neq \texttt{'N'}, the contents of :math:\mathrm{a} are destroyed.

**ns** : int
The total number of singular values found. :math:0\leq \mathrm{ns}\leq \mathrm{min}\left(m, n\right).

If :math:\mathrm{erange} = \texttt{'A'}, :math:\mathrm{ns} = \mathrm{min}\left(m, n\right).

If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{ns} = \mathrm{iu}-\mathrm{il}+1.

If :math:\mathrm{erange} = \texttt{'V'} then the value of :math:\mathrm{ns} is not known in advance and so an upper limit should be used when specifying the dimensions of array :math:\mathrm{u}, e.g., :math:\mathrm{min}\left(m, n\right).

**s** : float, ndarray, shape :math:\left(\min\left(m,n\right)\right)
The singular values of :math:A, sorted so that :math:\mathrm{s}[i-1]\geq \mathrm{s}[i].

**u** : None or float, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobu} = \texttt{'V'}, :math:\mathrm{u} contains the first :math:\mathrm{ns} columns of :math:U (the left singular vectors, stored column-wise).

If :math:\mathrm{jobu} = \texttt{'N'}, :math:\mathrm{u} is not referenced.

**vt** : None or float, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobvt} = \texttt{'V'}, :math:\mathrm{vt} contains the first :math:\mathrm{ns} rows of :math:V^\mathrm{T} (the right singular vectors, stored row-wise).

If :math:\mathrm{jobvt} = \texttt{'N'}, :math:\mathrm{vt} is not referenced.

**workb** : float, ndarray, shape :math:\left(\min\left(m,n\right)\right)
If :math:\mathrm{errno} > 0, :math:\mathrm{workb}[1:\mathrm{min}\left(m, n\right)] contains the unconverged superdiagonal elements of an upper bidiagonal matrix :math:B whose diagonal is in :math:\mathrm{s} (not necessarily sorted). :math:B satisfies :math:A = UBV^\mathrm{T}, so it has the same singular values as :math:A, and singular vectors related by :math:U and :math:V^\mathrm{T}.

**jfail** : int, ndarray, shape :math:\left(2\times \min\left(m,n\right)\right)
If :math:\mathrm{errno} > 0, :math:\mathrm{jfail} contains, in its first :math:k nonzero elements, the indices of the :math:k eigenvectors (associated with a left or right singular vector, see :meth:dbdsvdx) that failed to converge.

.. _f08km-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{jobu}.

Constraint: :math:\mathrm{jobu} = \texttt{'V'} or :math:\texttt{'N'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{jobvt}.

Constraint: :math:\mathrm{jobvt} = \texttt{'V'} or :math:\texttt{'N'}.

(errno :math:-3)
On entry, error in parameter :math:\mathrm{erange}.

Constraint: :math:\mathrm{erange} = \texttt{'A'}, :math:\texttt{'V'} or :math:\texttt{'I'}.

(errno :math:-4)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

(errno :math:-5)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

(errno :math:-8)
On entry, error in parameter :math:\mathrm{vl}.

Constraint: :math:0.0\leq \mathrm{vl}.

(errno :math:-9)
On entry, error in parameter :math:\mathrm{vu}.

Constraint: :math:\mathrm{vl} < \mathrm{vu}.

(errno :math:-10)
On entry, error in parameter :math:\mathrm{il}.

(errno :math:-11)
On entry, error in parameter :math:\mathrm{iu}.

(errno :math:i > 0)
If dgesvdx did not converge, :math:\textit{errno} specifies how many superdiagonals of an intermediate bidiagonal form did not converge to zero.

.. _f08km-py2-py-notes:

**Notes**
The SVD is written as

.. math::
A = U\Sigma V^\mathrm{T}\text{,}

where :math:\Sigma is an :math:m\times n matrix which is zero except for its :math:\mathrm{min}\left(m, n\right) diagonal elements, :math:U is an :math:m\times m orthogonal matrix, and :math:V is an :math:n\times n orthogonal matrix.
The diagonal elements of :math:\Sigma are the singular values of :math:A; they are real and non-negative, and are returned in descending order.
The first :math:\mathrm{min}\left(m, n\right) columns of :math:U and :math:V are the left and right singular vectors of :math:A, respectively.

Note that the function returns :math:V^\mathrm{T}, not :math:V.

Alternative to computing all singular values of :math:A, a selected set can be computed.
The set is either those singular values lying in a given interval, :math:\sigma \in \left(v_l, v_u\right], or those whose index (counting from largest to smallest in magnitude) lies in a given range :math:1\leq i_l,\ldots,i_u\leq n.
In these cases, the corresponding left and right singular vectors can optionally be computed.

.. _f08km-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 zgelss(a, b, rcond):
r"""
zgelss computes the minimum norm solution to a complex linear least squares problem

.. math::
\mathrm{min}_x\left\lVert b-Ax\right\rVert_2\text{.}

.. _f08kn-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08knf.html

.. _f08kn-py2-py-parameters:

**Parameters**
**a** : complex, array-like, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:A.

**b** : complex, array-like, shape :math:\left(\max\left(m,n\right), \textit{nrhs}\right)
The :math:m\times r right-hand side matrix :math:B.

**rcond** : float
Used to determine the effective rank of :math:A. Singular values :math:\mathrm{s}[i-1]\leq \mathrm{rcond}\times \mathrm{s} are treated as zero. If :math:\mathrm{rcond} < 0, machine precision is used instead.

**Returns**
**a** : complex, ndarray, shape :math:\left(m, n\right)
The first :math:\mathrm{min}\left(m, n\right) rows of :math:A are overwritten with its right singular vectors, stored row-wise.

**b** : complex, ndarray, shape :math:\left(\max\left(m,n\right), \textit{nrhs}\right)
:math:\mathrm{b} is overwritten by the :math:n\times r solution matrix :math:X. If :math:m\geq n and :math:\mathrm{rank} = n, the residual sum of squares for the solution in the :math:i\ th column is given by the sum of squares of the modulus of elements :math:n+1,\ldots,m in that column.

**s** : float, ndarray, shape :math:\left(\min\left(m,n\right)\right)
The singular values of :math:A in decreasing order.

**rank** : int
The effective rank of :math:A, i.e., the number of singular values which are greater than :math:\mathrm{rcond}\times \mathrm{s}.

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

(errno :math:-3)
On entry, error in parameter :math:\textit{nrhs}.

Constraint: :math:\textit{nrhs}\geq 0.

(errno :math:i > 0)
The algorithm for computing the SVD failed to converge; :math:\langle\mathit{\boldsymbol{value}}\rangle off-diagonal elements of an intermediate bidiagonal form did not converge to zero.

.. _f08kn-py2-py-notes:

**Notes**
zgelss uses the singular value decomposition (SVD) of :math:A, where :math:A is an :math:m\times n matrix which may be rank-deficient.

Several right-hand side vectors :math:b and solution vectors :math:x can be handled in a single call; they are stored as the columns of the :math:m\times r right-hand side matrix :math:B and the :math:n\times r solution matrix :math:X.

The effective rank of :math:A is determined by treating as zero those singular values which are less than :math:\mathrm{rcond} times the largest singular value.

.. _f08kn-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 zgesvd(jobu, jobvt, a):
r"""
zgesvd computes the singular value decomposition (SVD) of a complex :math:m\times n matrix :math:A, optionally computing the left and/or right singular vectors.

.. _f08kp-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08kpf.html

.. _f08kp-py2-py-parameters:

**Parameters**
**jobu** : str, length 1
Specifies options for computing all or part of the matrix :math:U.

:math:\mathrm{jobu} = \texttt{'A'}

All :math:m columns of :math:U are returned in array :math:\mathrm{u}.

:math:\mathrm{jobu} = \texttt{'S'}

The first :math:\mathrm{min}\left(m, n\right) columns of :math:U (the left singular vectors) are returned in the array :math:\mathrm{u}.

:math:\mathrm{jobu} = \texttt{'O'}

The first :math:\mathrm{min}\left(m, n\right) columns of :math:U (the left singular vectors) are overwritten on the array :math:\mathrm{a}.

:math:\mathrm{jobu} = \texttt{'N'}

No columns of :math:U (no left singular vectors) are computed.

**jobvt** : str, length 1
Specifies options for computing all or part of the matrix :math:V^\mathrm{H}.

:math:\mathrm{jobvt} = \texttt{'A'}

All :math:n rows of :math:V^\mathrm{H} are returned in the array :math:\mathrm{vt}.

:math:\mathrm{jobvt} = \texttt{'S'}

The first :math:\mathrm{min}\left(m, n\right) rows of :math:V^\mathrm{H} (the right singular vectors) are returned in the array :math:\mathrm{vt}.

:math:\mathrm{jobvt} = \texttt{'O'}

The first :math:\mathrm{min}\left(m, n\right) rows of :math:V^\mathrm{H} (the right singular vectors) are overwritten on the array :math:\mathrm{a}.

:math:\mathrm{jobvt} = \texttt{'N'}

No rows of :math:V^\mathrm{H} (no right singular vectors) are computed.

**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)
If :math:\mathrm{jobu} = \texttt{'O'}, :math:\mathrm{a} is overwritten with the first :math:\mathrm{min}\left(m, n\right) columns of :math:U (the left singular vectors, stored column-wise).

If :math:\mathrm{jobvt} = \texttt{'O'}, :math:\mathrm{a} is overwritten with the first :math:\mathrm{min}\left(m, n\right) rows of :math:V^\mathrm{H} (the right singular vectors, stored row-wise).

If :math:\mathrm{jobu} \neq \texttt{'O'} and :math:\mathrm{jobvt} \neq \texttt{'O'}, the contents of :math:\mathrm{a} are destroyed.

**s** : float, ndarray, shape :math:\left(\min\left(m,n\right)\right)
The singular values of :math:A, sorted so that :math:\mathrm{s}[i-1]\geq \mathrm{s}[i].

**u** : complex, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobu} = \texttt{'A'}, :math:\mathrm{u} contains the :math:m\times m unitary matrix :math:U.

If :math:\mathrm{jobu} = \texttt{'S'}, :math:\mathrm{u} contains the first :math:\mathrm{min}\left(m, n\right) columns of :math:U (the left singular vectors, stored column-wise).

If :math:\mathrm{jobu} = \texttt{'N'} or :math:\texttt{'O'}, :math:\mathrm{u} is not referenced.

**vt** : complex, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobvt} = \texttt{'A'}, :math:\mathrm{vt} contains the :math:n\times n unitary matrix :math:V^H.

If :math:\mathrm{jobvt} = \texttt{'S'}, :math:\mathrm{vt} contains the first :math:\mathrm{min}\left(m, n\right) rows of :math:V^\mathrm{H} (the right singular vectors, stored row-wise).

If :math:\mathrm{jobvt} = \texttt{'N'} or :math:\texttt{'O'}, :math:\mathrm{vt} is not referenced.

**rworkb** : float, ndarray, shape :math:\left(\min\left(m,n\right)\right)
If :math:\mathrm{errno} > 0, :math:\mathrm{rworkb}[0:\mathrm{min}\left(m, n\right)-1] contains the unconverged superdiagonal elements of an upper bidiagonal matrix :math:B whose diagonal is in :math:S (not necessarily sorted). :math:B satisfies :math:A = UBV^\mathrm{T}, so it has the same singular values as :math:A, and singular vectors related by :math:U and :math:V^\mathrm{T}.

.. _f08kp-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{jobu}.

Constraint: :math:\mathrm{jobu} = \texttt{'A'}, :math:\texttt{'S'}, :math:\texttt{'O'} or :math:\texttt{'N'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{jobvt}.

Constraint: :math:\mathrm{jobvt} = \texttt{'A'}, :math:\texttt{'S'}, :math:\texttt{'O'} or :math:\texttt{'N'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{jobvt}.

Constraint: :math:\mathrm{jobvt} \neq \texttt{'O'} or :math:\mathrm{jobu} \neq \texttt{'O'}.

(errno :math:-3)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

(errno :math:-4)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

(errno :math:i > 0)
If zgesvd did not converge, :math:\textit{errno} specifies how many superdiagonals of an intermediate bidiagonal form did not converge to zero.

.. _f08kp-py2-py-notes:

**Notes**
The SVD is written as

.. math::
A = U\Sigma V^\mathrm{H}\text{,}

where :math:\Sigma is an :math:m\times n matrix which is zero except for its :math:\mathrm{min}\left(m, n\right) diagonal elements, :math:U is an :math:m\times m unitary matrix, and :math:V is an :math:n\times n unitary matrix.
The diagonal elements of :math:\Sigma are the singular values of :math:A; they are real and non-negative, and are returned in descending order.
The first :math:\mathrm{min}\left(m, n\right) columns of :math:U and :math:V are the left and right singular vectors of :math:A.

Note that the function returns :math:V^\mathrm{H}, not :math:V.

.. _f08kp-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 zgelsd(a, b, rcond):
r"""
zgelsd computes the minimum norm solution to a complex linear least squares problem

.. math::
\mathrm{min}_x\left\lVert b-Ax\right\rVert_2\text{.}

.. _f08kq-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08kqf.html

.. _f08kq-py2-py-parameters:

**Parameters**
**a** : complex, array-like, shape :math:\left(m, n\right)
The :math:m\times n coefficient matrix :math:A.

**b** : complex, array-like, shape :math:\left(\max\left(m,n\right), \textit{nrhs}\right)
The :math:m\times r right-hand side matrix :math:B.

**rcond** : float
Used to determine the effective rank of :math:A. Singular values :math:\mathrm{s}[i-1]\leq \mathrm{rcond}\times \mathrm{s} are treated as zero. If :math:\mathrm{rcond} < 0, machine precision is used instead.

**Returns**
**a** : complex, ndarray, shape :math:\left(m, n\right)
The contents of :math:\mathrm{a} are destroyed.

**b** : complex, ndarray, shape :math:\left(\max\left(m,n\right), \textit{nrhs}\right)
:math:\mathrm{b} is overwritten by the :math:n\times r solution matrix :math:X. If :math:m\geq n and :math:\mathrm{rank} = n, the residual sum of squares for the solution in the :math:i\ th column is given by the sum of squares of the modulus of elements :math:n+1,\ldots,m in that column.

**s** : float, ndarray, shape :math:\left(\min\left(m,n\right)\right)
The singular values of :math:A in decreasing order.

**rank** : int
The effective rank of :math:A, i.e., the number of singular values which are greater than :math:\mathrm{rcond}\times \mathrm{s}.

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

(errno :math:-3)
On entry, error in parameter :math:\textit{nrhs}.

Constraint: :math:\textit{nrhs}\geq 0.

(errno :math:i > 0)
The algorithm for computing the SVD failed to converge; :math:\langle\mathit{\boldsymbol{value}}\rangle off-diagonal elements of an intermediate bidiagonal form did not converge to zero.

.. _f08kq-py2-py-notes:

**Notes**
zgelsd uses the singular value decomposition (SVD) of :math:A, where :math:A is a complex :math:m\times n matrix which may be rank-deficient.

Several right-hand side vectors :math:b and solution vectors :math:x can be handled in a single call; they are stored as the columns of the :math:m\times r right-hand side matrix :math:B and the :math:n\times r solution matrix :math:X.

The problem is solved in three steps:

(1) reduce the coefficient matrix :math:A to bidiagonal form with Householder transformations, reducing the original problem into a 'bidiagonal least squares problem' (BLS);

(#) solve the BLS using a divide-and-conquer approach;

(#) apply back all the Householder transformations to solve the original least squares problem.

The effective rank of :math:A is determined by treating as zero those singular values which are less than :math:\mathrm{rcond} times the largest singular value.

.. _f08kq-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 zgesdd(jobz, a):
r"""
zgesdd computes the singular value decomposition (SVD) of a complex :math:m\times n matrix :math:A, optionally computing the left and/or right singular vectors, by using a divide-and-conquer method.

.. _f08kr-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08krf.html

.. _f08kr-py2-py-parameters:

**Parameters**
**jobz** : str, length 1
Specifies options for computing all or part of the matrix :math:U.

:math:\mathrm{jobz} = \texttt{'A'}

All :math:m columns of :math:U and all :math:n rows of :math:V^\mathrm{H} are returned in the arrays :math:\mathrm{u} and :math:\mathrm{vt}.

:math:\mathrm{jobz} = \texttt{'S'}

The first :math:\mathrm{min}\left(m, n\right) columns of :math:U and the first :math:\mathrm{min}\left(m, n\right) rows of :math:V^\mathrm{H} are returned in the arrays :math:\mathrm{u} and :math:\mathrm{vt}.

:math:\mathrm{jobz} = \texttt{'O'}

If :math:m\geq n, the first :math:n columns of :math:U are overwritten on the array :math:\mathrm{a} and all rows of :math:V^\mathrm{H} are returned in the array :math:\mathrm{vt}. Otherwise, all columns of :math:U are returned in the array :math:\mathrm{u} and the first :math:m rows of :math:V^\mathrm{H} are overwritten in the array :math:\mathrm{vt}.

:math:\mathrm{jobz} = \texttt{'N'}

No columns of :math:U or rows of :math:V^\mathrm{H} are computed.

**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)
If :math:\mathrm{jobz} = \texttt{'O'}, :math:\mathrm{a} is overwritten with the first :math:n columns of :math:U (the left singular vectors, stored column-wise) if :math:m\geq n; :math:\mathrm{a} is overwritten with the first :math:m rows of :math:V^\mathrm{H} (the right singular vectors, stored row-wise) otherwise.

If :math:\mathrm{jobz} \neq \texttt{'O'}, the contents of :math:\mathrm{a} are destroyed.

**s** : float, ndarray, shape :math:\left(\min\left(m,n\right)\right)
The singular values of :math:A, sorted so that :math:\mathrm{s}[i-1]\geq \mathrm{s}[i].

**u** : complex, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobz} = \texttt{'A'} or :math:\mathrm{jobz} = \texttt{'O'} and :math:m < n, :math:\mathrm{u} contains the :math:m\times m unitary matrix :math:U.

If :math:\mathrm{jobz} = \texttt{'S'}, :math:\mathrm{u} contains the first :math:\mathrm{min}\left(m, n\right) columns of :math:U (the left singular vectors, stored column-wise).

If :math:\mathrm{jobz} = \texttt{'O'} and :math:m\geq n, or :math:\mathrm{jobz} = \texttt{'N'}, :math:\mathrm{u} is not referenced.

**vt** : complex, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobz} = \texttt{'A'} or :math:\mathrm{jobz} = \texttt{'O'} and :math:m\geq n, :math:\mathrm{vt} contains the :math:n\times n unitary matrix :math:V^H.

If :math:\mathrm{jobz} = \texttt{'S'}, :math:\mathrm{vt} contains the first :math:\mathrm{min}\left(m, n\right) rows of :math:V^\mathrm{H} (the right singular vectors, stored row-wise).

If :math:\mathrm{jobz} = \texttt{'O'} and :math:m < n, or :math:\mathrm{jobz} = \texttt{'N'}, :math:\mathrm{vt} is not referenced.

.. _f08kr-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{jobz}.

Constraint: :math:\mathrm{jobz} = \texttt{'A'}, :math:\texttt{'S'}, :math:\texttt{'O'} or :math:\texttt{'N'}.

(errno :math:-2)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

(errno :math:-3)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

(errno :math:i > 0)
zgesdd did not converge, the updating process failed.

.. _f08kr-py2-py-notes:

**Notes**
The SVD is written as

.. math::
A = U\Sigma V^\mathrm{H}\text{,}

where :math:\Sigma is an :math:m\times n matrix which is zero except for its :math:\mathrm{min}\left(m, n\right) diagonal elements, :math:U is an :math:m\times m unitary matrix, and :math:V is an :math:n\times n unitary matrix.
The diagonal elements of :math:\Sigma are the singular values of :math:A; they are real and non-negative, and are returned in descending order.
The first :math:\mathrm{min}\left(m, n\right) columns of :math:U and :math:V are the left and right singular vectors of :math:A.

Note that the function returns :math:V^\mathrm{H}, not :math:V.

.. _f08kr-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 zgebrd(a):
r"""
zgebrd reduces a complex :math:m\times n matrix to bidiagonal form.

.. _f08ks-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08ksf.html

.. _f08ks-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)
If :math:m\geq n, the diagonal and first superdiagonal are overwritten by the upper bidiagonal matrix :math:B, elements below the diagonal are overwritten by details of the unitary matrix :math:Q and elements above the first superdiagonal are overwritten by details of the unitary matrix :math:P.

If :math:m < n, the diagonal and first subdiagonal are overwritten by the lower bidiagonal matrix :math:B, elements below the first subdiagonal are overwritten by details of the unitary matrix :math:Q and elements above the diagonal are overwritten by details of the unitary matrix :math:P.

**d** : float, ndarray, shape :math:\left(\min\left(m,n\right)\right)
The diagonal elements of the bidiagonal matrix :math:B.

**e** : float, ndarray, shape :math:\left(\min\left(m,n\right)-1\right)
The off-diagonal elements of the bidiagonal matrix :math:B.

**tauq** : complex, ndarray, shape :math:\left(\min\left(m,n\right)\right)
Further details of the unitary matrix :math:Q.

**taup** : complex, ndarray, shape :math:\left(\min\left(m,n\right)\right)
Further details of the unitary matrix :math:P.

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

.. _f08ks-py2-py-notes:

**Notes**
zgebrd reduces a complex :math:m\times n matrix :math:A to real bidiagonal form :math:B by a unitary transformation: :math:A = QBP^\mathrm{H}, where :math:Q and :math:P^\mathrm{H} are unitary matrices of order :math:m and :math:n respectively.

If :math:m\geq n, the reduction is given by:

.. math::
A = Q\begin{pmatrix}B_1\\0\end{pmatrix}P^\mathrm{H} = Q_1B_1P^\mathrm{H}\text{,}

where :math:B_1 is a real :math:n\times n upper bidiagonal matrix and :math:Q_1 consists of the first :math:n columns of :math:Q.

If :math:m < n, the reduction is given by

.. math::
A = Q\begin{pmatrix}B_1&0\end{pmatrix}P^\mathrm{H} = QB_1P_1^\mathrm{H}\text{,}

where :math:B_1 is a real :math:m\times m lower bidiagonal matrix and :math:P_1^\mathrm{H} consists of the first :math:m rows of :math:P^\mathrm{H}.

The unitary matrices :math:Q and :math:P are not formed explicitly but are represented as products of elementary reflectors (see the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html>__ for details). Functions are provided to work with :math:Q and :math:P in this representation (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08ksf.html#fcomments>__).

.. _f08ks-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 zungbr(vect, k, a, tau):
r"""
zungbr generates one of the complex unitary matrices :math:Q or :math:P^\mathrm{H} which were determined by :meth:zgebrd when reducing a complex matrix to bidiagonal form.

.. _f08kt-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08ktf.html

.. _f08kt-py2-py-parameters:

**Parameters**
**vect** : str, length 1
Indicates whether the unitary matrix :math:Q or :math:P^\mathrm{H} is generated.

:math:\mathrm{vect} = \texttt{'Q'}

:math:Q is generated.

:math:\mathrm{vect} = \texttt{'P'}

:math:P^\mathrm{H} is generated.

**k** : int
If :math:\mathrm{vect} = \texttt{'Q'}, the number of columns in the original matrix :math:A.

If :math:\mathrm{vect} = \texttt{'P'}, the number of rows in the original matrix :math:A.

**a** : complex, array-like, shape :math:\left(m, n\right)
Details of the vectors which define the elementary reflectors, as returned by :meth:zgebrd.

**tau** : complex, array-like, shape :math:\left(:\right)
Note: the required length for this argument is determined as follows: if :math:\mathrm{vect}=\texttt{'Q'}: :math:\min\left(m,\mathrm{k}\right); if :math:\mathrm{vect}=\texttt{'P'}: :math:\min\left(n,\mathrm{k}\right); otherwise: :math:0.

Further details of the elementary reflectors, as returned by :meth:zgebrd in its argument :math:\textit{tauq} if :math:\mathrm{vect} = \texttt{'Q'}, or in its argument :math:\textit{taup} if :math:\mathrm{vect} = \texttt{'P'}.

**Returns**
**a** : complex, ndarray, shape :math:\left(m, n\right)
The unitary matrix :math:Q or :math:P^\mathrm{H}, or the leading rows or columns thereof, as specified by :math:\mathrm{vect}, :math:\mathrm{m} and :math:\mathrm{n}.

.. _f08kt-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{vect}.

Constraint: :math:\mathrm{vect} = \texttt{'Q'} or :math:\texttt{'P'}.

(errno :math:-2)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

(errno :math:-3)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

(errno :math:-3)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:m\geq n\geq \mathrm{k}.

(errno :math:-3)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:m = n.

(errno :math:-3)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq m\geq \mathrm{k}.

(errno :math:-3)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n = m.

(errno :math:-4)
On entry, error in parameter :math:\mathrm{k}.

Constraint: :math:\mathrm{k}\geq 0.

.. _f08kt-py2-py-notes:

**Notes**
zungbr is intended to be used after a call to :meth:zgebrd, which reduces a complex rectangular matrix :math:A to real bidiagonal form :math:B by a unitary transformation: :math:A = QBP^\mathrm{H}. :meth:zgebrd represents the matrices :math:Q and :math:P^\mathrm{H} as products of elementary reflectors.

This function may be used to generate :math:Q or :math:P^\mathrm{H} explicitly as square matrices, or in some cases just the leading columns of :math:Q or the leading rows of :math:P^\mathrm{H}.

The various possibilities are specified by the arguments :math:\mathrm{vect}, :math:\textit{m}, :math:\textit{n} and :math:\mathrm{k}.
The appropriate values to cover the most likely cases are as follows (assuming that :math:A was an :math:m\times n matrix):

(1) To form the full :math:m\times m matrix :math:Q: set :math:\mathrm{vect} = \texttt{'Q'}, :math:n = m and :math:\mathrm{k} = n (note that the array :math:\mathrm{a} must have at least :math:m columns).

(#) If :math:m > n, to form the :math:n leading columns of :math:Q: set :math:\mathrm{vect} = \texttt{'Q'} and :math:\mathrm{k} = n

(#) To form the full :math:n\times n matrix :math:P^\mathrm{H}: set :math:\mathrm{vect} = \texttt{'P'}, :math:m = n and :math:\mathrm{k} = m (note that the array :math:\mathrm{a} must have at least :math:n rows).

(#) If :math:m < n, to form the :math:m leading rows of :math:P^\mathrm{H}: set :math:\mathrm{vect} = \texttt{'P'} and :math:\mathrm{k} = m

.. _f08kt-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 zunmbr(vect, side, trans, k, a, tau, c):
r"""
zunmbr multiplies an arbitrary complex :math:m\times n matrix :math:C by one of the complex unitary matrices :math:Q or :math:P which were determined by :meth:zgebrd when reducing a complex matrix to bidiagonal form.

.. _f08ku-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08kuf.html

.. _f08ku-py2-py-parameters:

**Parameters**
**vect** : str, length 1
Indicates whether :math:Q or :math:Q^\mathrm{H} or :math:P or :math:P^\mathrm{H} is to be applied to :math:C.

:math:\mathrm{vect} = \texttt{'Q'}

:math:Q or :math:Q^\mathrm{H} is applied to :math:C.

:math:\mathrm{vect} = \texttt{'P'}

:math:P or :math:P^\mathrm{H} is applied to :math:C.

**side** : str, length 1
Indicates how :math:Q or :math:Q^\mathrm{H} or :math:P or :math:P^\mathrm{H} is to be applied to :math:C.

:math:\mathrm{side} = \texttt{'L'}

:math:Q or :math:Q^\mathrm{H} or :math:P or :math:P^\mathrm{H} is applied to :math:C from the left.

:math:\mathrm{side} = \texttt{'R'}

:math:Q or :math:Q^\mathrm{H} or :math:P or :math:P^\mathrm{H} is applied to :math:C from the right.

**trans** : str, length 1
Indicates whether :math:Q or :math:P or :math:Q^\mathrm{H} or :math:P^\mathrm{H} is to be applied to :math:C.

:math:\mathrm{trans} = \texttt{'N'}

:math:Q or :math:P is applied to :math:C.

:math:\mathrm{trans} = \texttt{'C'}

:math:Q^\mathrm{H} or :math:P^\mathrm{H} is applied to :math:C.

**k** : int
If :math:\mathrm{vect} = \texttt{'Q'}, the number of columns in the original matrix :math:A.

If :math:\mathrm{vect} = \texttt{'P'}, the number of rows in the original matrix :math:A.

**a** : complex, array-like, shape :math:\left(:, :\right)
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\mathrm{vect}=\texttt{'Q'}: :math:\textit{r}; if :math:\mathrm{vect}=\texttt{'P'}: :math:\min\left(\textit{r},\mathrm{k}\right); otherwise: :math:0.

Note: the required extent for this argument in dimension 2 is determined as follows: if :math:\mathrm{vect}=\texttt{'Q'}: :math:\min\left(\textit{r},\mathrm{k}\right); if :math:\mathrm{vect}=\texttt{'P'}: :math:\textit{r}; otherwise: :math:0.

Details of the vectors which define the elementary reflectors, as returned by :meth:zgebrd.

**tau** : complex, array-like, shape :math:\left(\min\left(\textit{r},\mathrm{k}\right)\right)
Further details of the elementary reflectors, as returned by :meth:zgebrd in its argument :math:\textit{tauq} if :math:\mathrm{vect} = \texttt{'Q'}, or in its argument :math:\textit{taup} if :math:\mathrm{vect} = \texttt{'P'}.

**c** : complex, array-like, shape :math:\left(m, n\right)
The matrix :math:C.

**Returns**
**c** : complex, ndarray, shape :math:\left(m, n\right)
:math:\mathrm{c} is overwritten by :math:QC or :math:Q^\mathrm{H}C or :math:CQ or :math:C^\mathrm{H}Q or :math:PC or :math:P^\mathrm{H}C or :math:CP or :math:C^\mathrm{H}P as specified by :math:\mathrm{vect}, :math:\mathrm{side} and :math:\mathrm{trans}.

.. _f08ku-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{vect}.

Constraint: :math:\mathrm{vect} = \texttt{'Q'} or :math:\texttt{'P'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{side}.

Constraint: :math:\mathrm{side} = \texttt{'L'} or :math:\texttt{'R'}.

(errno :math:-3)
On entry, error in parameter :math:\mathrm{trans}.

Constraint: :math:\mathrm{trans} = \texttt{'N'} or :math:\texttt{'C'}.

(errno :math:-4)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

(errno :math:-5)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

(errno :math:-6)
On entry, error in parameter :math:\mathrm{k}.

Constraint: :math:\mathrm{k}\geq 0.

.. _f08ku-py2-py-notes:

**Notes**
zunmbr is intended to be used after a call to :meth:zgebrd, which reduces a complex rectangular matrix :math:A to real bidiagonal form :math:B by a unitary transformation: :math:A = QBP^\mathrm{H}. :meth:zgebrd represents the matrices :math:Q and :math:P^\mathrm{H} as products of elementary reflectors.

This function may be used to form one of the matrix products

.. math::
QC,Q^\mathrm{H}C,CQ,CQ^\mathrm{H},PC,P^\mathrm{H}C,CP\text{ or }CP^\mathrm{H}\text{,}

overwriting the result on :math:C (which may be any complex rectangular matrix).

.. _f08ku-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 zgejsv(joba, jobu, jobv, jobr, jobt, jobp, a):
r"""
zgejsv computes the singular value decomposition (SVD) of a real :math:m\times n matrix :math:A, where :math:m\geq n, and optionally computes the left and/or right singular vectors. zgejsv implements the preconditioned Jacobi SVD of Drmač and Veselić (2008a) and Drmač and Veselić (2008b).
This is an expert version of the Jacobi SVD function :meth:zgesvj that employs preprocessing and preconditioning to improve the accuracy of results for extremely ill-conditioned matrices.
In most cases :meth:zgesvj, employing fast scaled rotations and de Rijk's pivoting strategy, is sufficient and is simpler to use.
Also consider using :meth:zgesvd or :meth:zgesdd which are much simpler to use and also handle the case :math:m < n.

.. _f08kv-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08kvf.html

.. _f08kv-py2-py-parameters:

**Parameters**
**joba** : str, length 1
Specifies the form of pivoting for the :math:QR factorization stage; whether an estimate of the condition number of the scaled matrix is required; and the form of rank reduction that is performed.

:math:\mathrm{joba} = \texttt{'C'}

The initial :math:QR factorization of the input matrix is performed with column pivoting; no estimate of condition number is computed; and, the rank is reduced by only the underflowed part of the triangular factor :math:R. This option works well (high relative accuracy) if :math:A can be written in the form :math:A = BD, with well-conditioned :math:B and arbitrary diagonal matrix :math:D. The accuracy cannot be spoiled by column scaling. The accuracy of the computed output depends on the condition of :math:B, and the procedure attempts to achieve the best theoretical accuracy.

:math:\mathrm{joba} = \texttt{'E'}

Computation as with :math:\mathrm{joba} = \texttt{'C'} with an additional estimate of the condition number of :math:B. It provides a realistic error bound.

:math:\mathrm{joba} = \texttt{'F'}

The initial :math:QR factorization of the input matrix is performed with full row and column pivoting; no estimate of condition number is computed; and, the rank is reduced by only the underflowed part of the triangular factor :math:R. If :math:A = D_1\times C\times D_2 with ill-conditioned diagonal scalings :math:D_1, :math:D_2, and well-conditioned matrix :math:C, this option gives higher accuracy than the :math:\mathrm{joba} = \texttt{'C'} option. If the structure of the input matrix is not known, and relative accuracy is desirable, then this option is advisable.

:math:\mathrm{joba} = \texttt{'G'}

Computation as with :math:\mathrm{joba} = \texttt{'F'} with an additional estimate of the condition number of :math:B, where :math:A = DB (i.e., :math:B = C\times D_2). If :math:A has heavily weighted rows, then using this condition number gives too pessimistic an error bound.

:math:\mathrm{joba} = \texttt{'A'}

Computation as with :math:\mathrm{joba} = \texttt{'C'} except in the treatment of rank reduction. In this case, small singular values are to be considered as noise and, if found, the matrix is treated as numerically rank deficient. The computed SVD, :math:A = U\Sigma V^\mathrm{H}, is such that the relative residual norm (when comparing against :math:A) is of the order :math:\mathrm{O}\left(m\right)\times \epsilon, where :math:\epsilon is machine precision. This gives the procedure licence to discard (set to zero) all singular values below :math:n\times \epsilon \times \left\lVert A\right\rVert.

:math:\mathrm{joba} = \texttt{'R'}

Similar to :math:\mathrm{joba} = \texttt{'A'}. The rank revealing property of the initial :math:QR factorization is used to reveal (using the upper triangular factor) a gap, :math:\sigma_{{r+1}} < \epsilon \sigma_r, in which case the numerical rank is declared to be :math:r. The SVD is computed with absolute error bounds, but more accurately than with :math:\mathrm{joba} = \texttt{'A'}.

**jobu** : str, length 1
Specifies options for computing the left singular vectors :math:U.

:math:\mathrm{jobu} = \texttt{'U'}

The first :math:n left singular vectors (columns of :math:U) are computed and returned in the array :math:\mathrm{u}.

:math:\mathrm{jobu} = \texttt{'F'}

All :math:m left singular vectors are computed and returned in the array :math:\mathrm{u}.

:math:\mathrm{jobu} = \texttt{'W'}

No left singular vectors are computed, but the array :math:\mathrm{u} (with :math:\textit{ldu}\geq m and second dimension at least :math:\textit{n}) is available as workspace for computing right singular values. See the description of :math:\mathrm{u}.

:math:\mathrm{jobu} = \texttt{'N'}

No left singular vectors are computed. :math:\mathrm{u} is not referenced when :math:\mathrm{jobv} = \texttt{'W'} or :math:\texttt{'N'}.

**jobv** : str, length 1
Specifies options for computing the right singular vectors :math:V.

:math:\mathrm{jobv} = \texttt{'V'}

The :math:n right singular vectors (columns of :math:V) are computed and returned in the array :math:\mathrm{v}; Jacobi rotations are not explicitly accumulated.

:math:\mathrm{jobv} = \texttt{'J'}

The :math:n right singular vectors (columns of :math:V) are computed and returned in the array :math:\mathrm{v}, but they are computed as the product of Jacobi rotations. This option is allowed only if :math:\mathrm{jobu} = \texttt{'U'} or :math:\texttt{'F'}, i.e., in computing the full SVD.

This is equivalent to multiplying the input matrix, on the right, by the matrix :math:V.

:math:\mathrm{jobv} = \texttt{'W'}

No right singular values are computed, but the array :math:\mathrm{v} (with :math:\textit{ldv}\geq n and second dimension at least :math:\textit{n}) is available as workspace for computing left singular values. See the description of :math:\mathrm{v}.

:math:\mathrm{jobv} = \texttt{'N'}

No right singular vectors are computed. :math:\mathrm{v} is not referenced when :math:\mathrm{jobu} = \texttt{'W'} or :math:\texttt{'N'} or :math:\mathrm{jobt} = \texttt{'N'} or :math:m\neq n.

**jobr** : str, length 1
Specifies the conditions under which columns of :math:A are to be set to zero. This effectively specifies a lower limit on the range of singular values; any singular values below this limit are (through column zeroing) set to zero. If :math:A\neq 0 is scaled so that the largest column (in the Euclidean norm) of :math:cA is equal to the square root of the overflow threshold, then :math:\mathrm{jobr} allows the function to kill columns of :math:A whose norm in :math:cA is less than :math:\sqrt{\textit{sfmin}} (for :math:\mathrm{jobr} = \texttt{'R'}), or less than :math:\textit{sfmin}/\epsilon (otherwise). :math:\textit{sfmin} is the safe range parameter, as returned by function :meth:machine.real_safe <naginterfaces.library.machine.real_safe>.

:math:\mathrm{jobr} = \texttt{'N'}

Only set to zero those columns of :math:A for which the norm of corresponding column of :math:cA < \textit{sfmin}/\epsilon, that is, those columns that are effectively zero (to machine precision) anyway. If the condition number of :math:A is greater than the overflow threshold :math:\lambda, where :math:\lambda is the value returned by :meth:machine.real_largest <naginterfaces.library.machine.real_largest>, you are recommended to use function :meth:zgesvj.

:math:\mathrm{jobr} = \texttt{'R'}

Set to zero those columns of :math:A for which the norm of the corresponding column of :math:cA < \sqrt{\textit{sfmin}}. This approximately represents a restricted range for :math:\sigma \left(cA\right) of :math:\left[\sqrt{\textit{sfmin}}, \sqrt{\lambda }\right].

For computing the singular values in the full range from the safe minimum up to the overflow threshold use :meth:zgesvj.

Suggested value: :math:\mathrm{jobr} = \texttt{'R'}.

**jobt** : str, length 1
Specifies, in the case :math:n = m, whether the function is permitted to use the conjugate transpose of :math:A for improved efficiency. If the matrix is square, then the procedure may use :math:A^\mathrm{H} if it seems to be better with respect to convergence. If the matrix is not square, :math:\mathrm{jobt} is ignored. The decision is based on two values of entropy over the adjoint orbit of :math:A^\mathrm{H}A. See the descriptions of :math:\mathrm{rworkb} and :math:\mathrm{rworkb}.

:math:\mathrm{jobt} = \texttt{'T'}

If :math:n = m, perform an entropy test and, if the test indicates possibly faster convergence of the Jacobi process when using :math:A^\mathrm{H}, then form the conjugate transpose :math:A^\mathrm{H}. If :math:A is replaced with :math:A^\mathrm{H}, then the row pivoting is included automatically.

:math:\mathrm{jobt} = \texttt{'N'}

No entropy test and no transposition is performed.

The option :math:\mathrm{jobt} = \texttt{'T'} can be used to compute only the singular values, or the full SVD (:math:U, :math:\Sigma and :math:V).

In the case where only one set of singular vectors (:math:U or :math:V) is required, the caller must still provide both :math:\mathrm{u} and :math:\mathrm{v}, as one of the matrices is used as workspace if the matrix :math:A is transposed.

See the descriptions of :math:\mathrm{u} and :math:\mathrm{v}.

**jobp** : str, length 1
Specifies whether the function should be allowed to introduce structured perturbations to drown denormalized numbers. For details see Drmač and Veselić (2008a) and Drmač and Veselić (2008b). For the sake of simplicity, these perturbations are included only when the full SVD or only the singular values are requested.

:math:\mathrm{jobp} = \texttt{'P'}

Introduce perturbation if :math:A is found to be very badly scaled (introducing denormalized numbers).

:math:\mathrm{jobp} = \texttt{'N'}

Do not perturb.

**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 contents of :math:\mathrm{a} are overwritten.

**sva** : float, ndarray, shape :math:\left(n\right)
The, possibly scaled, singular values of :math:A.

The singular values of :math:A are :math:\sigma_{\textit{i}} = \alpha \times \mathrm{sva}[\textit{i}-1], for :math:\textit{i} = 1,2,\ldots,n, where :math:\alpha = \mathrm{rworkb}/\mathrm{rworkb}.

Normally :math:\alpha = 1 and no scaling is required to obtain the singular values.

However, if the largest singular value of :math:A overflows or if small singular values have been saved from underflow by scaling the input matrix :math:A, then :math:\alpha \neq 1.

If :math:\mathrm{jobr} = \texttt{'R'}, then some of the singular values may be returned as exact zeros because they are below the numerical rank threshold or are denormalized numbers.

**u** : complex, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobu} = \texttt{'U'}, :math:\mathrm{u} contains the :math:m\times n matrix of left singular vectors.

If :math:\mathrm{jobu} = \texttt{'F'}, :math:\mathrm{u} contains the :math:m\times m matrix of left singular vectors, including an orthonormal basis of the orthogonal complement of Range(:math:A).

:math:\mathrm{u} is not referenced when :math:\mathrm{jobu} = \texttt{'W'} or :math:\texttt{'N'} and one of the following is satisfied:

:math:\mathrm{jobv} = \texttt{'W'} or :math:\texttt{'N'}, or

:math:n = 1, or

:math:A is the zero matrix.

**v** : complex, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobv} = \texttt{'V'} or :math:\texttt{'J'}, :math:\mathrm{v} contains the :math:n\times n matrix of right singular vectors.

:math:\mathrm{v} is not referenced when :math:\mathrm{jobv} = \texttt{'W'} or :math:\texttt{'N'} and one of the following is satisfied:

:math:\mathrm{jobu} = \texttt{'U'} or :math:\texttt{'F'} and :math:\mathrm{jobt} = \texttt{'T'}, or

:math:n = 1, or

:math:A is the zero matrix.

**rworkb** : float, ndarray, shape :math:\left(7\right)
Contains information about the completed job.

:math:\mathrm{rworkb}

:math:\alpha = \mathrm{rworkb}/\mathrm{rworkb} is the scaling factor such that :math:\sigma_{\textit{i}} = \alpha \times \mathrm{sva}[\textit{i}-1], for :math:\textit{i} = 1,2,\ldots,n, are the computed singular values of :math:A. See the description of :math:\mathrm{sva}.

:math:\mathrm{rworkb}

See the description of :math:\mathrm{rworkb}.

:math:\mathrm{rworkb}

:math:\textit{sconda}, an estimate for the condition number of column equilibrated :math:A (if :math:\mathrm{joba} = \texttt{'E'} or :math:\texttt{'G'}). :math:\textit{sconda} is an estimate of :math:\sqrt{\left(\left\lVert \left(R^\mathrm{T}R\right)^{-1}\right\rVert_1\right)}. It is computed using :meth:lapacklin.dpocon <naginterfaces.library.lapacklin.dpocon>. It satisfies :math:n^{{-\frac{1}{4}}}\times \textit{sconda}\leq \left\lVert R^{-1}\right\rVert_2\leq n^{\frac{1}{4}}\times \textit{sconda} where :math:R is the triangular factor from the :math:QR factorization of :math:A. However, if :math:R is truncated and the numerical rank is determined to be strictly smaller than :math:n, :math:\textit{sconda} is returned as :math:-1, thus indicating that the smallest singular values might be lost.

If the full SVD is needed, and you are familiar with the details of the method, the following two condition numbers are useful for the analysis of the algorithm.

:math:\mathrm{rworkb}

An estimate of the scaled condition number of the triangular factor in the first :math:QR factorization.

:math:\mathrm{rworkb}

An estimate of the scaled condition number of the triangular factor in the second :math:QR factorization.

The following two parameters are computed if :math:\mathrm{jobt} = \texttt{'T'}.

:math:\mathrm{rworkb}

The entropy of :math:A^\mathrm{T}A: this is the Shannon entropy of :math:\mathrm{diag}\left({A^\mathrm{T}A}\right)/\mathrm{trace}\left({A^\mathrm{T}A}\right) taken as a point in the probability simplex.

:math:\mathrm{rworkb}

The entropy of :math:AA^\mathrm{T}.

**iworkb** : None or int, ndarray, shape :math:\left(:\right)
Contains information about the completed job.

:math:\mathrm{iworkb}

The numerical rank of :math:A determined after the initial :math:QR factorization with pivoting. See the descriptions of :math:\mathrm{joba} and :math:\mathrm{jobr}.

:math:\mathrm{iworkb}

The number of computed nonzero singular values.

:math:\mathrm{iworkb}

If nonzero, a warning message. If :math:\mathrm{iworkb} = 1, then some of the column norms of :math:A were denormalized (tiny) numbers. The requested high accuracy is not warranted by the data.

.. _f08kv-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{joba}.

Constraint: :math:\mathrm{joba} = \texttt{'C'}, :math:\texttt{'E'}, :math:\texttt{'F'}, :math:\texttt{'G'}, :math:\texttt{'A'} or :math:\texttt{'R'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{jobu}.

Constraint: :math:\mathrm{jobu} = \texttt{'U'}, :math:\texttt{'F'}, :math:\texttt{'W'} or :math:\texttt{'N'}.

(errno :math:-3)
On entry, error in parameter :math:\mathrm{jobv}.

Constraint: :math:\mathrm{jobv} = \texttt{'V'}, :math:\texttt{'J'}, :math:\texttt{'W'} or :math:\texttt{'N'}.

(errno :math:-3)
On entry, error in parameter :math:\mathrm{jobv}.

Constraint: :math:\mathrm{jobv} \neq \texttt{'J'}.

(errno :math:-4)
On entry, error in parameter :math:\mathrm{jobr}.

Constraint: :math:\mathrm{jobr} = \texttt{'N'} or :math:\texttt{'R'}.

(errno :math:-5)
On entry, error in parameter :math:\mathrm{jobt}.

Constraint: :math:\mathrm{jobt} = \texttt{'T'} or :math:\texttt{'N'}.

(errno :math:-6)
On entry, error in parameter :math:\mathrm{jobp}.

Constraint: :math:\mathrm{jobp} = \texttt{'P'} or :math:\texttt{'N'}.

(errno :math:-7)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

(errno :math:-8)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:m\geq n\geq 0.

**Warns**
**NagAlgorithmicWarning**
(errno :math:i > 0)
zgejsv did not converge in the allowed number of iterations (:math:30). The computed values might be inaccurate.

.. _f08kv-py2-py-notes:

**Notes**
The SVD is written as

.. math::
A = U\Sigma V^\mathrm{H}\text{,}

where :math:\Sigma is an :math:m\times n matrix which is zero except for its :math:n diagonal elements, :math:U is an :math:m\times m unitary matrix, and :math:V is an :math:n\times n unitary matrix.
The diagonal elements of :math:\Sigma are the singular values of :math:A in descending order of magnitude.
The columns of :math:U and :math:V are the left and the right singular vectors of :math:A, respectively.

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

Drmač, Z and Veselić, K, 2008, New fast and accurate Jacobi SVD Algorithm I, SIAM J. Matrix Anal. Appl. (29 4)

Drmač, Z and Veselić, K, 2008, New fast and accurate Jacobi SVD Algorithm II, SIAM J. Matrix Anal. Appl. (29 4)

Golub, G H and Van Loan, C F, 1996, Matrix Computations, (3rd Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError

[docs]def zgesvj(joba, jobu, jobv, a, mv, v, ctol):
r"""
zgesvj computes the one-sided Jacobi singular value decomposition (SVD) of a complex :math:m\times n, general or triangular, matrix :math:A, :math:m\geq n, with fast scaled rotations and de Rijk’s pivoting, optionally computing the left and/or right singular vectors.
For :math:m < n, the functions :meth:zgesvd or :meth:zgesdd may be used.

.. _f08kw-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08kwf.html

.. _f08kw-py2-py-parameters:

**Parameters**
**joba** : str, length 1
Specifies the structure of matrix :math:A.

:math:\mathrm{joba} = \texttt{'L'}

The input matrix :math:A is lower triangular.

:math:\mathrm{joba} = \texttt{'U'}

The input matrix :math:A is upper triangular.

:math:\mathrm{joba} = \texttt{'G'}

The input matrix :math:A is a general :math:m\times n matrix, :math:m\geq n.

**jobu** : str, length 1
Specifies whether to compute the left singular vectors and if so whether you want to control their numerical orthogonality threshold.

:math:\mathrm{jobu} = \texttt{'U'}

The left singular vectors corresponding to the nonzero singular values are computed and returned in the leading columns of :math:\mathrm{a}. See more details in the description of :math:\mathrm{a}. The numerical orthogonality threshold is set to approximately :math:\textit{tol} = \sqrt{m}\times \epsilon, where :math:\epsilon is the machine precision.

:math:\mathrm{jobu} = \texttt{'C'}

Analogous to :math:\mathrm{jobu} = \texttt{'U'}, except that you can control the level of numerical orthogonality of the computed left singular vectors. The orthogonality threshold is set to :math:\textit{tol} = \mathrm{ctol}\times \epsilon. The option :math:\mathrm{jobu} = \texttt{'C'} can be used if :math:m\times \epsilon is a satisfactory orthogonality of the computed left singular vectors, so :math:\mathrm{ctol} = m could save a few sweeps of Jacobi rotations. See the descriptions of :math:\mathrm{a} and :math:\mathrm{ctol}.

:math:\mathrm{jobu} = \texttt{'N'}

The matrix :math:U is not computed. However, see the description of :math:\mathrm{a}.

**jobv** : str, length 1
Specifies whether and how to compute the right singular vectors.

:math:\mathrm{jobv} = \texttt{'V'}

The matrix :math:V is computed and returned in the array :math:\mathrm{v}.

:math:\mathrm{jobv} = \texttt{'A'}

The Jacobi rotations are applied to the leading :math:m_v\times n part of the array :math:\mathrm{v}. In other words, the right singular vector matrix :math:V is not computed explicitly, instead it is applied to an :math:m_v\times n matrix initially stored in the first :math:\mathrm{mv} rows of :math:\mathrm{v}.

:math:\mathrm{jobv} = \texttt{'N'}

The matrix :math:V is not computed and the array :math:\mathrm{v} is not referenced.

**a** : complex, array-like, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:A.

**mv** : int
If :math:\mathrm{jobv} = \texttt{'A'}, the product of Jacobi rotations is applied to the first :math:m_v rows of :math:\mathrm{v}.

If :math:\mathrm{jobv} \neq \texttt{'A'}, :math:\mathrm{mv} is ignored.

See the description of :math:\mathrm{jobv}.

**v** : complex, array-like, shape :math:\left(:, :\right)
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\mathrm{jobv}=\texttt{'V'}: :math:n; if :math:\mathrm{jobv}=\texttt{'A'}: :math:\mathrm{mv}; otherwise: :math:1.

Note: the required extent for this argument in dimension 2 is determined as follows: if :math:\mathrm{jobv}\text{ in } (\texttt{'V'}, \texttt{'A'}): :math:n; otherwise: :math:1.

If :math:\mathrm{jobv} = \texttt{'A'}, :math:\mathrm{v} must contain an :math:m_v\times n matrix to be premultiplied by the matrix :math:V of right singular vectors.

**ctol** : float
If :math:\mathrm{jobu} = \texttt{'C'}, :math:\mathrm{ctol} = \textit{ctol}, the threshold for convergence. The process stops if all columns of :math:A are mutually orthogonal up to :math:\textit{ctol}\times \epsilon. It is required that :math:\textit{ctol}\geq 1, i.e., it is not possible to force the function to obtain orthogonality below :math:\epsilon. :math:\textit{ctol} greater than :math:1/\epsilon is meaningless, where :math:\epsilon is the machine precision.

**Returns**
**a** : complex, ndarray, shape :math:\left(m, n\right)
The matrix :math:U containing the left singular vectors of :math:A.

If :math:\mathrm{jobu} = \texttt{'U'} or :math:\texttt{'C'}

if :math:\textit{errno} = 0

:math:\mathrm{rank}\left(A\right) unitary columns of :math:U are returned in the leading :math:\mathrm{rank}\left(A\right) columns of the array :math:\mathrm{a}. Here :math:\mathrm{rank}\left(A\right)\leq n is the number of computed singular values of :math:A that are above the safe range parameter, as returned by :meth:machine.real_safe <naginterfaces.library.machine.real_safe>. The singular vectors corresponding to underflowed or zero singular values are not computed. The value of :math:\mathrm{rank}\left(A\right) is returned by rounding :math:\mathrm{rwork} to the nearest whole number. Also see the descriptions of :math:\mathrm{sva} and :math:\mathrm{rwork}. The computed columns of :math:U are mutually numerically unitary up to approximately :math:\textit{tol} = \sqrt{m}\times \epsilon; or :math:\textit{tol} = \mathrm{ctol}\times \epsilon (:math:\mathrm{jobu} = \texttt{'C'}), where :math:\epsilon is the machine precision, see the description of :math:\mathrm{jobu}.

if :math:\textit{errno} > 0

zgesvj did not converge in :math:30 iterations (sweeps). In this case, the computed columns of :math:U may not be unitary up to :math:\textit{tol}. The output :math:U (stored in :math:\mathrm{a}), :math:\Sigma (given by the computed singular values in :math:\mathrm{sva}) and :math:V is still a decomposition of the input matrix :math:A in the sense that the residual :math:\left\lVert A-\alpha \times U\times \Sigma \times V^\mathrm{H}\right\rVert_2/\left\lVert A\right\rVert_2 is small, where :math:\alpha is the value returned in :math:\mathrm{rwork}.

If :math:\mathrm{jobu} = \texttt{'N'}

if :math:\textit{errno} = 0

Note that the left singular vectors are 'for free' in the one-sided Jacobi SVD algorithm. However, if only the singular values are needed, the level of numerical orthogonality of :math:U is not an issue and iterations are stopped when the columns of the iterated matrix are numerically unitary up to approximately :math:m\times \epsilon. Thus, on exit, :math:\mathrm{a} contains the columns of :math:U scaled with the corresponding singular values.

if :math:\textit{errno} > 0

zgesvj did not converge in :math:30 iterations (sweeps).

**sva** : float, ndarray, shape :math:\left(n\right)
The, possibly scaled, singular values of :math:A.

If :math:\textit{errno} = 0

The singular values of :math:A are :math:\sigma_{\textit{i}} = \alpha \times \mathrm{sva}[\textit{i}-1], for :math:\textit{i} = 1,2,\ldots,n, where :math:\alpha is the scale factor stored in :math:\mathrm{rwork}. Normally :math:\alpha = 1, however, if some of the singular values of :math:A might underflow or overflow, then :math:\alpha \neq 1 and the scale factor needs to be applied to obtain the singular values.

If :math:\textit{errno} > 0

zgesvj did not converge in :math:30 iterations and :math:\alpha \times \mathrm{sva} may not be accurate.

**v** : complex, ndarray, shape :math:\left(:, :\right)
The right singular vectors of :math:A.

If :math:\mathrm{jobv} = \texttt{'V'}, :math:\mathrm{v} contains the :math:n\times n matrix of the right singular vectors.

If :math:\mathrm{jobv} = \texttt{'A'}, :math:\mathrm{v} contains the product of the computed right singular vector matrix and the initial matrix in the array :math:\mathrm{v}.

If :math:\mathrm{jobv} = \texttt{'N'}, :math:\mathrm{v} is not referenced.

**rwork** : float, ndarray, shape :math:\left(6\right)
Contains information about the completed job.

:math:\mathrm{rwork}

The scaling factor, :math:\alpha, such that :math:\sigma_{\textit{i}} = \alpha \times \mathrm{sva}[\textit{i}-1], for :math:\textit{i} = 1,2,\ldots,n, are the computed singular values of :math:A. (See the description of :math:\mathrm{sva}.)

:math:\mathrm{rwork}

:math:\mathrm{nint}\left(\mathrm{rwork}\right) gives the number of the computed nonzero singular values.

:math:\mathrm{rwork}

:math:\mathrm{nint}\left(\mathrm{rwork}\right) gives the number of the computed singular values that are larger than the underflow threshold.

:math:\mathrm{rwork}

:math:\mathrm{nint}\left(\mathrm{rwork}\right) gives the number of iterations (sweeps of Jacobi rotations) needed for numerical convergence.

:math:\mathrm{rwork}

:math:\mathrm{max}_{{i\neq j}}\left\lvert \cos\left({A\left(:, i\right)}, {A\left(:, j\right)}\right)\right\rvert in the last iteration (sweep). This is useful information in cases when zgesvj did not converge, as it can be used to estimate whether the output is still useful and for subsequent analysis.

:math:\mathrm{rwork}

The largest absolute value over all sines of the Jacobi rotation angles in the last sweep. It can be useful for subsequent analysis.

.. _f08kw-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{joba}.

Constraint: :math:\mathrm{joba} = \texttt{'L'}, :math:\texttt{'U'} or :math:\texttt{'G'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{jobu}.

Constraint: :math:\mathrm{jobu} = \texttt{'U'}, :math:\texttt{'C'} or :math:\texttt{'N'}.

(errno :math:-3)
On entry, error in parameter :math:\mathrm{jobv}.

Constraint: :math:\mathrm{jobv} = \texttt{'V'}, :math:\texttt{'A'} or :math:\texttt{'N'}.

(errno :math:-4)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

(errno :math:-5)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:m\geq n\geq 0.

(errno :math:-9)
On entry, error in parameter :math:\mathrm{mv}.

Constraint: :math:\mathrm{mv}\geq 0.

(errno :math:-14)
On entry, error in parameter :math:\mathrm{ctol}.

Constraint: :math:\mathrm{ctol}\geq 1.0.

**Warns**
**NagAlgorithmicWarning**
(errno :math:i > 0)
zgesvj did not converge in the allowed number of iterations (:math:30), but its output might still be useful.

.. _f08kw-py2-py-notes:

**Notes**
The SVD is written as

.. math::
A = U\Sigma V^\mathrm{H}\text{,}

where :math:\Sigma is an :math:n\times n diagonal matrix, :math:U is an :math:m\times n unitary matrix, and :math:V is an :math:n\times n unitary matrix.
The diagonal elements of :math:\Sigma are the singular values of :math:A in descending order of magnitude.
The columns of :math:U and :math:V are the left and the right singular vectors of :math:A, respectively.

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

Drmač, Z and Veselić, K, 2008, New fast and accurate Jacobi SVD Algorithm I, SIAM J. Matrix Anal. Appl. (29 4)

Drmač, Z and Veselić, K, 2008, New fast and accurate Jacobi SVD Algorithm II, SIAM J. Matrix Anal. Appl. (29 4)

Golub, G H and Van Loan, C F, 1996, Matrix Computations, (3rd Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError

[docs]def zgesvdx(jobu, jobvt, erange, a, vl, vu, il, iu):
r"""
zgesvdx computes the singular value decomposition (SVD) of a complex :math:m\times n matrix :math:A, optionally computing the left and/or right singular vectors.
All singular values or a selected set of singular values may be computed.

.. _f08kz-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08kzf.html

.. _f08kz-py2-py-parameters:

**Parameters**
**jobu** : str, length 1
Specifies options for computing all or part of the matrix :math:U.

:math:\mathrm{jobu} = \texttt{'V'}

The :math:\mathrm{ns} columns of :math:U, as specified by :math:\mathrm{erange}, are returned in array :math:\mathrm{u}.

:math:\mathrm{jobu} = \texttt{'N'}

No columns of :math:U (no left singular vectors) are computed.

**jobvt** : str, length 1
Specifies options for computing all or part of the matrix :math:V^\mathrm{T}.

:math:\mathrm{jobvt} = \texttt{'V'}

The :math:\mathrm{ns} rows of :math:V^\mathrm{T}, as specified by :math:\mathrm{erange}, are returned in the array :math:\mathrm{vt}.

:math:\mathrm{jobvt} = \texttt{'N'}

No rows of :math:V^\mathrm{T} (no right singular vectors) are computed.

**erange** : str, length 1
Indicates which singular values should be returned.

:math:\mathrm{erange} = \texttt{'A'}

All singular values will be found.

:math:\mathrm{erange} = \texttt{'V'}

All singular values in the half-open interval :math:\left(\mathrm{vl}, \mathrm{vu}\right] will be found.

:math:\mathrm{erange} = \texttt{'I'}

The :math:\mathrm{il}\ th through :math:\mathrm{iu}\ th singular values will be found.

**a** : complex, array-like, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:A.

**vl** : float
If :math:\mathrm{erange} = \texttt{'V'}, the lower bound of the interval to be searched for singular values.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'I'}, :math:\mathrm{vl} is not referenced.

**vu** : float
If :math:\mathrm{erange} = \texttt{'V'}, the upper bound of the interval to be searched for singular values.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'I'}, :math:\mathrm{vu} is not referenced.

**il** : int
If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{il} and :math:\mathrm{iu} specify the indices (in ascending order) of the smallest and largest singular values to be returned, respectively.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}, :math:\mathrm{il} and :math:\mathrm{iu} are not referenced.

**iu** : int
If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{il} and :math:\mathrm{iu} specify the indices (in ascending order) of the smallest and largest singular values to be returned, respectively.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}, :math:\mathrm{il} and :math:\mathrm{iu} are not referenced.

**Returns**
**a** : complex, ndarray, shape :math:\left(m, n\right)
If :math:\mathrm{jobu} \neq \texttt{'N'} and :math:\mathrm{jobvt} \neq \texttt{'N'}, the contents of :math:\mathrm{a} are destroyed.

**ns** : int
The total number of singular values found. :math:0\leq \mathrm{ns}\leq \mathrm{min}\left(m, n\right).

If :math:\mathrm{erange} = \texttt{'A'}, :math:\mathrm{ns} = \mathrm{min}\left(m, n\right).

If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{ns} = \mathrm{iu}-\mathrm{il}+1.

If :math:\mathrm{erange} = \texttt{'V'} then the value of :math:\mathrm{ns} is not known in advance and so an upper limit should be used when specifying the dimensions of array :math:\mathrm{u}, e.g., :math:\mathrm{min}\left(m, n\right).

**s** : float, ndarray, shape :math:\left(\min\left(m,n\right)\right)
The singular values of :math:A, sorted so that :math:\mathrm{s}[i-1]\geq \mathrm{s}[i].

**u** : None or complex, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobu} = \texttt{'V'}, :math:\mathrm{u} contains the first :math:\mathrm{ns} columns of :math:U (the left singular vectors, stored column-wise).

If :math:\mathrm{jobu} = \texttt{'N'}, :math:\mathrm{u} is not referenced.

**vt** : None or complex, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobvt} = \texttt{'V'}, :math:\mathrm{vt} contains the first :math:\mathrm{ns} rows of :math:V^\mathrm{H} (the right singular vectors, stored row-wise).

If :math:\mathrm{jobvt} = \texttt{'N'}, :math:\mathrm{vt} is not referenced.

**rworkb** : float, ndarray, shape :math:\left(\min\left(m,n\right)\right)
If :math:\mathrm{errno} > 0, :math:\mathrm{rworkb}[1:\mathrm{min}\left(m, n\right)] contains the unconverged superdiagonal elements of an upper bidiagonal matrix :math:B whose diagonal is in :math:\mathrm{s} (not necessarily sorted). :math:B satisfies :math:A = UBV^\mathrm{H}, so it has the same singular values as :math:A, and left and right singular vectors that are those of :math:A pre-multiplied by :math:U^\mathrm{H} and :math:V^\mathrm{H}.

**jfail** : int, ndarray, shape :math:\left(2\times \min\left(m,n\right)\right)
If :math:\mathrm{errno} > 0, :math:\mathrm{jfail} contains, in its first :math:k nonzero elements, the indices of the :math:k eigenvectors (associated with a left or right singular vector, see :meth:dbdsvdx) that failed to converge.

.. _f08kz-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{jobu}.

Constraint: :math:\mathrm{jobu} = \texttt{'V'} or :math:\texttt{'N'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{jobvt}.

Constraint: :math:\mathrm{jobvt} = \texttt{'V'} or :math:\texttt{'N'}.

(errno :math:-3)
On entry, error in parameter :math:\mathrm{erange}.

Constraint: :math:\mathrm{erange} = \texttt{'A'}, :math:\texttt{'V'} or :math:\texttt{'I'}.

(errno :math:-4)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

(errno :math:-5)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

(errno :math:-8)
On entry, error in parameter :math:\mathrm{vl}.

Constraint: :math:0.0\leq \mathrm{vl}.

(errno :math:-9)
On entry, error in parameter :math:\mathrm{vu}.

Constraint: :math:\mathrm{vl} < \mathrm{vu}.

(errno :math:-10)
On entry, error in parameter :math:\mathrm{il}.

(errno :math:-11)
On entry, error in parameter :math:\mathrm{iu}.

(errno :math:i > 0)
If zgesvdx did not converge, :math:\textit{errno} specifies how many superdiagonals of an intermediate bidiagonal form did not converge to zero.

.. _f08kz-py2-py-notes:

**Notes**
The SVD is written as

.. math::
A = U\Sigma V^\mathrm{H}\text{,}

where :math:\Sigma is an :math:m\times n matrix which is zero except for its :math:\mathrm{min}\left(m, n\right) diagonal elements, :math:U is an :math:m\times m unitary matrix, and :math:V is an :math:n\times n unitary matrix.
The diagonal elements of :math:\Sigma are the singular values of :math:A; they are complex and non-negative, and are returned in descending order.
The first :math:\mathrm{min}\left(m, n\right) columns of :math:U and :math:V are the left and right singular vectors of :math:A, respectively.

Note that the function returns :math:V^\mathrm{H}, not :math:V.

Alternative to computing all singular values of :math:A, a selected set can be computed.
The set is either those singular values lying in a given interval, :math:\sigma \in \left(v_l, v_u\right], or those whose index (counting from largest to smallest in magnitude) lies in a given range :math:1\leq i_l,\ldots,i_u\leq n.
In these cases, the corresponding left and right singular vectors can optionally be computed.

.. _f08kz-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 dgbbrd(vect, m, kl, ku, ab, c):
r"""
dgbbrd reduces a real :math:m\times n band matrix to upper bidiagonal form.

.. _f08le-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08lef.html

.. _f08le-py2-py-parameters:

**Parameters**
**vect** : str, length 1
Indicates whether the matrices :math:Q and/or :math:P^\mathrm{T} are generated.

:math:\mathrm{vect} = \texttt{'N'}

Neither :math:Q nor :math:P^\mathrm{T} is generated.

:math:\mathrm{vect} = \texttt{'Q'}

:math:Q is generated.

:math:\mathrm{vect} = \texttt{'P'}

:math:P^\mathrm{T} is generated.

:math:\mathrm{vect} = \texttt{'B'}

Both :math:Q and :math:P^\mathrm{T} are generated.

**m** : int
:math:m, the number of rows of the matrix :math:A.

**kl** : int
The number of subdiagonals, :math:k_l, within the band of :math:A.

**ku** : int
The number of superdiagonals, :math:k_u, within the band of :math:A.

**ab** : float, array-like, shape :math:\left(\mathrm{kl}+\mathrm{ku}+1, n\right)
The original :math:m\times n band matrix :math:A.

**c** : float, array-like, shape :math:\left(:, \textit{ncc}\right)
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\textit{ncc} > 0: :math:\mathrm{m}; if :math:\textit{ncc}=0: :math:1; otherwise: :math:0.

An :math:m\times n_C matrix :math:C.

**Returns**
**ab** : float, ndarray, shape :math:\left(\mathrm{kl}+\mathrm{ku}+1, n\right)
:math:\mathrm{ab} is overwritten by values generated during the reduction.

**d** : float, ndarray, shape :math:\left(\min\left(\mathrm{m},n\right)\right)
The diagonal elements of the bidiagonal matrix :math:B.

**e** : float, ndarray, shape :math:\left(\min\left(\mathrm{m},n\right)-1\right)
The superdiagonal elements of the bidiagonal matrix :math:B.

**q** : float, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{vect} = \texttt{'Q'} or :math:\texttt{'B'}, contains the :math:m\times m orthogonal matrix :math:Q.

If :math:\mathrm{vect} = \texttt{'N'} or :math:\texttt{'P'}, :math:\mathrm{q} is not referenced.

**pt** : float, ndarray, shape :math:\left(:, :\right)
The :math:n\times n orthogonal matrix :math:P^T, if :math:\mathrm{vect} = \texttt{'P'} or :math:\texttt{'B'}. If :math:\mathrm{vect} = \texttt{'N'} or :math:\texttt{'Q'}, :math:\mathrm{pt} is not referenced.

**c** : float, ndarray, shape :math:\left(:, \textit{ncc}\right)
:math:\mathrm{c} is overwritten by :math:Q^\mathrm{T}C. If :math:\textit{ncc} = 0, :math:\mathrm{c} is not referenced.

.. _f08le-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{vect}.

Constraint: :math:\mathrm{vect} = \texttt{'N'}, :math:\texttt{'Q'}, :math:\texttt{'P'} or :math:\texttt{'B'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{m}.

Constraint: :math:\mathrm{m}\geq 0.

(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{ncc}.

Constraint: :math:\textit{ncc}\geq 0.

(errno :math:-5)
On entry, error in parameter :math:\mathrm{kl}.

Constraint: :math:\mathrm{kl}\geq 0.

(errno :math:-6)
On entry, error in parameter :math:\mathrm{ku}.

Constraint: :math:\mathrm{ku}\geq 0.

.. _f08le-py2-py-notes:

**Notes**
dgbbrd reduces a real :math:m\times n band matrix to upper bidiagonal form :math:B by an orthogonal transformation: :math:A = QBP^\mathrm{T}.
The orthogonal matrices :math:Q and :math:P^\mathrm{T}, of order :math:m and :math:n respectively, are determined as a product of Givens rotation matrices, and may be formed explicitly by the function if required.
A matrix :math:C may also be updated to give :math:\tilde{C} = Q^\mathrm{T}C.

The function uses a vectorizable form of the reduction.
"""
raise NotImplementedError

[docs]def zgbbrd(vect, m, kl, ku, ab, c):
r"""
zgbbrd reduces a complex :math:m\times n band matrix to real upper bidiagonal form.

.. _f08ls-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08lsf.html

.. _f08ls-py2-py-parameters:

**Parameters**
**vect** : str, length 1
Indicates whether the matrices :math:Q and/or :math:P^\mathrm{H} are generated.

:math:\mathrm{vect} = \texttt{'N'}

Neither :math:Q nor :math:P^\mathrm{H} is generated.

:math:\mathrm{vect} = \texttt{'Q'}

:math:Q is generated.

:math:\mathrm{vect} = \texttt{'P'}

:math:P^\mathrm{H} is generated.

:math:\mathrm{vect} = \texttt{'B'}

Both :math:Q and :math:P^\mathrm{H} are generated.

**m** : int
:math:m, the number of rows of the matrix :math:A.

**kl** : int
The number of subdiagonals, :math:k_l, within the band of :math:A.

**ku** : int
The number of superdiagonals, :math:k_u, within the band of :math:A.

**ab** : complex, array-like, shape :math:\left(\mathrm{kl}+\mathrm{ku}+1, n\right)
The original :math:m\times n band matrix :math:A.

**c** : complex, array-like, shape :math:\left(:, \textit{ncc}\right)
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\textit{ncc} > 0: :math:\mathrm{m}; if :math:\textit{ncc}=0: :math:1; otherwise: :math:0.

An :math:m\times n_C matrix :math:C.

**Returns**
**ab** : complex, ndarray, shape :math:\left(\mathrm{kl}+\mathrm{ku}+1, n\right)
:math:\mathrm{ab} is overwritten by values generated during the reduction.

**d** : float, ndarray, shape :math:\left(\min\left(\mathrm{m},n\right)\right)
The diagonal elements of the bidiagonal matrix :math:B.

**e** : float, ndarray, shape :math:\left(\min\left(\mathrm{m},n\right)-1\right)
The superdiagonal elements of the bidiagonal matrix :math:B.

**q** : complex, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{vect} = \texttt{'Q'} or :math:\texttt{'B'}, contains the :math:m\times m unitary matrix :math:Q.

If :math:\mathrm{vect} = \texttt{'N'} or :math:\texttt{'P'}, :math:\mathrm{q} is not referenced.

**pt** : complex, ndarray, shape :math:\left(:, :\right)
The :math:n\times n unitary matrix :math:P^H, if :math:\mathrm{vect} = \texttt{'P'} or :math:\texttt{'B'}. If :math:\mathrm{vect} = \texttt{'N'} or :math:\texttt{'Q'}, :math:\mathrm{pt} is not referenced.

**c** : complex, ndarray, shape :math:\left(:, \textit{ncc}\right)
:math:\mathrm{c} is overwritten by :math:Q^\mathrm{H}C. If :math:\textit{ncc} = 0, :math:\mathrm{c} is not referenced.

.. _f08ls-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{vect}.

Constraint: :math:\mathrm{vect} = \texttt{'N'}, :math:\texttt{'Q'}, :math:\texttt{'P'} or :math:\texttt{'B'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{m}.

Constraint: :math:\mathrm{m}\geq 0.

(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{ncc}.

Constraint: :math:\textit{ncc}\geq 0.

(errno :math:-5)
On entry, error in parameter :math:\mathrm{kl}.

Constraint: :math:\mathrm{kl}\geq 0.

(errno :math:-6)
On entry, error in parameter :math:\mathrm{ku}.

Constraint: :math:\mathrm{ku}\geq 0.

.. _f08ls-py2-py-notes:

**Notes**
zgbbrd reduces a complex :math:m\times n band matrix to real upper bidiagonal form :math:B by a unitary transformation: :math:A = QBP^\mathrm{H}.
The unitary matrices :math:Q and :math:P^\mathrm{H}, of order :math:m and :math:n respectively, are determined as a product of Givens rotation matrices, and may be formed explicitly by the function if required.
A matrix :math:C may also be updated to give :math:\tilde{C} = Q^\mathrm{H}C.

The function uses a vectorizable form of the reduction.
"""
raise NotImplementedError

[docs]def dbdsvdx(uplo, jobz, erange, d, e, vl, vu, il, iu):
r"""
dbdsvdx computes all or selected singular values and, optionally, the corresponding left and right singular vectors of a real :math:n\times n (upper or lower) bidiagonal matrix :math:B.

.. _f08mb-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08mbf.html

.. _f08mb-py2-py-parameters:

**Parameters**
**uplo** : str, length 1
Indicates whether :math:B is upper or lower bidiagonal.

:math:\mathrm{uplo} = \texttt{'U'}

:math:B is upper bidiagonal.

:math:\mathrm{uplo} = \texttt{'L'}

:math:B is lower bidiagonal.

**jobz** : str, length 1
Indicates whether singular vectors are computed.

:math:\mathrm{jobz} = \texttt{'N'}

Only singular values are computed.

:math:\mathrm{jobz} = \texttt{'V'}

Singular values and singular vectors are computed.

**erange** : str, length 1
Indicates which singular values should be returned.

:math:\mathrm{erange} = \texttt{'A'}

All singular values will be found.

:math:\mathrm{erange} = \texttt{'V'}

All singular values in the half-open interval :math:\left(\mathrm{vl}, \mathrm{vu}\right] will be found.

:math:\mathrm{erange} = \texttt{'I'}

The :math:\mathrm{il}\ th through :math:\mathrm{iu}\ th singular values will be found.

**d** : float, array-like, shape :math:\left(n\right)
The diagonal elements :math:\boldsymbol{d} of the bidiagonal matrix :math:B.

**e** : float, array-like, shape :math:\left(n-1\right)
The :math:\left(n-1\right) off-diagonal elements :math:\boldsymbol{e} of the bidiagonal matrix :math:B.

**vl** : float
If :math:\mathrm{erange} = \texttt{'V'}, the lower bound of the interval to be searched for singular values.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'I'}, :math:\mathrm{vl} is not referenced.

**vu** : float
If :math:\mathrm{erange} = \texttt{'V'}, the upper bound of the interval to be searched for singular values.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'I'}, :math:\mathrm{vu} is not referenced.

**il** : int
If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{il} and :math:\mathrm{iu} specify the indices (in ascending order) of the smallest and largest singular values to be returned, respectively.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}, :math:\mathrm{il} and :math:\mathrm{iu} are not referenced.

**iu** : int
If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{il} and :math:\mathrm{iu} specify the indices (in ascending order) of the smallest and largest singular values to be returned, respectively.

If :math:\mathrm{erange} = \texttt{'A'} or :math:\texttt{'V'}, :math:\mathrm{il} and :math:\mathrm{iu} are not referenced.

**Returns**
**ns** : int
The total number of singular values found. :math:0\leq \mathrm{ns}\leq n.

If :math:\mathrm{erange} = \texttt{'A'}, :math:\mathrm{ns} = n.

If :math:\mathrm{erange} = \texttt{'I'}, :math:\mathrm{ns} = \mathrm{iu}-\mathrm{il}+1.

**s** : float, ndarray, shape :math:\left(n\right)
The first :math:\mathrm{ns} elements contain the selected singular values in ascending order.

**z** : float, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobz} = \texttt{'V'}, then if :math:\textit{errno} = 0 the first :math:\mathrm{ns} columns of :math:\mathrm{z} contain the singular vectors of the matrix :math:B corresponding to the selected singular values, with :math:U in rows :math:1 to :math:n and :math:V in rows :math:n+1 to :math:n\times 2.

.. _f08mb-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{jobz}.

Constraint: :math:\mathrm{jobz} = \texttt{'N'} or :math:\texttt{'V'}.

(errno :math:-3)
On entry, error in parameter :math:\mathrm{erange}.

Constraint: :math:\mathrm{erange} = \texttt{'A'}, :math:\texttt{'V'} or :math:\texttt{'I'}.

(errno :math:-4)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

(errno :math:-7)
On entry, error in parameter :math:\mathrm{vl}.

Constraint: :math:0.0\leq \mathrm{vl}.

(errno :math:-8)
On entry, error in parameter :math:\mathrm{vu}.

Constraint: :math:\mathrm{vl} < \mathrm{vu}.

(errno :math:-9)
On entry, error in parameter :math:\mathrm{il}.

(errno :math:-10)
On entry, error in parameter :math:\mathrm{iu}.

(errno :math:i > 0)
The algorithm failed to converge; :math:\langle\mathit{\boldsymbol{value}}\rangle eigenvectors of the associated eigenproblem did not converge. Their indices are stored in array :math:\textit{iwork}.

.. _f08mb-py2-py-notes:

**Notes**
dbdsvdx computes the singular value decomposition (SVD) of a real :math:n\times n (upper or lower) bidiagonal matrix :math:B as

.. math::
B = {USV^\mathrm{T}}\text{,}

where :math:S is a diagonal matrix with non-negative diagonal elements (the singular values of :math:B), and :math:U and :math:V^\mathrm{T} are orthogonal matrices.
The columns of :math:U and :math:V are the left and right singular vectors of :math:B, respectively.

Given an upper bidiagonal matrix :math:B with diagonal :math:\boldsymbol{d} = \begin{pmatrix}d_1&d_2&\ldots &d_n\end{pmatrix} and superdiagonal :math:\boldsymbol{e} = \begin{pmatrix}e_1&e_2&\ldots &e_{{N-1}}\end{pmatrix}, dbdsvdx computes the singular value decomposition of :math:B through the eigenvalues and eigenvectors of the :math:\left(n\times 2\right)\times \left(n\times 2\right) tridiagonal matrix

.. math::
\textit{TGK} = \begin{pmatrix}0&d_1&&&&\\d_1&0&e_1&&\\&e_1&0&d_2&&\\&&d_2&.&.\\&&&.&.\end{pmatrix}\text{.}

If :math:\left(s, u, v\right) is a singular triplet of :math:B with :math:\left\lVert u\right\rVert = \left\lVert v\right\rVert = 1, then :math:\left(s, q_1\right) and :math:\left({-s}, q_2\right), :math:\left\lVert q_1\right\rVert = \left\lVert q_2\right\rVert = 1, are eigenpairs of :math:\textit{TGK}, with :math:q_1 = \left(v_1, u_1, v_2, u_2, \ldots, v_n, u_n\right)/\sqrt{2}, and :math:q_2 = \left({-v}_1, u_1, {-v}_2, u_2, \ldots, {-v}_n, u_n\right)/\sqrt{2}.

Given a :math:\textit{TGK} matrix, you can either

(i) compute :math:{-s},{-v} and change signs so that the singular values (and corresponding vectors) are already in descending order (as in :meth:dgesvd) or

(#) compute :math:s,v and reorder the values (and corresponding vectors).

dbdsvdx implements \(i) by calling :meth:dstevx (bisection plus inverse iteration, to be replaced with a version of the Multiple Relative Robust Representation algorithm. (See Williams and Lang (2013).)

Alternative to computing all singular values of :math:B, a selected set can be computed.
The set is either those singular values lying in a given interval, :math:\sigma \in \left(v_l, v_u\right], or those whose index (counting from largest to smallest in magnitude) lies in a given range :math:1\leq i_l,\ldots,i_u\leq n.
In these cases, the corresponding left and right singular vectors can optionally be computed.

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

Williams, P and Lang, B, 2013, A framework for the :math:MR^3 Algorithm: theory and implementation, SIAM J. Sci. Comput. (35), 740--766
"""
raise NotImplementedError

[docs]def dbdsdc(uplo, compq, d, e):
r"""
dbdsdc computes the singular values and, optionally, the left and right singular vectors of a real :math:n\times n (upper or lower) bidiagonal matrix :math:B.

.. _f08md-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08mdf.html

.. _f08md-py2-py-parameters:

**Parameters**
**uplo** : str, length 1
Indicates whether :math:B is upper or lower bidiagonal.

:math:\mathrm{uplo} = \texttt{'U'}

:math:B is upper bidiagonal.

:math:\mathrm{uplo} = \texttt{'L'}

:math:B is lower bidiagonal.

**compq** : str, length 1
Specifies whether singular vectors are to be computed.

:math:\mathrm{compq} = \texttt{'N'}

Compute singular values only.

:math:\mathrm{compq} = \texttt{'P'}

Compute singular values and compute singular vectors in compact form.

:math:\mathrm{compq} = \texttt{'I'}

Compute singular values and singular vectors.

**d** : float, array-like, shape :math:\left(n\right)
The :math:n diagonal elements of the bidiagonal matrix :math:B.

**e** : float, array-like, shape :math:\left(n-1\right)
The :math:\left(n-1\right) off-diagonal elements of the bidiagonal matrix :math:B.

**Returns**
**d** : float, ndarray, shape :math:\left(n\right)
If no exception or warning is raised, the singular values of :math:B.

**u** : None or float, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{compq} = \texttt{'I'}, then if no exception or warning is raised, :math:\mathrm{u} contains the left singular vectors of the bidiagonal matrix :math:B.

If :math:\mathrm{compq} \neq \texttt{'I'}, :math:\mathrm{u} is not referenced.

**vt** : None or float, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{compq} = \texttt{'I'}, then if no exception or warning is raised, the rows of :math:\mathrm{vt} contain the right singular vectors of the bidiagonal matrix :math:B.

If :math:\mathrm{compq} \neq \texttt{'I'}, :math:\mathrm{vt} is not referenced.

**q** : None or float, ndarray, shape :math:\left(:\right)
If :math:\mathrm{compq} = \texttt{'P'}, then if no exception or warning is raised, :math:\mathrm{q} and :math:\mathrm{iq} contain the left and right singular vectors in a compact form, requiring :math:\mathrm{O}\left(n\mathrm{log2}\left(n\right)\right) space instead of :math:2\times n^2. In particular, :math:\mathrm{q} contains all the real data in the first :math:\textit{ldq} = n\times \left(11+2\times \textit{smlsiz}+8\times \mathrm{int}\left(\mathrm{log2}\left(n/\left(\textit{smlsiz}+1\right)\right)\right)\right) elements of :math:\mathrm{q}, where :math:\textit{smlsiz} is equal to the maximum size of the subproblems at the bottom of the computation tree (usually about :math:25).

If :math:\mathrm{compq} \neq \texttt{'P'}, :math:\mathrm{q} is not referenced.

**iq** : None or int, ndarray, shape :math:\left(:\right)
If :math:\mathrm{compq} = \texttt{'P'}, then if no exception or warning is raised, :math:\mathrm{q} and :math:\mathrm{iq} contain the left and right singular vectors in a compact form, requiring :math:\mathrm{O}\left(n\mathrm{log2}\left(n\right)\right) space instead of :math:2\times n^2. In particular, :math:\mathrm{iq} contains all integer data in the first :math:\textit{ldiq} = n\times \left(3+3\times \mathrm{int}\left(\mathrm{log2}\left(n/\left(\textit{smlsiz}+1\right)\right)\right)\right) elements of :math:\mathrm{iq}, where :math:\textit{smlsiz} is equal to the maximum size of the subproblems at the bottom of the computation tree (usually about :math:25).

If :math:\mathrm{compq} \neq \texttt{'P'}, :math:\mathrm{iq} is not referenced.

.. _f08md-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{compq}.

Constraint: :math:\mathrm{compq} = \texttt{'N'}, :math:\texttt{'P'} or :math:\texttt{'I'}.

(errno :math:-3)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

(errno :math:i > 0)
The algorithm failed to compute a singular value. The update process of divide-and-conquer failed.

.. _f08md-py2-py-notes:

**Notes**
dbdsdc computes the singular value decomposition (SVD) of the (upper or lower) bidiagonal matrix :math:B as

.. math::
B = {USV^\mathrm{T}}\text{,}

where :math:S is a diagonal matrix with non-negative diagonal elements :math:s_{{ii}} = s_i, such that

.. math::
s_1\geq s_2\geq \cdots \geq s_n\geq 0\text{,}

and :math:U and :math:V are orthogonal matrices.
The diagonal elements of :math:S are the singular values of :math:B and the columns of :math:U and :math:V are respectively the corresponding left and right singular vectors of :math:B.

When only singular values are required the function uses the :math:QR algorithm, but when singular vectors are required a divide and conquer method is used.
The singular values can optionally be returned in compact form, although currently no function is available to apply :math:U or :math:V when stored in compact form.

.. _f08md-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 dbdsqr(uplo, d, e, vt, u, c):
r"""
dbdsqr computes the singular value decomposition of a real upper or lower bidiagonal matrix, or of a real general matrix which has been reduced to bidiagonal form.

.. _f08me-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08mef.html

.. _f08me-py2-py-parameters:

**Parameters**
**uplo** : str, length 1
Indicates whether :math:B is an upper or lower bidiagonal matrix.

:math:\mathrm{uplo} = \texttt{'U'}

:math:B is an upper bidiagonal matrix.

:math:\mathrm{uplo} = \texttt{'L'}

:math:B is a lower bidiagonal matrix.

**d** : float, array-like, shape :math:\left(n\right)
The diagonal elements of the bidiagonal matrix :math:B.

**e** : float, array-like, shape :math:\left(\max\left(1,{n-1}\right)\right)
The off-diagonal elements of the bidiagonal matrix :math:B.

**vt** : float, array-like, shape :math:\left(:, \textit{ncvt}\right)
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\textit{ncvt} > 0: :math:n; otherwise: :math:1.

If :math:\textit{ncvt} > 0, :math:\mathrm{vt} must contain an :math:n\times \textit{ncvt} matrix. If the right singular vectors of :math:B are required, :math:\textit{ncvt} = n and :math:\mathrm{vt} must contain the unit matrix; if the right singular vectors of :math:A are required, :math:\mathrm{vt} must contain the orthogonal matrix :math:P^T returned by :meth:dorgbr with :math:{\textit{vect}} = \texttt{'P'}.

**u** : float, array-like, shape :math:\left(\textit{nru}, n\right)
If :math:\textit{nru} > 0, :math:\mathrm{u} must contain an :math:\textit{nru}\times n matrix. If the left singular vectors of :math:B are required, :math:\textit{nru} = n and :math:\mathrm{u} must contain the unit matrix; if the left singular vectors of :math:A are required, :math:\mathrm{u} must contain the orthogonal matrix :math:Q returned by :meth:dorgbr with :math:{\textit{vect}} = \texttt{'Q'}.

**c** : float, array-like, shape :math:\left(:, \textit{ncc}\right)
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\textit{ncc} > 0: :math:n; otherwise: :math:1.

The :math:n\times \textit{ncc} matrix :math:C if :math:\textit{ncc} > 0.

**Returns**
**d** : float, ndarray, shape :math:\left(n\right)
The singular values in decreasing order of magnitude, unless :math:\mathrm{errno} > 0 (in which case see :ref:Exceptions <f08me-py2-py-errors>).

**e** : float, ndarray, shape :math:\left(\max\left(1,{n-1}\right)\right)
:math:\mathrm{e} is overwritten, but if :math:\mathrm{errno} > 0 see :ref:Exceptions <f08me-py2-py-errors>.

**vt** : float, ndarray, shape :math:\left(:, \textit{ncvt}\right)
The :math:n\times \textit{ncvt} matrix :math:V^\mathrm{T} or :math:V^\mathrm{T}P^\mathrm{T} of right singular vectors, stored by rows.

If :math:\textit{ncvt} = 0, :math:\mathrm{vt} is not referenced.

**u** : float, ndarray, shape :math:\left(\textit{nru}, n\right)
The :math:\textit{nru}\times n matrix :math:U or :math:QU of left singular vectors, stored as columns of the matrix.

If :math:\textit{nru} = 0, :math:\mathrm{u} is not referenced.

**c** : float, ndarray, shape :math:\left(:, \textit{ncc}\right)
:math:\mathrm{c} is overwritten by the matrix :math:U^\mathrm{T}C. If :math:\textit{ncc} = 0, :math:\mathrm{c} is not referenced.

.. _f08me-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{ncvt}.

Constraint: :math:\textit{ncvt}\geq 0.

(errno :math:-4)
On entry, error in parameter :math:\textit{nru}.

Constraint: :math:\textit{nru}\geq 0.

(errno :math:-5)
On entry, error in parameter :math:\textit{ncc}.

Constraint: :math:\textit{ncc}\geq 0.

**Warns**
**NagAlgorithmicWarning**
(errno :math:i > 0)
:math:\langle\mathit{\boldsymbol{value}}\rangle off-diagonals did not converge. The arrays :math:\mathrm{d} and :math:\mathrm{e} contain the diagonal and off-diagonal elements, respectively, of a bidiagonal matrix orthogonally equivalent to :math:B.

.. _f08me-py2-py-notes:

**Notes**
dbdsqr computes the singular values and, optionally, the left or right singular vectors of a real upper or lower bidiagonal matrix :math:B.
In other words, it can compute the singular value decomposition (SVD) of :math:B as

.. math::
B = U\Sigma V^\mathrm{T}\text{.}

Here :math:\Sigma is a diagonal matrix with real diagonal elements :math:\sigma_i (the singular values of :math:B), such that

.. math::
\sigma_1\geq \sigma_2\geq \cdots \geq \sigma_n\geq 0\text{;}

:math:U is an orthogonal matrix whose columns are the left singular vectors :math:u_i; :math:V is an orthogonal matrix whose rows are the right singular vectors :math:v_i.
Thus

.. math::

To compute :math:U and/or :math:V^\mathrm{T}, the arrays :math:\mathrm{u} and/or :math:\mathrm{vt} must be initialized to the unit matrix before dbdsqr is called.

The function may also be used to compute the SVD of a real general matrix :math:A which has been reduced to bidiagonal form by an orthogonal transformation: :math:A = QBP^\mathrm{T}.
If :math:A is :math:m\times n with :math:m\geq n, then :math:Q is :math:m\times n and :math:P^\mathrm{T} is :math:n\times n; if :math:A is :math:n\times p with :math:n < p, then :math:Q is :math:n\times n and :math:P^\mathrm{T} is :math:n\times p.
In this case, the matrices :math:Q and/or :math:P^\mathrm{T} must be formed explicitly by :meth:dorgbr and passed to dbdsqr in the arrays :math:\mathrm{u} and/or :math:\mathrm{vt} respectively.

dbdsqr also has the capability of forming :math:U^\mathrm{T}C, where :math:C is an arbitrary real matrix; this is needed when using the SVD to solve linear least squares problems.

dbdsqr uses two different algorithms.
If any singular vectors are required (i.e., if :math:\textit{ncvt} > 0 or :math:\textit{nru} > 0 or :math:\textit{ncc} > 0), the bidiagonal :math:QR algorithm is used, switching between zero-shift and implicitly shifted forms to preserve the accuracy of small singular values, and switching between :math:QR and :math:QL variants in order to handle graded matrices effectively (see Demmel and Kahan (1990)).
If only singular values are required (i.e., if :math:\textit{ncvt} = \textit{nru} = \textit{ncc} = 0), they are computed by the differential qd algorithm (see Fernando and Parlett (1994)), which is faster and can achieve even greater accuracy.

The singular vectors are normalized so that :math:\left\lVert u_i\right\rVert = \left\lVert v_i\right\rVert = 1, but are determined only to within a factor :math:{\pm 1}.

.. _f08me-py2-py-references:

**References**
Demmel, J W and Kahan, W, 1990, Accurate singular values of bidiagonal matrices, SIAM J. Sci. Statist. Comput. (11), 873--912

Fernando, K V and Parlett, B N, 1994, Accurate singular values and differential qd algorithms, Numer. Math. (67), 191--229

Golub, G H and Van Loan, C F, 1996, Matrix Computations, (3rd Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError

[docs]def zbdsqr(uplo, d, e, vt, u, c):
r"""
zbdsqr computes the singular value decomposition of a complex general matrix which has been reduced to bidiagonal form.

.. _f08ms-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08msf.html

.. _f08ms-py2-py-parameters:

**Parameters**
**uplo** : str, length 1
Indicates whether :math:B is an upper or lower bidiagonal matrix.

:math:\mathrm{uplo} = \texttt{'U'}

:math:B is an upper bidiagonal matrix.

:math:\mathrm{uplo} = \texttt{'L'}

:math:B is a lower bidiagonal matrix.

**d** : float, array-like, shape :math:\left(n\right)
The diagonal elements of the bidiagonal matrix :math:B.

**e** : float, array-like, shape :math:\left(\max\left(1,{n-1}\right)\right)
The off-diagonal elements of the bidiagonal matrix :math:B.

**vt** : complex, array-like, shape :math:\left(:, \textit{ncvt}\right)
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\textit{ncvt} > 0: :math:n; otherwise: :math:1.

If :math:\textit{ncvt} > 0, :math:\mathrm{vt} must contain an :math:n\times \textit{ncvt} matrix. If the right singular vectors of :math:B are required, :math:\textit{ncvt} = n and :math:\mathrm{vt} must contain the unit matrix; if the right singular vectors of :math:A are required, :math:\mathrm{vt} must contain the unitary matrix :math:P^H returned by :meth:zungbr with :math:{\textit{vect}} = \texttt{'P'}.

**u** : complex, array-like, shape :math:\left(\textit{nru}, n\right)
If :math:\textit{nru} > 0, :math:\mathrm{u} must contain an :math:\textit{nru}\times n matrix. If the left singular vectors of :math:B are required, :math:\textit{nru} = n and :math:\mathrm{u} must contain the unit matrix; if the left singular vectors of :math:A are required, :math:\mathrm{u} must contain the unitary matrix :math:Q returned by :meth:zungbr with :math:{\textit{vect}} = \texttt{'Q'}.

**c** : complex, array-like, shape :math:\left(:, \textit{ncc}\right)
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\textit{ncc} > 0: :math:n; otherwise: :math:1.

The :math:n\times \textit{ncc} matrix :math:C if :math:\textit{ncc} > 0.

**Returns**
**d** : float, ndarray, shape :math:\left(n\right)
The singular values in decreasing order of magnitude, unless :math:\mathrm{errno} > 0 (in which case see :ref:Exceptions <f08ms-py2-py-errors>).

**e** : float, ndarray, shape :math:\left(\max\left(1,{n-1}\right)\right)
:math:\mathrm{e} is overwritten, but if :math:\mathrm{errno} > 0 see :ref:Exceptions <f08ms-py2-py-errors>.

**vt** : complex, ndarray, shape :math:\left(:, \textit{ncvt}\right)
The :math:n\times \textit{ncvt} matrix :math:V^\mathrm{H} or :math:V^\mathrm{H}P^\mathrm{H} of right singular vectors, stored by rows.

If :math:\textit{ncvt} = 0, :math:\mathrm{vt} is not referenced.

**u** : complex, ndarray, shape :math:\left(\textit{nru}, n\right)
The :math:\textit{nru}\times n matrix :math:U or :math:QU of left singular vectors, stored as columns of the matrix.

If :math:\textit{nru} = 0, :math:\mathrm{u} is not referenced.

**c** : complex, ndarray, shape :math:\left(:, \textit{ncc}\right)
:math:\mathrm{c} is overwritten by the matrix :math:U^\mathrm{H}C. If :math:\textit{ncc} = 0, :math:\mathrm{c} is not referenced.

.. _f08ms-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{ncvt}.

Constraint: :math:\textit{ncvt}\geq 0.

(errno :math:-4)
On entry, error in parameter :math:\textit{nru}.

Constraint: :math:\textit{nru}\geq 0.

(errno :math:-5)
On entry, error in parameter :math:\textit{ncc}.

Constraint: :math:\textit{ncc}\geq 0.

**Warns**
**NagAlgorithmicWarning**
(errno :math:i > 0)
:math:\langle\mathit{\boldsymbol{value}}\rangle off-diagonals did not converge. The arrays :math:\mathrm{d} and :math:\mathrm{e} contain the diagonal and off-diagonal elements, respectively, of a bidiagonal matrix orthogonally equivalent to :math:B.

.. _f08ms-py2-py-notes:

**Notes**
zbdsqr computes the singular values and, optionally, the left or right singular vectors of a real upper or lower bidiagonal matrix :math:B.
In other words, it can compute the singular value decomposition (SVD) of :math:B as

.. math::
B = U\Sigma V^\mathrm{T}\text{.}

Here :math:\Sigma is a diagonal matrix with real diagonal elements :math:\sigma_i (the singular values of :math:B), such that

.. math::
\sigma_1\geq \sigma_2\geq \cdots \geq \sigma_n\geq 0\text{;}

:math:U is an orthogonal matrix whose columns are the left singular vectors :math:u_i; :math:V is an orthogonal matrix whose rows are the right singular vectors :math:v_i.
Thus

.. math::

To compute :math:U and/or :math:V^\mathrm{T}, the arrays :math:\mathrm{u} and/or :math:\mathrm{vt} must be initialized to the unit matrix before zbdsqr is called.

The function stores the real orthogonal matrices :math:U and :math:V^\mathrm{T} in complex arrays :math:\mathrm{u} and :math:\mathrm{vt}, so that it may also be used to compute the SVD of a complex general matrix :math:A which has been reduced to bidiagonal form by a unitary transformation: :math:A = QBP^\mathrm{H}.
If :math:A is :math:m\times n with :math:m\geq n, then :math:Q is :math:m\times n and :math:P^\mathrm{H} is :math:n\times n; if :math:A is :math:n\times p with :math:n < p, then :math:Q is :math:n\times n and :math:P^\mathrm{H} is :math:n\times p.
In this case, the matrices :math:Q and/or :math:P^\mathrm{H} must be formed explicitly by :meth:zungbr and passed to zbdsqr in the arrays :math:\mathrm{u} and/or :math:\mathrm{vt} respectively.

zbdsqr also has the capability of forming :math:U^\mathrm{H}C, where :math:C is an arbitrary complex matrix; this is needed when using the SVD to solve linear least squares problems.

zbdsqr uses two different algorithms.
If any singular vectors are required (i.e., if :math:\textit{ncvt} > 0 or :math:\textit{nru} > 0 or :math:\textit{ncc} > 0), the bidiagonal :math:QR algorithm is used, switching between zero-shift and implicitly shifted forms to preserve the accuracy of small singular values, and switching between :math:QR and :math:QL variants in order to handle graded matrices effectively (see Demmel and Kahan (1990)).
If only singular values are required (i.e., if :math:\textit{ncvt} = \textit{nru} = \textit{ncc} = 0), they are computed by the differential qd algorithm (see Fernando and Parlett (1994)), which is faster and can achieve even greater accuracy.

The singular vectors are normalized so that :math:\left\lVert u_i\right\rVert = \left\lVert v_i\right\rVert = 1, but are determined only to within a complex factor of absolute value :math:1.

.. _f08ms-py2-py-references:

**References**
Demmel, J W and Kahan, W, 1990, Accurate singular values of bidiagonal matrices, SIAM J. Sci. Statist. Comput. (11), 873--912

Fernando, K V and Parlett, B N, 1994, Accurate singular values and differential qd algorithms, Numer. Math. (67), 191--229

Golub, G H and Van Loan, C F, 1996, Matrix Computations, (3rd Edition), Johns Hopkins University Press, Baltimore
"""
raise NotImplementedError

[docs]def dgeev(jobvl, jobvr, a):
r"""
dgeev computes the eigenvalues and, optionally, the left and/or right eigenvectors for an :math:n\times n real nonsymmetric matrix :math:A.

.. _f08na-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08naf.html

.. _f08na-py2-py-parameters:

**Parameters**
**jobvl** : str, length 1
If :math:\mathrm{jobvl} = \texttt{'N'}, the left eigenvectors of :math:A are not computed.

If :math:\mathrm{jobvl} = \texttt{'V'}, the left eigenvectors of :math:A are computed.

**jobvr** : str, length 1
If :math:\mathrm{jobvr} = \texttt{'N'}, the right eigenvectors of :math:A are not computed.

If :math:\mathrm{jobvr} = \texttt{'V'}, the right eigenvectors of :math:A are computed.

**a** : float, array-like, shape :math:\left(n, n\right)
The :math:n\times n matrix :math:A.

**Returns**
**a** : float, ndarray, shape :math:\left(n, n\right)
:math:\mathrm{a} has been overwritten.

**wr** : float, ndarray, shape :math:\left(n\right)
:math:\mathrm{wr} and :math:\mathrm{wi} contain the real and imaginary parts, respectively, of the computed eigenvalues. Complex conjugate pairs of eigenvalues appear consecutively with the eigenvalue having the positive imaginary part first.

**wi** : float, ndarray, shape :math:\left(n\right)
:math:\mathrm{wr} and :math:\mathrm{wi} contain the real and imaginary parts, respectively, of the computed eigenvalues. Complex conjugate pairs of eigenvalues appear consecutively with the eigenvalue having the positive imaginary part first.

**vl** : float, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobvl} = \texttt{'V'}, the left eigenvectors :math:u_j are stored one after another in the columns of :math:\mathrm{vl}, in the same order as their corresponding eigenvalues. If the :math:j\ th eigenvalue is real, then :math:u_j = \mathrm{vl}[\textit{i}-1,j-1], for :math:\textit{i} = 1,2,\ldots,n. If the :math:j\ th and :math:\left(j+1\right)\ st eigenvalues form a complex conjugate pair, then :math:u_j = \mathrm{vl}[\textit{i}-1,j-1]+\textit{i}\times \mathrm{vl}[\textit{i}-1,j] and :math:u_{{j+1}} = \mathrm{vl}[\textit{i}-1,j-1]-\textit{i}\times \mathrm{vl}[\textit{i}-1,j], for :math:\textit{i} = 1,2,\ldots,n.

If :math:\mathrm{jobvl} = \texttt{'N'}, :math:\mathrm{vl} is not referenced.

**vr** : float, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobvr} = \texttt{'V'}, the right eigenvectors :math:v_j are stored one after another in the columns of :math:\mathrm{vr}, in the same order as their corresponding eigenvalues. If the :math:j\ th eigenvalue is real, then :math:v_j = \mathrm{vr}[\textit{i}-1,j-1], for :math:\textit{i} = 1,2,\ldots,n. If the :math:j\ th and :math:\left(j+1\right)\ st eigenvalues form a complex conjugate pair, then :math:v_j = \mathrm{vr}[\textit{i}-1,j-1]+\textit{i}\times \mathrm{vr}[\textit{i}-1,j] and :math:v_{{j+1}} = \mathrm{vr}[\textit{i}-1,j-1]-\textit{i}\times \mathrm{vr}[\textit{i}-1,j], for :math:\textit{i} = 1,2,\ldots,n.

If :math:\mathrm{jobvr} = \texttt{'N'}, :math:\mathrm{vr} is not referenced.

.. _f08na-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{jobvl}.

Constraint: :math:\mathrm{jobvl} = \texttt{'N'} or :math:\texttt{'V'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{jobvr}.

Constraint: :math:\mathrm{jobvr} = \texttt{'N'} or :math:\texttt{'V'}.

(errno :math:-3)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

**Warns**
**NagAlgorithmicWarning**
(errno :math:i > 0)
The :math:QR algorithm failed to compute all the eigenvalues, and no eigenvectors have been computed; elements :math:\langle\mathit{\boldsymbol{value}}\rangle to :math:\textit{n} of :math:\mathrm{wr} and :math:\mathrm{wi} contain eigenvalues which have converged.

.. _f08na-py2-py-notes:

**Notes**
The right eigenvector :math:v_j of :math:A satisfies

.. math::
Av_j = \lambda_jv_j

where :math:\lambda_j is the :math:j\ th eigenvalue of :math:A.
The left eigenvector :math:u_j of :math:A satisfies

.. math::
u_j^\mathrm{H}A = \lambda_ju_j^\mathrm{H}

where :math:u_j^\mathrm{H} denotes the conjugate transpose of :math:u_j.

The matrix :math:A is first reduced to upper Hessenberg form by means of orthogonal similarity transformations, and the :math:QR algorithm is then used to further reduce the matrix to upper quasi-triangular Schur form, :math:T, with :math:1\times 1 and :math:2\times 2 blocks on the main diagonal.
The eigenvalues are computed from :math:T, the :math:2\times 2 blocks corresponding to complex conjugate pairs and, optionally, the eigenvectors of :math:T are computed and backtransformed to the eigenvectors of :math:A.

.. _f08na-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 dgeevx(balanc, jobvl, jobvr, sense, a):
r"""
dgeevx computes the eigenvalues and, optionally, the left and/or right eigenvectors for an :math:n\times n real nonsymmetric matrix :math:A.

Optionally, it also computes a balancing transformation to improve the conditioning of the eigenvalues and eigenvectors, reciprocal condition numbers for the eigenvalues, and reciprocal condition numbers for the right eigenvectors.

.. _f08nb-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08nbf.html

.. _f08nb-py2-py-parameters:

**Parameters**
**balanc** : str, length 1
Indicates how the input matrix should be diagonally scaled and/or permuted to improve the conditioning of its eigenvalues.

:math:\mathrm{balanc} = \texttt{'N'}

Do not diagonally scale or permute.

:math:\mathrm{balanc} = \texttt{'P'}

Perform permutations to make the matrix more nearly upper triangular. Do not diagonally scale.

:math:\mathrm{balanc} = \texttt{'S'}

Diagonally scale the matrix, i.e., replace :math:A\times DAD^{-1}, where :math:D is a diagonal matrix chosen to make the rows and columns of :math:A more equal in norm. Do not permute.

:math:\mathrm{balanc} = \texttt{'B'}

Both diagonally scale and permute :math:A.

Computed reciprocal condition numbers will be for the matrix after balancing and/or permuting.

Permuting does not change condition numbers (in exact arithmetic), but balancing does.

**jobvl** : str, length 1
If :math:\mathrm{jobvl} = \texttt{'N'}, the left eigenvectors of :math:A are not computed.

If :math:\mathrm{jobvl} = \texttt{'V'}, the left eigenvectors of :math:A are computed.

If :math:\mathrm{sense} = \texttt{'E'} or :math:\texttt{'B'}, :math:\mathrm{jobvl} must be set to :math:\mathrm{jobvl} = \texttt{'V'}.

**jobvr** : str, length 1
If :math:\mathrm{jobvr} = \texttt{'N'}, the right eigenvectors of :math:A are not computed.

If :math:\mathrm{jobvr} = \texttt{'V'}, the right eigenvectors of :math:A are computed.

If :math:\mathrm{sense} = \texttt{'E'} or :math:\texttt{'B'}, :math:\mathrm{jobvr} must be set to :math:\mathrm{jobvr} = \texttt{'V'}.

**sense** : str, length 1
Determines which reciprocal condition numbers are computed.

:math:\mathrm{sense} = \texttt{'N'}

None are computed.

:math:\mathrm{sense} = \texttt{'E'}

Computed for eigenvalues only.

:math:\mathrm{sense} = \texttt{'V'}

Computed for right eigenvectors only.

:math:\mathrm{sense} = \texttt{'B'}

Computed for eigenvalues and right eigenvectors.

If :math:\mathrm{sense} = \texttt{'E'} or :math:\texttt{'B'}, both left and right eigenvectors must also be computed (:math:\mathrm{jobvl} = \texttt{'V'} and :math:\mathrm{jobvr} = \texttt{'V'}).

**a** : float, array-like, shape :math:\left(n, n\right)
The :math:n\times n matrix :math:A.

**Returns**
**a** : float, ndarray, shape :math:\left(n, n\right)
:math:\mathrm{a} has been overwritten. If :math:\mathrm{jobvl} = \texttt{'V'} or :math:\mathrm{jobvr} = \texttt{'V'}, :math:A contains the real Schur form of the balanced version of the input matrix :math:A.

**wr** : float, ndarray, shape :math:\left(n\right)
:math:\mathrm{wr} and :math:\mathrm{wi} contain the real and imaginary parts, respectively, of the computed eigenvalues. Complex conjugate pairs of eigenvalues appear consecutively with the eigenvalue having the positive imaginary part first.

**wi** : float, ndarray, shape :math:\left(n\right)
:math:\mathrm{wr} and :math:\mathrm{wi} contain the real and imaginary parts, respectively, of the computed eigenvalues. Complex conjugate pairs of eigenvalues appear consecutively with the eigenvalue having the positive imaginary part first.

**vl** : float, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobvl} = \texttt{'V'}, the left eigenvectors :math:u_j are stored one after another in the columns of :math:\mathrm{vl}, in the same order as their corresponding eigenvalues. If the :math:j\ th eigenvalue is real, then :math:u_j = \mathrm{vl}[\textit{i}-1,j-1], for :math:\textit{i} = 1,2,\ldots,n. If the :math:j\ th and :math:\left(j+1\right)\ st eigenvalues form a complex conjugate pair, then :math:u_j = \mathrm{vl}[\textit{i}-1,j-1]+\textit{i}\times \mathrm{vl}[\textit{i}-1,j] and :math:u_{{j+1}} = \mathrm{vl}[\textit{i}-1,j-1]-\textit{i}\times \mathrm{vl}[\textit{i}-1,j], for :math:\textit{i} = 1,2,\ldots,n.

If :math:\mathrm{jobvl} = \texttt{'N'}, :math:\mathrm{vl} is not referenced.

**vr** : float, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobvr} = \texttt{'V'}, the right eigenvectors :math:v_j are stored one after another in the columns of :math:\mathrm{vr}, in the same order as their corresponding eigenvalues. If the :math:j\ th eigenvalue is real, then :math:v_j = \mathrm{vr}[\textit{i}-1,j-1], for :math:\textit{i} = 1,2,\ldots,n. If the :math:j\ th and :math:\left(j+1\right)\ st eigenvalues form a complex conjugate pair, then :math:v_j = \mathrm{vr}[\textit{i}-1,j-1]+\textit{i}\times \mathrm{vr}[\textit{i}-1,j] and :math:v_{{j+1}} = \mathrm{vr}[\textit{i}-1,j-1]-\textit{i}\times \mathrm{vr}[\textit{i}-1,j], for :math:\textit{i} = 1,2,\ldots,n.

If :math:\mathrm{jobvr} = \texttt{'N'}, :math:\mathrm{vr} is not referenced.

**ilo** : int
:math:\mathrm{ilo} and :math:\mathrm{ihi} are integer values determined when :math:A was balanced. The balanced :math:A has :math:a_{{ij}} = 0 if :math:i > j and :math:j = 1,2,\ldots,\mathrm{ilo}-1 or :math:i = \mathrm{ihi}+1,\ldots,n.

**ihi** : int
:math:\mathrm{ilo} and :math:\mathrm{ihi} are integer values determined when :math:A was balanced. The balanced :math:A has :math:a_{{ij}} = 0 if :math:i > j and :math:j = 1,2,\ldots,\mathrm{ilo}-1 or :math:i = \mathrm{ihi}+1,\ldots,n.

**scale** : float, ndarray, shape :math:\left(n\right)
Details of the permutations and scaling factors applied when balancing :math:A.

If :math:p_j is the index of the row and column interchanged with row and column :math:j, and :math:d_j is the scaling factor applied to row and column :math:j, then

:math:\mathrm{scale}[\textit{j}-1] = p_{\textit{j}}, for :math:\textit{j} = 1,2,\ldots,\mathrm{ilo}-1;

:math:\mathrm{scale}[\textit{j}-1] = d_{\textit{j}}, for :math:\textit{j} = \mathrm{ilo},\ldots,\mathrm{ihi};

:math:\mathrm{scale}[\textit{j}-1] = p_{\textit{j}}, for :math:\textit{j} = \mathrm{ihi}+1,\ldots,n.

The order in which the interchanges are made is :math:\textit{n} to :math:\mathrm{ihi}+1, then :math:1 to :math:\mathrm{ilo}-1.

**abnrm** : float
The :math:1-norm of the balanced matrix (the maximum of the sum of absolute values of elements of any column).

**rconde** : float, ndarray, shape :math:\left(n\right)
:math:\mathrm{rconde}[j-1] is the reciprocal condition number of the :math:j\ th eigenvalue.

**rcondv** : float, ndarray, shape :math:\left(n\right)
:math:\mathrm{rcondv}[j-1] is the reciprocal condition number of the :math:j\ th right eigenvector.

.. _f08nb-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{balanc}.

Constraint: :math:\mathrm{balanc} = \texttt{'N'}, :math:\texttt{'P'}, :math:\texttt{'S'} or :math:\texttt{'B'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{jobvl}.

Constraint: :math:\mathrm{jobvl} = \texttt{'N'} or :math:\texttt{'V'}.

(errno :math:-3)
On entry, error in parameter :math:\mathrm{jobvr}.

Constraint: :math:\mathrm{jobvr} = \texttt{'N'} or :math:\texttt{'V'}.

(errno :math:-4)
On entry, error in parameter :math:\mathrm{sense}.

Constraint: :math:\mathrm{sense} = \texttt{'N'}, :math:\texttt{'E'}, :math:\texttt{'V'} or :math:\texttt{'B'}.

(errno :math:-5)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

**Warns**
**NagAlgorithmicWarning**
(errno :math:i > 0)
The :math:QR algorithm failed to compute all the eigenvalues, and no eigenvectors or condition numbers have been computed; elements :math:1 to :math:\mathrm{ilo}-1 and :math:\langle\mathit{\boldsymbol{value}}\rangle to :math:\textit{n} of :math:\mathrm{wr} and :math:\mathrm{wi} contain eigenvalues which have converged.

.. _f08nb-py2-py-notes:

**Notes**
The right eigenvector :math:v_j of :math:A satisfies

.. math::
Av_j = \lambda_jv_j

where :math:\lambda_j is the :math:j\ th eigenvalue of :math:A.
The left eigenvector :math:u_j of :math:A satisfies

.. math::
u_j^\mathrm{H}A = \lambda_ju_j^\mathrm{H}

where :math:u_j^\mathrm{H} denotes the conjugate transpose of :math:u_j.

Balancing a matrix means permuting the rows and columns to make it more nearly upper triangular, and applying a diagonal similarity transformation :math:DAD^{-1}, where :math:D is a diagonal matrix, with the aim of making its rows and columns closer in norm and the condition numbers of its eigenvalues and eigenvectors smaller.
The computed reciprocal condition numbers correspond to the balanced matrix.
Permuting rows and columns will not change the condition numbers (in exact arithmetic) but diagonal scaling will.
For further explanation of balancing, see Section 4.8.1.2 of Anderson et al. (1999).

Following the optional balancing, the matrix :math:A is first reduced to upper Hessenberg form by means of unitary similarity transformations, and the :math:QR algorithm is then used to further reduce the matrix to upper triangular Schur form, :math:T, from which the eigenvalues are computed.
Optionally, the eigenvectors of :math:T are also computed and backtransformed to those of :math:A.

.. _f08nb-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 dgehrd(ilo, ihi, a):
r"""
dgehrd reduces a real general matrix to Hessenberg form.

.. _f08ne-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08nef.html

.. _f08ne-py2-py-parameters:

**Parameters**
**ilo** : int
If :math:A has been output by :meth:dgebal, :math:\mathrm{ilo} and :math:\mathrm{ihi} **must** contain the values returned by that function. Otherwise, :math:\mathrm{ilo} must be set to :math:1 and :math:\mathrm{ihi} to :math:\textit{n}.

**ihi** : int
If :math:A has been output by :meth:dgebal, :math:\mathrm{ilo} and :math:\mathrm{ihi} **must** contain the values returned by that function. Otherwise, :math:\mathrm{ilo} must be set to :math:1 and :math:\mathrm{ihi} to :math:\textit{n}.

**a** : float, array-like, shape :math:\left(n, n\right)
The :math:n\times n general matrix :math:A.

**Returns**
**a** : float, ndarray, shape :math:\left(n, n\right)
:math:\mathrm{a} is overwritten by the upper Hessenberg matrix :math:H and details of the orthogonal matrix :math:Q.

**tau** : float, ndarray, shape :math:\left(\max\left(1,{n-1}\right)\right)
Further details of the orthogonal matrix :math:Q.

.. _f08ne-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{ilo}.

(errno :math:-3)
On entry, error in parameter :math:\mathrm{ihi}.

.. _f08ne-py2-py-notes:

**Notes**
dgehrd reduces a real general matrix :math:A to upper Hessenberg form :math:H by an orthogonal similarity transformation: :math:A = QHQ^\mathrm{T}.

The matrix :math:Q is not formed explicitly, but is represented as a product of elementary reflectors (see the F08 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08intro.html>__ for details). Functions are provided to work with :math:Q in this representation (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08nef.html#fcomments>__).

The function can take advantage of a previous call to :meth:dgebal, which may produce a matrix with the structure:

.. math::
\begin{pmatrix}A_{11}&A_{12}&A_{13}\\&A_{22}&A_{23}\\&&A_{33}\end{pmatrix}

where :math:A_{11} and :math:A_{33} are upper triangular.
If so, only the central diagonal block :math:A_{22}, in rows and columns :math:i_{\mathrm{lo}} to :math:i_{\mathrm{hi}}, needs to be reduced to Hessenberg form (the blocks :math:A_{12} and :math:A_{23} will also be affected by the reduction).
Therefore, the values of :math:i_{\mathrm{lo}} and :math:i_{\mathrm{hi}} determined by :meth:dgebal can be supplied to the function directly.
If :meth:dgebal has not previously been called however, then :math:i_{\mathrm{lo}} must be set to :math:1 and :math:i_{\mathrm{hi}} to :math:n.

.. _f08ne-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 dorghr(ilo, ihi, a, tau):
r"""
dorghr generates the real orthogonal matrix :math:Q which was determined by :meth:dgehrd when reducing a real general matrix :math:A to Hessenberg form.

.. _f08nf-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08nff.html

.. _f08nf-py2-py-parameters:

**Parameters**
**ilo** : int
These **must** be the same arguments :math:\mathrm{ilo} and :math:\mathrm{ihi}, respectively, as supplied to :meth:dgehrd.

**ihi** : int
These **must** be the same arguments :math:\mathrm{ilo} and :math:\mathrm{ihi}, respectively, as supplied to :meth:dgehrd.

**a** : float, array-like, shape :math:\left(n, n\right)
Details of the vectors which define the elementary reflectors, as returned by :meth:dgehrd.

**tau** : float, array-like, shape :math:\left(\max\left(1,{n-1}\right)\right)
Further details of the elementary reflectors, as returned by :meth:dgehrd.

**Returns**
**a** : float, ndarray, shape :math:\left(n, n\right)
The :math:n\times n orthogonal matrix :math:Q.

.. _f08nf-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{ilo}.

(errno :math:-3)
On entry, error in parameter :math:\mathrm{ihi}.

.. _f08nf-py2-py-notes:

**Notes**
dorghr is intended to be used following a call to :meth:dgehrd, which reduces a real general matrix :math:A to upper Hessenberg form :math:H by an orthogonal similarity transformation: :math:A = QHQ^\mathrm{T}. :meth:dgehrd represents the matrix :math:Q as a product of :math:i_{\mathrm{hi}}-i_{\mathrm{lo}} elementary reflectors.
Here :math:i_{\mathrm{lo}} and :math:i_{\mathrm{hi}} are values determined by :meth:dgebal when balancing the matrix; if the matrix has not been balanced, :math:i_{\mathrm{lo}} = 1 and :math:i_{\mathrm{hi}} = n.

This function may be used to generate :math:Q explicitly as a square matrix. :math:Q has the structure:

.. math::
Q = \begin{pmatrix}I&0&0\\0&Q_{22}&0\\0&0&I\end{pmatrix}

where :math:Q_{22} occupies rows and columns :math:i_{\mathrm{lo}} to :math:i_{\mathrm{hi}}.

.. _f08nf-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 dormhr(side, trans, ilo, ihi, a, tau, c):
r"""
dormhr multiplies an arbitrary real matrix :math:C by the real orthogonal matrix :math:Q which was determined by :meth:dgehrd when reducing a real general matrix to Hessenberg form.

.. _f08ng-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08ngf.html

.. _f08ng-py2-py-parameters:

**Parameters**
**side** : str, length 1
Indicates how :math:Q or :math:Q^\mathrm{T} is to be applied to :math:C.

:math:\mathrm{side} = \texttt{'L'}

:math:Q or :math:Q^\mathrm{T} is applied to :math:C from the left.

:math:\mathrm{side} = \texttt{'R'}

:math:Q or :math:Q^\mathrm{T} is applied to :math:C from the right.

**trans** : str, length 1
Indicates whether :math:Q or :math:Q^\mathrm{T} is to be applied to :math:C.

:math:\mathrm{trans} = \texttt{'N'}

:math:Q is applied to :math:C.

:math:\mathrm{trans} = \texttt{'T'}

:math:Q^\mathrm{T} is applied to :math:C.

**ilo** : int
These **must** be the same arguments :math:\mathrm{ilo} and :math:\mathrm{ihi}, respectively, as supplied to :meth:dgehrd.

**ihi** : int
These **must** be the same arguments :math:\mathrm{ilo} and :math:\mathrm{ihi}, respectively, as supplied to :meth:dgehrd.

**a** : float, array-like, shape :math:\left(:, :\right)
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\mathrm{side}=\texttt{'L'}: :math:m; if :math:\mathrm{side}=\texttt{'R'}: :math:n; otherwise: :math:0.

Note: the required extent for this argument in dimension 2 is determined as follows: if :math:\mathrm{side}=\texttt{'L'}: :math:m; if :math:\mathrm{side}=\texttt{'R'}: :math:n; otherwise: :math:0.

Details of the vectors which define the elementary reflectors, as returned by :meth:dgehrd.

**tau** : float, array-like, shape :math:\left(:\right)
Note: the required length for this argument is determined as follows: if :math:\mathrm{side}=\texttt{'L'}: :math:{m-1}; if :math:\mathrm{side}=\texttt{'R'}: :math:{n-1}; otherwise: :math:0.

Further details of the elementary reflectors, as returned by :meth:dgehrd.

**c** : float, array-like, shape :math:\left(m, n\right)
The :math:m\times n matrix :math:C.

**Returns**
**c** : float, ndarray, shape :math:\left(m, n\right)
:math:\mathrm{c} is overwritten by :math:QC or :math:Q^\mathrm{T}C or :math:CQ or :math:CQ^\mathrm{T} as specified by :math:\mathrm{side} and :math:\mathrm{trans}.

.. _f08ng-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{side}.

Constraint: :math:\mathrm{side} = \texttt{'L'} or :math:\texttt{'R'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{trans}.

Constraint: :math:\mathrm{trans} = \texttt{'N'} or :math:\texttt{'T'}.

(errno :math:-3)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

(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{ilo}.

(errno :math:-6)
On entry, error in parameter :math:\mathrm{ihi}.

.. _f08ng-py2-py-notes:

**Notes**
dormhr is intended to be used following a call to :meth:dgehrd, which reduces a real general matrix :math:A to upper Hessenberg form :math:H by an orthogonal similarity transformation: :math:A = QHQ^\mathrm{T}. :meth:dgehrd represents the matrix :math:Q as a product of :math:i_{\mathrm{hi}}-i_{\mathrm{lo}} elementary reflectors.
Here :math:i_{\mathrm{lo}} and :math:i_{\mathrm{hi}} are values determined by :meth:dgebal when balancing the matrix; if the matrix has not been balanced, :math:i_{\mathrm{lo}} = 1 and :math:i_{\mathrm{hi}} = n.

This function may be used to form one of the matrix products

.. math::
QC,Q^\mathrm{T}C,CQ\text{ or }CQ^\mathrm{T}\text{,}

overwriting the result on :math:C (which may be any real rectangular matrix).

A common application of this function is to transform a matrix :math:V of eigenvectors of :math:H to the matrix :math:\textit{QV} of eigenvectors of :math:A.

.. _f08ng-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 dgebal(job, n, a):
r"""
dgebal balances a real general matrix in order to improve the accuracy of computed eigenvalues and/or eigenvectors.

.. _f08nh-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08nhf.html

.. _f08nh-py2-py-parameters:

**Parameters**
**job** : str, length 1
Indicates whether :math:A is to be permuted and/or scaled (or neither).

:math:\mathrm{job} = \texttt{'N'}

:math:A is neither permuted nor scaled (but values are assigned to :math:\mathrm{ilo}, :math:\mathrm{ihi} and :math:\mathrm{scale}).

:math:\mathrm{job} = \texttt{'P'}

:math:A is permuted but not scaled.

:math:\mathrm{job} = \texttt{'S'}

:math:A is scaled but not permuted.

:math:\mathrm{job} = \texttt{'B'}

:math:A is both permuted and scaled.

**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 matrix :math:A.

**Returns**
**a** : float, ndarray, shape :math:\left(\mathrm{n}, \mathrm{n}\right)
:math:\mathrm{a} is overwritten by the balanced matrix. If :math:\mathrm{job} = \texttt{'N'}, :math:\mathrm{a} is not referenced.

**ilo** : int
The values :math:i_{\mathrm{lo}} and :math:i_{\mathrm{hi}} such that on exit :math:\mathrm{a}[i-1,j-1] is zero if :math:i > j and :math:1\leq j < i_{\mathrm{lo}} or :math:i_{\mathrm{hi}} < i\leq n.

If :math:\mathrm{job} = \texttt{'N'} or :math:\texttt{'S'}, :math:i_{\mathrm{lo}} = 1 and :math:i_{\mathrm{hi}} = n.

**ihi** : int
The values :math:i_{\mathrm{lo}} and :math:i_{\mathrm{hi}} such that on exit :math:\mathrm{a}[i-1,j-1] is zero if :math:i > j and :math:1\leq j < i_{\mathrm{lo}} or :math:i_{\mathrm{hi}} < i\leq n.

If :math:\mathrm{job} = \texttt{'N'} or :math:\texttt{'S'}, :math:i_{\mathrm{lo}} = 1 and :math:i_{\mathrm{hi}} = n.

**scale** : float, ndarray, shape :math:\left(\mathrm{n}\right)
Details of the permutations and scaling factors applied to :math:A. More precisely, if :math:p_j is the index of the row and column interchanged with row and column :math:j and :math:d_j is the scaling factor used to balance row and column :math:j then

.. math::
\mathrm{scale}[j-1] = \left\{\begin{array}{ll}p_j\text{,}&j = 1,2,\ldots,i_{\mathrm{lo}}-1\\d_j\text{,}&j = i_{\mathrm{lo}},i_{\mathrm{lo}}+1,\ldots,i_{\mathrm{hi}}\quad \text{ and}\\p_j\text{,}&j = i_{\mathrm{hi}}+1,i_{\mathrm{hi}}+2,\ldots,n\text{.}\end{array}\right.

The order in which the interchanges are made is :math:n to :math:i_{\mathrm{hi}}+1 then :math:1 to :math:i_{\mathrm{lo}}-1.

.. _f08nh-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{job}.

Constraint: :math:\mathrm{job} = \texttt{'N'}, :math:\texttt{'P'}, :math:\texttt{'S'} or :math:\texttt{'B'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{n}.

Constraint: :math:\mathrm{n}\geq 0.

.. _f08nh-py2-py-notes:

**Notes**
dgebal balances a real general matrix :math:A.
The term 'balancing' covers two steps, each of which involves a similarity transformation of :math:A.
The function can perform either or both of these steps.

(1) The function first attempts to permute :math:A to block upper triangular form by a similarity transformation:

.. math::
PAP^\mathrm{T} = A^{\prime } = \begin{pmatrix}A_{11}^{\prime }&A_{12}^{\prime }&A_{13}^{\prime }\\0&A_{22}^{\prime }&A_{23}^{\prime }\\0&0&A_{33}^{\prime }\end{pmatrix}

where :math:P is a permutation matrix, and :math:A_{11}^{\prime } and :math:A_{33}^{\prime } are upper triangular. Then the diagonal elements of :math:A_{11}^{\prime } and :math:A_{33}^{\prime } are eigenvalues of :math:A. The rest of the eigenvalues of :math:A are the eigenvalues of the central diagonal block :math:A_{22}^{\prime }, in rows and columns :math:i_{\mathrm{lo}} to :math:i_{\mathrm{hi}}. Subsequent operations to compute the eigenvalues of :math:A (or its Schur factorization) need only be applied to these rows and columns; this can save a significant amount of work if :math:i_{\mathrm{lo}} > 1 and :math:i_{\mathrm{hi}} < n. If no suitable permutation exists (as is often the case), the function sets :math:i_{\mathrm{lo}} = 1 and :math:i_{\mathrm{hi}} = n, and :math:A_{22}^{\prime } is the whole of :math:A.

(#) The function applies a diagonal similarity transformation to :math:A^{\prime }, to make the rows and columns of :math:A_{22}^{\prime } as close in norm as possible:

.. math::
A^{{\prime \prime }} = DA^{\prime }D^{-1} = \begin{pmatrix}I&0&0\\0&D_{22}&0\\0&0&I\end{pmatrix}\begin{pmatrix}A_{11}^{\prime }&A_{12}^{\prime }&A_{13}^{\prime }\\0&A_{22}^{\prime }&A_{23}^{\prime }\\0&0&A_{33}^{\prime }\end{pmatrix}\begin{pmatrix}I&0&0\\0&D_{22}^{-1}&0\\0&0&I\end{pmatrix}\text{.}

This scaling can reduce the norm of the matrix (i.e., :math:\left\lVert A_{22}^{{\prime \prime }}\right\rVert < \left\lVert A_{22}^{\prime }\right\rVert) and hence reduce the effect of rounding errors on the accuracy of computed eigenvalues and eigenvectors.

.. _f08nh-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 dgebak(job, side, ilo, ihi, scale, v):
r"""
dgebak transforms eigenvectors of a balanced matrix to those of the original real nonsymmetric matrix.

.. _f08nj-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08njf.html

.. _f08nj-py2-py-parameters:

**Parameters**
**job** : str, length 1
This **must** be the same argument :math:\mathrm{job} as supplied to :meth:dgebal.

**side** : str, length 1
Indicates whether left or right eigenvectors are to be transformed.

:math:\mathrm{side} = \texttt{'L'}

The left eigenvectors are transformed.

:math:\mathrm{side} = \texttt{'R'}

The right eigenvectors are transformed.

**ilo** : int
The values :math:i_{\mathrm{lo}} and :math:i_{\mathrm{hi}}, as returned by :meth:dgebal.

**ihi** : int
The values :math:i_{\mathrm{lo}} and :math:i_{\mathrm{hi}}, as returned by :meth:dgebal.

**scale** : float, array-like, shape :math:\left(n\right)
Details of the permutations and/or the scaling factors used to balance the original real nonsymmetric matrix, as returned by :meth:dgebal.

**v** : float, array-like, shape :math:\left(n, m\right)
The matrix of left or right eigenvectors to be transformed.

**Returns**
**v** : float, ndarray, shape :math:\left(n, m\right)
The transformed eigenvectors.

.. _f08nj-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{job}.

Constraint: :math:\mathrm{job} = \texttt{'N'}, :math:\texttt{'P'}, :math:\texttt{'S'} or :math:\texttt{'B'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{side}.

Constraint: :math:\mathrm{side} = \texttt{'L'} or :math:\texttt{'R'}.

(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{ilo}.

(errno :math:-5)
On entry, error in parameter :math:\mathrm{ihi}.

(errno :math:-7)
On entry, error in parameter :math:\textit{m}.

Constraint: :math:m\geq 0.

.. _f08nj-py2-py-notes:

**Notes**
dgebak is intended to be used after a real nonsymmetric matrix :math:A has been balanced by :meth:dgebal, and eigenvectors of the balanced matrix :math:A_{22}^{{\prime \prime }} have subsequently been computed.

For a description of balancing, see the document for :meth:dgebal.
The balanced matrix :math:A^{{\prime \prime }} is obtained as :math:A^{{\prime \prime }} = DPAP^\mathrm{T}D^{-1}, where :math:P is a permutation matrix and :math:D is a diagonal scaling matrix.
This function transforms left or right eigenvectors as follows:

if :math:x is a right eigenvector of :math:A^{{\prime \prime }}, :math:P^\mathrm{T}D^{-1}x is a right eigenvector of :math:A;

if :math:y is a left eigenvector of :math:A^{{\prime \prime }}, :math:P^\mathrm{T}Dy is a left eigenvector of :math:A.
"""
raise NotImplementedError

[docs]def zgeev(jobvl, jobvr, a):
r"""
zgeev computes the eigenvalues and, optionally, the left and/or right eigenvectors for an :math:n\times n complex nonsymmetric matrix :math:A.

.. _f08nn-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08nnf.html

.. _f08nn-py2-py-parameters:

**Parameters**
**jobvl** : str, length 1
If :math:\mathrm{jobvl} = \texttt{'N'}, the left eigenvectors of :math:A are not computed.

If :math:\mathrm{jobvl} = \texttt{'V'}, the left eigenvectors of :math:A are computed.

**jobvr** : str, length 1
If :math:\mathrm{jobvr} = \texttt{'N'}, the right eigenvectors of :math:A are not computed.

If :math:\mathrm{jobvr} = \texttt{'V'}, the right eigenvectors of :math:A are computed.

**a** : complex, array-like, shape :math:\left(n, n\right)
The :math:n\times n matrix :math:A.

**Returns**
**a** : complex, ndarray, shape :math:\left(n, n\right)
:math:\mathrm{a} has been overwritten.

**w** : complex, ndarray, shape :math:\left(n\right)
Contains the computed eigenvalues.

**vl** : complex, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobvl} = \texttt{'V'}, the left eigenvectors :math:u_j are stored one after another in the columns of :math:\mathrm{vl}, in the same order as their corresponding eigenvalues; that is :math:u_j = \mathrm{vl}[\textit{i}-1,j-1], for :math:\textit{i} = 1,2,\ldots,n.

If :math:\mathrm{jobvl} = \texttt{'N'}, :math:\mathrm{vl} is not referenced.

**vr** : complex, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobvr} = \texttt{'V'}, the right eigenvectors :math:v_j are stored one after another in the columns of :math:\mathrm{vr}, in the same order as their corresponding eigenvalues; that is :math:v_j = \mathrm{vr}[\textit{i}-1,j-1], for :math:\textit{i} = 1,2,\ldots,n.

If :math:\mathrm{jobvr} = \texttt{'N'}, :math:\mathrm{vr} is not referenced.

.. _f08nn-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{jobvl}.

Constraint: :math:\mathrm{jobvl} = \texttt{'N'} or :math:\texttt{'V'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{jobvr}.

Constraint: :math:\mathrm{jobvr} = \texttt{'N'} or :math:\texttt{'V'}.

(errno :math:-3)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

**Warns**
**NagAlgorithmicWarning**
(errno :math:i > 0)
The :math:QR algorithm failed to compute all the eigenvalues, and no eigenvectors have been computed; elements :math:\langle\mathit{\boldsymbol{value}}\rangle to :math:\textit{n} of :math:\mathrm{w} contain eigenvalues which have converged.

.. _f08nn-py2-py-notes:

**Notes**
The right eigenvector :math:v_j of :math:A satisfies

.. math::
Av_j = \lambda_jv_j

where :math:\lambda_j is the :math:j\ th eigenvalue of :math:A.
The left eigenvector :math:u_j of :math:A satisfies

.. math::
u_j^\mathrm{H}A = \lambda_ju_j^\mathrm{H}

where :math:u_j^\mathrm{H} denotes the conjugate transpose of :math:u_j.

The matrix :math:A is first reduced to upper Hessenberg form by means of unitary similarity transformations, and the :math:QR algorithm is then used to further reduce the matrix to upper triangular Schur form, :math:T, from which the eigenvalues are computed.
Optionally, the eigenvectors of :math:T are also computed and backtransformed to those of :math:A.

.. _f08nn-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 zgeevx(balanc, jobvl, jobvr, sense, a):
r"""
zgeevx computes the eigenvalues and, optionally, the left and/or right eigenvectors for an :math:n\times n complex nonsymmetric matrix :math:A.

Optionally, it also computes a balancing transformation to improve the conditioning of the eigenvalues and eigenvectors, reciprocal condition numbers for the eigenvalues, and reciprocal condition numbers for the right eigenvectors.

.. _f08np-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08npf.html

.. _f08np-py2-py-parameters:

**Parameters**
**balanc** : str, length 1
Indicates how the input matrix should be diagonally scaled and/or permuted to improve the conditioning of its eigenvalues.

:math:\mathrm{balanc} = \texttt{'N'}

Do not diagonally scale or permute.

:math:\mathrm{balanc} = \texttt{'P'}

Perform permutations to make the matrix more nearly upper triangular. Do not diagonally scale.

:math:\mathrm{balanc} = \texttt{'S'}

Diagonally scale the matrix, i.e., replace :math:A\times DAD^{-1}, where :math:D is a diagonal matrix chosen to make the rows and columns of :math:A more equal in norm. Do not permute.

:math:\mathrm{balanc} = \texttt{'B'}

Both diagonally scale and permute :math:A.

Computed reciprocal condition numbers will be for the matrix after balancing and/or permuting.

Permuting does not change condition numbers (in exact arithmetic), but balancing does.

**jobvl** : str, length 1
If :math:\mathrm{jobvl} = \texttt{'N'}, the left eigenvectors of :math:A are not computed.

If :math:\mathrm{jobvl} = \texttt{'V'}, the left eigenvectors of :math:A are computed.

If :math:\mathrm{sense} = \texttt{'E'} or :math:\texttt{'B'}, :math:\mathrm{jobvl} must be set to :math:\mathrm{jobvl} = \texttt{'V'}.

**jobvr** : str, length 1
If :math:\mathrm{jobvr} = \texttt{'N'}, the right eigenvectors of :math:A are not computed.

If :math:\mathrm{jobvr} = \texttt{'V'}, the right eigenvectors of :math:A are computed.

If :math:\mathrm{sense} = \texttt{'E'} or :math:\texttt{'B'}, :math:\mathrm{jobvr} must be set to :math:\mathrm{jobvr} = \texttt{'V'}.

**sense** : str, length 1
Determines which reciprocal condition numbers are computed.

:math:\mathrm{sense} = \texttt{'N'}

None are computed.

:math:\mathrm{sense} = \texttt{'E'}

Computed for eigenvalues only.

:math:\mathrm{sense} = \texttt{'V'}

Computed for right eigenvectors only.

:math:\mathrm{sense} = \texttt{'B'}

Computed for eigenvalues and right eigenvectors.

If :math:\mathrm{sense} = \texttt{'E'} or :math:\texttt{'B'}, both left and right eigenvectors must also be computed (:math:\mathrm{jobvl} = \texttt{'V'} and :math:\mathrm{jobvr} = \texttt{'V'}).

**a** : complex, array-like, shape :math:\left(n, n\right)
The :math:n\times n matrix :math:A.

**Returns**
**a** : complex, ndarray, shape :math:\left(n, n\right)
:math:\mathrm{a} has been overwritten. If :math:\mathrm{jobvl} = \texttt{'V'} or :math:\mathrm{jobvr} = \texttt{'V'}, :math:A contains the Schur form of the balanced version of the matrix :math:A.

**w** : complex, ndarray, shape :math:\left(n\right)
Contains the computed eigenvalues.

**vl** : complex, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobvl} = \texttt{'V'}, the left eigenvectors :math:u_j are stored one after another in the columns of :math:\mathrm{vl}, in the same order as their corresponding eigenvalues; that is :math:u_j = \mathrm{vl}[\textit{i}-1,j-1], for :math:\textit{i} = 1,2,\ldots,n.

If :math:\mathrm{jobvl} = \texttt{'N'}, :math:\mathrm{vl} is not referenced.

**vr** : complex, ndarray, shape :math:\left(:, :\right)
If :math:\mathrm{jobvr} = \texttt{'V'}, the right eigenvectors :math:v_j are stored one after another in the columns of :math:\mathrm{vr}, in the same order as their corresponding eigenvalues; that is :math:v_j = \mathrm{vr}[\textit{i}-1,j-1], for :math:\textit{i} = 1,2,\ldots,n.

If :math:\mathrm{jobvr} = \texttt{'N'}, :math:\mathrm{vr} is not referenced.

**ilo** : int
:math:\mathrm{ilo} and :math:\mathrm{ihi} are integer values determined when :math:A was balanced. The balanced :math:A has :math:a_{{ij}} = 0 if :math:i > j and :math:j = 1,2,\ldots,\mathrm{ilo}-1 or :math:i = \mathrm{ihi}+1,\ldots,n.

**ihi** : int
:math:\mathrm{ilo} and :math:\mathrm{ihi} are integer values determined when :math:A was balanced. The balanced :math:A has :math:a_{{ij}} = 0 if :math:i > j and :math:j = 1,2,\ldots,\mathrm{ilo}-1 or :math:i = \mathrm{ihi}+1,\ldots,n.

**scale** : float, ndarray, shape :math:\left(n\right)
Details of the permutations and scaling factors applied when balancing :math:A.

If :math:p_j is the index of the row and column interchanged with row and column :math:j, and :math:d_j is the scaling factor applied to row and column :math:j, then

:math:\mathrm{scale}[\textit{j}-1] = p_{\textit{j}}, for :math:\textit{j} = 1,2,\ldots,\mathrm{ilo}-1;

:math:\mathrm{scale}[\textit{j}-1] = d_{\textit{j}}, for :math:\textit{j} = \mathrm{ilo},\ldots,\mathrm{ihi};

:math:\mathrm{scale}[\textit{j}-1] = p_{\textit{j}}, for :math:\textit{j} = \mathrm{ihi}+1,\ldots,n.

The order in which the interchanges are made is :math:\textit{n} to :math:\mathrm{ihi}+1, then :math:1 to :math:\mathrm{ilo}-1.

**abnrm** : float
The :math:1-norm of the balanced matrix (the maximum of the sum of absolute values of elements of any column).

**rconde** : float, ndarray, shape :math:\left(n\right)
:math:\mathrm{rconde}[j-1] is the reciprocal condition number of the :math:j\ th eigenvalue.

**rcondv** : float, ndarray, shape :math:\left(n\right)
:math:\mathrm{rcondv}[j-1] is the reciprocal condition number of the :math:j\ th right eigenvector.

.. _f08np-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On entry, error in parameter :math:\mathrm{balanc}.

Constraint: :math:\mathrm{balanc} = \texttt{'N'}, :math:\texttt{'P'}, :math:\texttt{'S'} or :math:\texttt{'B'}.

(errno :math:-2)
On entry, error in parameter :math:\mathrm{jobvl}.

Constraint: :math:\mathrm{jobvl} = \texttt{'N'} or :math:\texttt{'V'}.

(errno :math:-3)
On entry, error in parameter :math:\mathrm{jobvr}.

Constraint: :math:\mathrm{jobvr} = \texttt{'N'} or :math:\texttt{'V'}.

(errno :math:-4)
On entry, error in parameter :math:\mathrm{sense}.

Constraint: :math:\mathrm{sense} = \texttt{'N'}, :math:\texttt{'E'}, :math:\texttt{'V'} or :math:\texttt{'B'}.

(errno :math:-5)
On entry, error in parameter :math:\textit{n}.

Constraint: :math:n\geq 0.

**Warns**
**NagAlgorithmicWarning**
(errno :math:i > 0)
The :math:QR algorithm failed to compute all the eigenvalues, and no eigenvectors or condition numbers have been computed; elements :math:1 to :math:\mathrm{ilo}-1 and :math:\langle\mathit{\boldsymbol{value}}\rangle to :math:\textit{n} of :math:\mathrm{w} contain eigenvalues which have converged.

.. _f08np-py2-py-notes:

**Notes**
The right eigenvector :math:v_j of :math:A satisfies

.. math::
Av_j = \lambda_jv_j

where :math:\lambda_j is the :math:j\ th eigenvalue of :math:A.
The left eigenvector :math:u_j of :math:A satisfies

.. math::
u_j^\mathrm{H}A = \lambda_ju_j^\mathrm{H}

where :math:u_j^\mathrm{H} denotes the conjugate transpose of :math:u_j.

Balancing a matrix means permuting the rows and columns to make it more nearly upper triangular, and applying a diagonal similarity transformation :math:DAD^{-1}, where :math:D is a diagonal matrix, with the aim of making its rows and columns closer in norm and the condition numbers of its eigenvalues and eigenvectors smaller.
The computed reciprocal condition numbers correspond to the balanced matrix.
Permuting rows and columns will not change the condition numbers (in exact arithmetic) but diagonal scaling will.
For further explanation of balancing, see Section 4.8.1.2 of Anderson et al. (1999).

Following the optional balancing, the matrix :math:A is first reduced to upper Hessenberg form by means of unitary similarity transformations, and the :math:QR algorithm is then used to further reduce the matrix to upper triangular Schur form, :math:T, from which the eigenvalues are computed.
Optionally, the eigenvectors of :math:T are also computed and backtransformed to those of :math:A.

.. _f08np-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 zgehrd(ilo, ihi, a):
r"""
zgehrd reduces a complex general matrix to Hessenberg form.

.. _f08ns-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/f08/f08nsf.html

.. _f08ns-py2-py-parameters:

**Parameters**
**ilo** : int