Source code for naginterfaces.library.lapackeig

# -*- coding: utf-8 -*-
r"""
Module Summary
--------------
Interfaces for the NAG Mark 30.3 `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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08intro.html#available>`__ and the decision trees in `Decision Trees <https://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08intro.html
"""

# NAG Copyright 2017-2024.

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

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

    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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08intro.html>`__ for details). Functions are provided to work with :math:`Q` in this representation (see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08intro.html>`__ for details). Functions are provided to work with :math:`Q` in this representation (see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08intro.html>`__ for details). Functions are provided to work with :math:`Q` in this representation (see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

def zgels(trans, a, b):
    r"""
    ``zgels`` solves linear least squares problems of the form

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

    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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08intro.html>`__ for details). Functions are provided to work with :math:`Q` in this representation (see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08intro.html>`__ for details). Functions are provided to work with :math:`Q` in this representation (see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08intro.html>`__ for details). Functions are provided to work with :math:`Q` in this representation (see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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}[0],\mathrm{jpvt}[1],\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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08intro.html>`__ for details). Functions are provided to work with :math:`Q` in this representation (see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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}[0],\mathrm{jpvt}[1],\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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08intro.html>`__ for details). Functions are provided to work with :math:`Q` in this representation (see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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::
            ZC\text{, }\quad Z^\mathrm{T}C\text{, }\quad CZ\text{, }\quad CZ^\mathrm{T}\text{,}

        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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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}[0],\mathrm{jpvt}[1],\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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08intro.html>`__ for details). Functions are provided to work with :math:`Q` in this representation (see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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}[0],\mathrm{jpvt}[1],\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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08intro.html>`__ for details). Functions are provided to work with :math:`Q` in this representation (see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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::
            ZC\text{, }\quad Z^\mathrm{H}C\text{, }\quad CZ\text{, }\quad CZ^\mathrm{H}\text{,}

        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

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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08intro.html#recomm_36>`__ for details). Functions are provided to work with :math:`Q` in this representation (see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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::
            QC\text{, }\quad Q^\mathrm{T}C\text{, }\quad CQ\text{, }\quad CQ^\mathrm{T}\text{,}

        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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08intro.html>`__ for details). Functions are provided to work with :math:`Q` in this representation (see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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::
            QC\text{, }\quad Q^\mathrm{T}C\text{, }\quad CQ\text{, }\quad CQ^\mathrm{T}\text{,}

        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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08intro.html#recomm_36>`__ for details). Functions are provided to work with :math:`Q` in this representation (see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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::
            QC\text{, }\quad Q^\mathrm{H}C\text{, }\quad CQ\text{, }\quad CQ^\mathrm{H}\text{,}

        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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08intro.html>`__ for details). Functions are provided to work with :math:`Q` in this representation (see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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::
            QC\text{, }\quad Q^\mathrm{H}C\text{, }\quad CQ\text{, }\quad CQ^\mathrm{H}\text{,}

        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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08intro.html>`__ for details). Functions are provided to work with :math:`Q` in this representation (see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08intro.html>`__ for details). Functions are provided to work with :math:`Q` in this representation (see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08intro.html>`__ for details). Functions are provided to work with :math:`Q` in this representation (see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08intro.html>`__ for details). Functions are provided to work with :math:`Q` in this representation (see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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}[0]` 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}[0]`, the second sub-matrix consists of rows/columns :math:`\mathrm{isplit}[0]+1` to :math:`\mathrm{isplit}[1]`, :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

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://support.nag.com/numeric/nl/nagdoc_30.3/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}[0]` 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}[0]` 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

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://support.nag.com/numeric/nl/nagdoc_30.3/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}[0]` 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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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}[0]` 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}[0]` 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

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://support.nag.com/numeric/nl/nagdoc_30.3/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}[0]` 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

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://support.nag.com/numeric/nl/nagdoc_30.3/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}[0]` 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}[0]`.

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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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}[0]` 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}[0]`.

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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08intro.html>`__ for details). Functions are provided to work with :math:`Q` and :math:`P` in this representation (see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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}[5]` and :math:`\textit{work}[6]`.

            :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}[0]/\textit{work}[1]`.

            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}[0]`

                :math:`\alpha = \mathrm{workb}[0]/\mathrm{workb}[1]` 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}[1]`

                See the description of :math:`\mathrm{workb}[0]`.

            :math:`\mathrm{workb}[2]`

                `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}[3]`

                An estimate of the scaled condition number of the triangular factor in the first :math:`QR` factorization.

            :math:`\mathrm{workb}[4]`

                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}[5]`

                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}[6]`

                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}[0]`

                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}[1]`

                The number of computed nonzero singular values.

            :math:`\mathrm{iworkb}[2]`

                If nonzero, a warning message. If :math:`\mathrm{iworkb}[2] = 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

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://support.nag.com/numeric/nl/nagdoc_30.3/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}[1]` 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}[0]`.

            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}[0]`. 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}[0]`

                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}[1]`

                :math:`\mathrm{nint}\left(\mathrm{work}[1]\right)` gives the number of the computed nonzero singular values.

            :math:`\mathrm{work}[2]`

                :math:`\mathrm{nint}\left(\mathrm{work}[2]\right)` gives the number of the computed singular values that are larger than the underflow threshold.

            :math:`\mathrm{work}[3]`

                :math:`\mathrm{nint}\left(\mathrm{work}[3]\right)` gives the number of iterations (sweeps of Jacobi rotations) needed for numerical convergence.

            :math:`\mathrm{work}[4]`

                :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}[5]`

                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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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}[0]` 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}[0]`.

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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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}[0]` 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}[0]`.

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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08intro.html>`__ for details). Functions are provided to work with :math:`Q` and :math:`P` in this representation (see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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}[5]` and :math:`\mathrm{rworkb}[6]`.

            :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}[0]/\mathrm{rworkb}[1]`.

            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}[0]`

                :math:`\alpha = \mathrm{rworkb}[0]/\mathrm{rworkb}[1]` 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}[1]`

                See the description of :math:`\mathrm{rworkb}[0]`.

            :math:`\mathrm{rworkb}[2]`

                :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}[3]`

                An estimate of the scaled condition number of the triangular factor in the first :math:`QR` factorization.

            :math:`\mathrm{rworkb}[4]`

                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}[5]`

                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}[6]`

                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}[0]`

                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}[1]`

                The number of computed nonzero singular values.

            :math:`\mathrm{iworkb}[2]`

                If nonzero, a warning message. If :math:`\mathrm{iworkb}[2] = 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

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://support.nag.com/numeric/nl/nagdoc_30.3/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}[1]` 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}[0]`.

            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}[0]`. 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}[0]`

                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}[1]`

                :math:`\mathrm{nint}\left(\mathrm{rwork}[1]\right)` gives the number of the computed nonzero singular values.

            :math:`\mathrm{rwork}[2]`

                :math:`\mathrm{nint}\left(\mathrm{rwork}[2]\right)` gives the number of the computed singular values that are larger than the underflow threshold.

            :math:`\mathrm{rwork}[3]`

                :math:`\mathrm{nint}\left(\mathrm{rwork}[3]\right)` gives the number of iterations (sweeps of Jacobi rotations) needed for numerical convergence.

            :math:`\mathrm{rwork}[4]`

                :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}[5]`

                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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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::
            Bu_i = \sigma_iv_i\quad \text{ and }\quad B^\mathrm{T}v_i = \sigma_iu_i\text{, }\quad i = 1,2,\ldots,n\text{.}

        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

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://support.nag.com/numeric/nl/nagdoc_30.3/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::
            Bu_i = \sigma_iv_i\quad \text{ and }\quad B^\mathrm{T}v_i = \sigma_iu_i\text{, }\quad i = 1,2,\ldots,n\text{.}

        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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08intro.html>`__ for details). Functions are provided to work with :math:`Q` in this representation (see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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

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://support.nag.com/numeric/nl/nagdoc_30.3/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