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

def zgehrd(ilo, ihi, a):
    r"""
    ``zgehrd`` reduces a complex general matrix to Hessenberg form.

    .. _f08ns-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08nsf.html

    .. _f08ns-py2-py-parameters:

    **Parameters**
        **ilo** : int
            If :math:`A` has been output by :meth:`zgebal`, :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:`zgebal`, :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** : complex, array-like, shape :math:`\left(n, n\right)`
            The :math:`n\times n` general matrix :math:`A`.

    **Returns**
        **a** : complex, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{a}` is overwritten by the upper Hessenberg matrix :math:`H` and details of the unitary matrix :math:`Q`. The subdiagonal elements of :math:`H` are real.

        **tau** : complex, ndarray, shape :math:`\left(\max\left(1,{n-1}\right)\right)`
            Further details of the unitary matrix :math:`Q`.

    .. _f08ns-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}`.

    .. _f08ns-py2-py-notes:

    **Notes**
        ``zgehrd`` reduces a complex general matrix :math:`A` to upper Hessenberg form :math:`H` by a unitary similarity transformation: :math:`A = QHQ^\mathrm{H}`. :math:`H` has real subdiagonal elements.

        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/f08nsf.html#fcomments>`__).

        The function can take advantage of a previous call to :meth:`zgebal`, 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:`zgebal` can be supplied to the function directly.
        If :meth:`zgebal` 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`.

    .. _f08ns-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 zunghr(ilo, ihi, a, tau):
    r"""
    ``zunghr`` generates the complex unitary matrix :math:`Q` which was determined by :meth:`zgehrd` when reducing a complex general matrix :math:`A` to Hessenberg form.

    .. _f08nt-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08ntf.html

    .. _f08nt-py2-py-parameters:

    **Parameters**
        **ilo** : int
            These **must** be the same arguments :math:`\mathrm{ilo}` and :math:`\mathrm{ihi}`, respectively, as supplied to :meth:`zgehrd`.

        **ihi** : int
            These **must** be the same arguments :math:`\mathrm{ilo}` and :math:`\mathrm{ihi}`, respectively, as supplied to :meth:`zgehrd`.

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

        **tau** : complex, array-like, shape :math:`\left(\max\left(1,{n-1}\right)\right)`
            Further details of the elementary reflectors, as returned by :meth:`zgehrd`.

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

    .. _f08nt-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}`.

    .. _f08nt-py2-py-notes:

    **Notes**
        ``zunghr`` is intended to be used following a call to :meth:`zgehrd`, which reduces a complex general matrix :math:`A` to upper Hessenberg form :math:`H` by a unitary similarity transformation: :math:`A = QHQ^\mathrm{H}`. :meth:`zgehrd` 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:`zgebal` 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}}`.

    .. _f08nt-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 zunmhr(side, trans, ilo, ihi, a, tau, c):
    r"""
    ``zunmhr`` multiplies an arbitrary complex matrix :math:`C` by the complex unitary matrix :math:`Q` which was determined by :meth:`zgehrd` when reducing a complex general matrix to Hessenberg form.

    .. _f08nu-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08nuf.html

    .. _f08nu-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`.

        **ilo** : int
            These **must** be the same arguments :math:`\mathrm{ilo}` and :math:`\mathrm{ihi}`, respectively, as supplied to :meth:`zgehrd`.

        **ihi** : int
            These **must** be the same arguments :math:`\mathrm{ilo}` and :math:`\mathrm{ihi}`, respectively, as supplied to :meth:`zgehrd`.

        **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:`zgehrd`.

        **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:`zgehrd`.

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

    .. _f08nu-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:`\mathrm{ilo}`.

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

    .. _f08nu-py2-py-notes:

    **Notes**
        ``zunmhr`` is intended to be used following a call to :meth:`zgehrd`, which reduces a complex general matrix :math:`A` to upper Hessenberg form :math:`H` by a unitary similarity transformation: :math:`A = QHQ^\mathrm{H}`. :meth:`zgehrd` 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:`zgebal` 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{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:`V` of eigenvectors of :math:`H` to the matrix :math:`\textit{QV}` of eigenvectors of :math:`A`.

    .. _f08nu-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 zgebal(job, n, a):
    r"""
    ``zgebal`` balances a complex general matrix in order to improve the accuracy of computed eigenvalues and/or eigenvectors.

    .. _f08nv-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08nvf.html

    .. _f08nv-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** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)`
            The :math:`n\times n` matrix :math:`A`.

    **Returns**
        **a** : complex, 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`.

    .. _f08nv-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`.

    .. _f08nv-py2-py-notes:

    **Notes**
        ``zgebal`` balances a complex 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.

    .. _f08nv-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 zgebak(job, side, ilo, ihi, scale, v):
    r"""
    ``zgebak`` transforms eigenvectors of a balanced matrix to those of the original complex general matrix.

    .. _f08nw-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08nwf.html

    .. _f08nw-py2-py-parameters:

    **Parameters**
        **job** : str, length 1
            This **must** be the same argument :math:`\mathrm{job}` as supplied to :meth:`zgebal`.

        **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:`zgebal`.

        **ihi** : int
            The values :math:`i_{\mathrm{lo}}` and :math:`i_{\mathrm{hi}}`, as returned by :meth:`zgebal`.

        **scale** : float, array-like, shape :math:`\left(n\right)`
            Details of the permutations and/or the scaling factors used to balance the original complex general matrix, as returned by :meth:`zgebal`.

        **v** : complex, array-like, shape :math:`\left(n, m\right)`
            The matrix of left or right eigenvectors to be transformed.

    **Returns**
        **v** : complex, ndarray, shape :math:`\left(n, m\right)`
            The transformed eigenvectors.

    .. _f08nw-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`.

    .. _f08nw-py2-py-notes:

    **Notes**
        ``zgebak`` is intended to be used after a complex general matrix :math:`A` has been balanced by :meth:`zgebal`, 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:`zgebal`.
        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 dgees(jobvs, sort, a, select=None, data=None):
    r"""
    ``dgees`` computes the eigenvalues, the real Schur form :math:`T`, and, optionally, the matrix of Schur vectors :math:`Z` for an :math:`n\times n` real nonsymmetric matrix :math:`A`.

    .. _f08pa-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08paf.html

    .. _f08pa-py2-py-parameters:

    **Parameters**
        **jobvs** : str, length 1
            If :math:`\mathrm{jobvs} = \texttt{'N'}`, Schur vectors are not computed.

            If :math:`\mathrm{jobvs} = \texttt{'V'}`, Schur vectors are computed.

        **sort** : str, length 1
            Specifies whether or not to order the eigenvalues on the diagonal of the Schur form.

            :math:`\mathrm{sort} = \texttt{'N'}`

                Eigenvalues are not ordered.

            :math:`\mathrm{sort} = \texttt{'S'}`

                Eigenvalues are ordered (see :math:`\mathrm{select}`).

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

        **select** : None or callable retval = select(wr, wi, data=None), optional
            Note: if this argument is **None** then a NAG-supplied facility will be used.

            If :math:`\mathrm{sort} = \texttt{'S'}`, :math:`\mathrm{select}` is used to select eigenvalues to sort to the top left of the Schur form.

            An eigenvalue :math:`\mathrm{wr}[j-1]+\sqrt{-1}\times \mathrm{wi}[j-1]` is selected if :math:`\mathrm{select}\left(\mathrm{wr}[j-1], \mathrm{wi}[j-1]\right)` is :math:`\mathbf{True}`.

            If either one of a complex conjugate pair of eigenvalues is selected, then both are.

            Note that a selected complex eigenvalue may no longer satisfy :math:`\mathrm{select}\left(\mathrm{wr}[j-1], \mathrm{wi}[j-1]\right) = \mathbf{True}` after ordering, since ordering may change the value of complex eigenvalues (especially if the eigenvalue is ill-conditioned); in this case :math:`\textit{errno}` is set to :math:`n+2`.

            **Parameters**
                **wr** : float
                    The real and imaginary parts of the eigenvalue.

                **wi** : float
                    The real and imaginary parts of the eigenvalue.

                **data** : arbitrary, optional, modifiable in place
                    User-communication data for callback functions.

            **Returns**
                **retval** : bool
                    Must be :math:`\mathbf{True}` if the eigenvalue is to be selected.

        **data** : arbitrary, optional
            User-communication data for callback functions.

    **Returns**
        **a** : float, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{a}` is overwritten by its real Schur form :math:`T`.

        **sdim** : int
            If :math:`\mathrm{sort} = \texttt{'N'}`, :math:`\mathrm{sdim} = 0`.

            If :math:`\mathrm{sort} = \texttt{'S'}`, :math:`\mathrm{sdim} = \text{}` number of eigenvalues (after sorting) for which :math:`\mathrm{select}` is :math:`\mathbf{True}`. (Complex conjugate pairs for which :math:`\mathrm{select}` is :math:`\mathbf{True}` for either eigenvalue count as :math:`2`.)

        **wr** : float, ndarray, shape :math:`\left(n\right)`
            See the description of :math:`\mathrm{wi}`.

        **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 in the same order that they appear on the diagonal of the output Schur form :math:`T`. Complex conjugate pairs of eigenvalues will appear consecutively with the eigenvalue having the positive imaginary part first.

        **vs** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobvs} = \texttt{'V'}`, :math:`\mathrm{vs}` contains the orthogonal matrix :math:`Z` of Schur vectors.

            If :math:`\mathrm{jobvs} = \texttt{'N'}`, :math:`\mathrm{vs}` is not referenced.

    .. _f08pa-py2-py-errors:

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

                Constraint: :math:`\mathrm{jobvs} = \texttt{'N'}` or :math:`\texttt{'V'}`.

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

                Constraint: :math:`\mathrm{sort} = \texttt{'N'}` or :math:`\texttt{'S'}`.

            (`errno` :math:`-4`)
                On entry, error in parameter :math:`\textit{n}`.

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

            (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq n\right)`)
                The :math:`QR` algorithm failed to compute all the eigenvalues.

    **Warns**
        **NagAlgorithmicWarning**
            (`errno` :math:`n+1`)
                The eigenvalues could not be reordered because some eigenvalues were too close to separate (the problem is very ill-conditioned).

            (`errno` :math:`n+2`)
                After reordering, roundoff changed values of some complex eigenvalues so that leading eigenvalues in the Schur form no longer satisfy :math:`\mathrm{select} = \mathbf{True}`. This could also be caused by underflow due to scaling.

    .. _f08pa-py2-py-notes:

    **Notes**
        The real Schur factorization of :math:`A` is given by

        .. math::
            A = ZTZ^\mathrm{T}\text{,}

        where :math:`Z`, the matrix of Schur vectors, is orthogonal and :math:`T` is the real Schur form.
        A matrix is in real Schur form if it is upper quasi-triangular with :math:`1\times 1` and :math:`2\times 2` blocks. :math:`2\times 2` blocks will be standardized in the form

        .. math::
            \left[\begin{array}{cc}a&b\\c&a\end{array}\right]

        where :math:`bc < 0`.
        The eigenvalues of such a block are :math:`a\pm \sqrt{bc}`.

        Optionally, ``dgees`` also orders the eigenvalues on the diagonal of the real Schur form so that selected eigenvalues are at the top left.
        The leading columns of :math:`Z` form an orthonormal basis for the invariant subspace corresponding to the selected eigenvalues.

    .. _f08pa-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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 dgeesx(jobvs, sort, sense, a, select=None, data=None):
    r"""
    ``dgeesx`` computes the eigenvalues, the real Schur form :math:`T`, and, optionally, the matrix of Schur vectors :math:`Z` for an :math:`n\times n` real nonsymmetric matrix :math:`A`.

    .. _f08pb-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08pbf.html

    .. _f08pb-py2-py-parameters:

    **Parameters**
        **jobvs** : str, length 1
            If :math:`\mathrm{jobvs} = \texttt{'N'}`, Schur vectors are not computed.

            If :math:`\mathrm{jobvs} = \texttt{'V'}`, Schur vectors are computed.

        **sort** : str, length 1
            Specifies whether or not to order the eigenvalues on the diagonal of the Schur form.

            :math:`\mathrm{sort} = \texttt{'N'}`

                Eigenvalues are not ordered.

            :math:`\mathrm{sort} = \texttt{'S'}`

                Eigenvalues are ordered (see :math:`\mathrm{select}`).

        **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 average of selected eigenvalues only.

            :math:`\mathrm{sense} = \texttt{'V'}`

                Computed for selected right invariant subspace only.

            :math:`\mathrm{sense} = \texttt{'B'}`

                Computed for both.

            If :math:`\mathrm{sense} = \texttt{'E'}`, :math:`\texttt{'V'}` or :math:`\texttt{'B'}`, :math:`\mathrm{sort} = \texttt{'S'}`.

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

        **select** : None or callable retval = select(wr, wi, data=None), optional
            Note: if this argument is **None** then a NAG-supplied facility will be used.

            If :math:`\mathrm{sort} = \texttt{'S'}`, :math:`\mathrm{select}` is used to select eigenvalues to sort to the top left of the Schur form.

            An eigenvalue :math:`\mathrm{wr}[j-1]+\sqrt{-1}\times \mathrm{wi}[j-1]` is selected if :math:`\mathrm{select}\left(\mathrm{wr}[j-1], \mathrm{wi}[j-1]\right)` is :math:`\mathbf{True}`.

            If either one of a complex conjugate pair of eigenvalues is selected, then both are.

            Note that a selected complex eigenvalue may no longer satisfy :math:`\mathrm{select}\left(\mathrm{wr}[j-1], \mathrm{wi}[j-1]\right) = \mathbf{True}` after ordering, since ordering may change the value of complex eigenvalues (especially if the eigenvalue is ill-conditioned); in this case :math:`\textit{errno}` is set to :math:`n+2`.

            **Parameters**
                **wr** : float
                    The real and imaginary parts of the eigenvalue.

                **wi** : float
                    The real and imaginary parts of the eigenvalue.

                **data** : arbitrary, optional, modifiable in place
                    User-communication data for callback functions.

            **Returns**
                **retval** : bool
                    Must be :math:`\mathbf{True}` if the eigenvalue is to be selected.

        **data** : arbitrary, optional
            User-communication data for callback functions.

    **Returns**
        **a** : float, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{a}` is overwritten by its real Schur form :math:`T`.

        **sdim** : int
            If :math:`\mathrm{sort} = \texttt{'N'}`, :math:`\mathrm{sdim} = 0`.

            If :math:`\mathrm{sort} = \texttt{'S'}`, :math:`\mathrm{sdim} = \text{}` number of eigenvalues (after sorting) for which :math:`\mathrm{select}` is :math:`\mathbf{True}`. (Complex conjugate pairs for which :math:`\mathrm{select}` is :math:`\mathbf{True}` for either eigenvalue count as :math:`2`.)

        **wr** : float, ndarray, shape :math:`\left(n\right)`
            See the description of :math:`\mathrm{wi}`.

        **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 in the same order that they appear on the diagonal of the output Schur form :math:`T`. Complex conjugate pairs of eigenvalues will appear consecutively with the eigenvalue having the positive imaginary part first.

        **vs** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobvs} = \texttt{'V'}`, :math:`\mathrm{vs}` contains the orthogonal matrix :math:`Z` of Schur vectors.

            If :math:`\mathrm{jobvs} = \texttt{'N'}`, :math:`\mathrm{vs}` is not referenced.

        **rconde** : float
            If :math:`\mathrm{sense} = \texttt{'E'}` or :math:`\texttt{'B'}`, contains the reciprocal condition number for the average of the selected eigenvalues.

            If :math:`\mathrm{sense} = \texttt{'N'}` or :math:`\texttt{'V'}`, :math:`\mathrm{rconde}` is not referenced.

        **rcondv** : float
            If :math:`\mathrm{sense} = \texttt{'V'}` or :math:`\texttt{'B'}`, :math:`\mathrm{rcondv}` contains the reciprocal condition number for the selected right invariant subspace.

            If :math:`\mathrm{sense} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{rcondv}` is not referenced.

    .. _f08pb-py2-py-errors:

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

                Constraint: :math:`\mathrm{jobvs} = \texttt{'N'}` or :math:`\texttt{'V'}`.

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

                Constraint: :math:`\mathrm{sort} = \texttt{'N'}` or :math:`\texttt{'S'}`.

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

            (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq n\right)`)
                The :math:`QR` algorithm failed to compute all the eigenvalues.

    **Warns**
        **NagAlgorithmicWarning**
            (`errno` :math:`n+1`)
                The eigenvalues could not be reordered because some eigenvalues were too close to separate (the problem is very ill-conditioned).

            (`errno` :math:`n+2`)
                After reordering, roundoff changed values of some complex eigenvalues so that leading eigenvalues in the Schur form no longer satisfy :math:`\mathrm{select} = \mathbf{True}`. This could also be caused by underflow due to scaling.

    .. _f08pb-py2-py-notes:

    **Notes**
        The real Schur factorization of :math:`A` is given by

        .. math::
            A = ZTZ^\mathrm{T}\text{,}

        where :math:`Z`, the matrix of Schur vectors, is orthogonal and :math:`T` is the real Schur form.
        A matrix is in real Schur form if it is upper quasi-triangular with :math:`1\times 1` and :math:`2\times 2` blocks. :math:`2\times 2` blocks will be standardized in the form

        .. math::
            \left[\begin{array}{cc}a&b\\c&a\end{array}\right]

        where :math:`bc < 0`.
        The eigenvalues of such a block are :math:`a\pm \sqrt{bc}`.

        Optionally, ``dgeesx`` also orders the eigenvalues on the diagonal of the real Schur form so that selected eigenvalues are at the top left; computes a reciprocal condition number for the average of the selected eigenvalues (:math:`\mathrm{rconde}`); and computes a reciprocal condition number for the right invariant subspace corresponding to the selected eigenvalues (:math:`\mathrm{rcondv}`).
        The leading columns of :math:`Z` form an orthonormal basis for this invariant subspace.

        For further explanation of the reciprocal condition numbers :math:`\mathrm{rconde}` and :math:`\mathrm{rcondv}`, see Section 4.8 of Anderson `et al.` (1999) (where these quantities are called :math:`s` and :math:`\textit{sep}` respectively).

    .. _f08pb-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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 dhseqr(job, compz, ilo, ihi, h, z):
    r"""
    ``dhseqr`` computes all the eigenvalues and, optionally, the Schur factorization of a real Hessenberg matrix or a real general matrix which has been reduced to Hessenberg form.

    .. _f08pe-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08pef.html

    .. _f08pe-py2-py-parameters:

    **Parameters**
        **job** : str, length 1
            Indicates whether eigenvalues only or the Schur form :math:`T` is required.

            :math:`\mathrm{job} = \texttt{'E'}`

                Eigenvalues only are required.

            :math:`\mathrm{job} = \texttt{'S'}`

                The Schur form :math:`T` is required.

        **compz** : str, length 1
            Indicates whether the Schur vectors are to be computed.

            :math:`\mathrm{compz} = \texttt{'N'}`

                No Schur vectors are computed (and the array :math:`\mathrm{z}` is not referenced).

            :math:`\mathrm{compz} = \texttt{'V'}`

                The Schur vectors 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 Schur vectors of :math:`H` are computed (and the array :math:`\mathrm{z}` is initialized by the function).

        **ilo** : int
            If the matrix :math:`A` has been balanced 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 the matrix :math:`A` has been balanced 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}`.

        **h** : float, array-like, shape :math:`\left(n, n\right)`
            The :math:`n\times n` upper Hessenberg matrix :math:`H`, as returned by :meth:`dgehrd`.

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

            If :math:`\mathrm{compz} = \texttt{'I'}`, :math:`\mathrm{z}` need not be set.

    **Returns**
        **h** : float, ndarray, shape :math:`\left(n, n\right)`
            If :math:`\mathrm{job} = \texttt{'E'}`, the array contains no useful information.

            If :math:`\mathrm{job} = \texttt{'S'}`, :math:`\mathrm{h}` is overwritten by the upper quasi-triangular matrix :math:`T` from the Schur decomposition (the Schur form) unless :math:`\mathrm{errno}` > 0.

        **wr** : float, ndarray, shape :math:`\left(n\right)`
            The real and imaginary parts, respectively, of the computed eigenvalues, unless :math:`\mathrm{errno}` > 0 (in which case see :ref:`Exceptions <f08pe-py2-py-errors>`). Complex conjugate pairs of eigenvalues appear consecutively with the eigenvalue having positive imaginary part first. The eigenvalues are stored in the same order as on the diagonal of the Schur form :math:`T` (if computed); see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08pef.html#fcomments>`__ for details.

        **wi** : float, ndarray, shape :math:`\left(n\right)`
            The real and imaginary parts, respectively, of the computed eigenvalues, unless :math:`\mathrm{errno}` > 0 (in which case see :ref:`Exceptions <f08pe-py2-py-errors>`). Complex conjugate pairs of eigenvalues appear consecutively with the eigenvalue having positive imaginary part first. The eigenvalues are stored in the same order as on the diagonal of the Schur form :math:`T` (if computed); see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08pef.html#fcomments>`__ for details.

        **z** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{compz} = \texttt{'V'}` or :math:`\texttt{'I'}`, :math:`\mathrm{z}` contains the orthogonal matrix of the required Schur vectors, unless :math:`\mathrm{errno}` > 0.

            If :math:`\mathrm{compz} = \texttt{'N'}`, :math:`\mathrm{z}` is not referenced.

    .. _f08pe-py2-py-errors:

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

                Constraint: :math:`\mathrm{job} = \texttt{'E'}` or :math:`\texttt{'S'}`.

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

                Constraint: :math:`\mathrm{compz} = \texttt{'N'}`, :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:`-4`)
                On entry, error in parameter :math:`\mathrm{ilo}`.

            (`errno` :math:`-5`)
                On entry, error in parameter :math:`\mathrm{ihi}`.

    **Warns**
        **NagAlgorithmicWarning**
            (`errno` :math:`i > 0`)
                The algorithm has failed to find all the eigenvalues after a total of :math:`30\left(\mathrm{ihi}-\mathrm{ilo}+1\right)` iterations.

    .. _f08pe-py2-py-notes:

    **Notes**
        ``dhseqr`` computes all the eigenvalues and, optionally, the Schur factorization of a real upper Hessenberg matrix :math:`H`:

        .. math::
            H = ZTZ^\mathrm{T}\text{,}

        where :math:`T` is an upper quasi-triangular matrix (the Schur form of :math:`H`), and :math:`Z` is the orthogonal matrix whose columns are the Schur vectors :math:`z_i`.
        See `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08pef.html#fcomments>`__ for details of the structure of :math:`T`.

        The function may also be used to compute the Schur factorization of a real general matrix :math:`A` which has been reduced to upper Hessenberg form :math:`H`:

        .. math::
            \begin{array}{lll}A& = &QHQ^\mathrm{T}\text{, where }Q\text{ is orthogonal,}\\& = &\left(QZ\right)T\left(QZ\right)^\mathrm{T}\text{.}\end{array}

        In this case, after :meth:`dgehrd` has been called to reduce :math:`A` to Hessenberg form, :meth:`dorghr` must be called to form :math:`Q` explicitly; :math:`Q` is then passed to ``dhseqr``, which must be called with :math:`\mathrm{compz} = \texttt{'V'}`.

        The function can also take advantage of a previous call to :meth:`dgebal` which may have balanced the original matrix before reducing it to Hessenberg form, so that the Hessenberg matrix :math:`H` has the structure:

        .. math::
            \begin{pmatrix}H_{11}&H_{12}&H_{13}\\&H_{22}&H_{23}\\&&H_{33}\end{pmatrix}

        where :math:`H_{11}` and :math:`H_{33}` are upper triangular.
        If so, only the central diagonal block :math:`H_{22}` (in rows and columns :math:`i_{\mathrm{lo}}` to :math:`i_{\mathrm{hi}}`) needs to be further reduced to Schur form (the blocks :math:`H_{12}` and :math:`H_{23}` are also affected).
        Therefore, the values of :math:`i_{\mathrm{lo}}` and :math:`i_{\mathrm{hi}}` can be supplied to ``dhseqr`` directly.
        Also, :meth:`dgebak` must be called after this function to permute the Schur vectors of the balanced matrix to those of the original matrix.
        If :meth:`dgebal` has not been called however, then :math:`i_{\mathrm{lo}}` must be set to :math:`1` and :math:`i_{\mathrm{hi}}` to :math:`n`.
        Note that if the Schur factorization of :math:`A` is required, :meth:`dgebal` must **not** be called with :math:`{\textit{job}} = \texttt{'S'}` or :math:`\texttt{'B'}`, because the balancing transformation is not orthogonal.

        ``dhseqr`` uses a multishift form of the upper Hessenberg :math:`QR` algorithm, due to Bai and Demmel (1989).
        The Schur vectors are normalized so that :math:`\left\lVert z_i\right\rVert_2 = 1`, but are determined only to within a factor :math:`{\pm 1}`.

    .. _f08pe-py2-py-references:

    **References**
        Bai, Z and Demmel, J W, 1989, `On a block implementation of Hessenberg multishift` :math:`{QR}` `iteration`, Internat. J. High Speed Comput. (1), 97--112

        Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
    """
    raise NotImplementedError

def dhsein(job, eigsrc, initv, select, h, wr, wi, vl, vr):
    r"""
    ``dhsein`` computes selected left and/or right eigenvectors of a real upper Hessenberg matrix corresponding to specified eigenvalues, by inverse iteration.

    .. _f08pk-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08pkf.html

    .. _f08pk-py2-py-parameters:

    **Parameters**
        **job** : str, length 1
            Indicates whether left and/or right eigenvectors are to be computed.

            :math:`\mathrm{job} = \texttt{'R'}`

                Only right eigenvectors are computed.

            :math:`\mathrm{job} = \texttt{'L'}`

                Only left eigenvectors are computed.

            :math:`\mathrm{job} = \texttt{'B'}`

                Both left and right eigenvectors are computed.

        **eigsrc** : str, length 1
            Indicates whether the eigenvalues of :math:`H` (stored in :math:`\mathrm{wr}` and :math:`\mathrm{wi}`) were found using :meth:`dhseqr`.

            :math:`\mathrm{eigsrc} = \texttt{'Q'}`

                The eigenvalues of :math:`H` were found using :meth:`dhseqr`; thus if :math:`H` has any zero subdiagonal elements (and so is block triangular), then the :math:`j`\ th eigenvalue can be assumed to be an eigenvalue of the block containing the :math:`j`\ th row/column. This property allows the function to perform inverse iteration on just one diagonal block.

            :math:`\mathrm{eigsrc} = \texttt{'N'}`

                No such assumption is made and the function performs inverse iteration using the whole matrix.

        **initv** : str, length 1
            Indicates whether you are supplying initial estimates for the selected eigenvectors.

            :math:`\mathrm{initv} = \texttt{'N'}`

                No initial estimates are supplied.

            :math:`\mathrm{initv} = \texttt{'U'}`

                Initial estimates are supplied in :math:`\mathrm{vl}` and/or :math:`\mathrm{vr}`.

        **select** : bool, array-like, shape :math:`\left(n\right)`
            Specifies which eigenvectors are to be computed. To obtain the real eigenvector corresponding to the real eigenvalue :math:`\mathrm{wr}[j-1]`, :math:`\mathrm{select}[j-1]` must be set :math:`\mathbf{True}`. To select the complex eigenvector corresponding to the complex eigenvalue :math:`\left({\mathrm{wr}[j-1]}, {\mathrm{wi}[j-1]}\right)` with complex conjugate (:math:`\mathrm{wr}[j],\mathrm{wi}[j]`), :math:`\mathrm{select}[j-1]` and/or :math:`\mathrm{select}[j]` must be set :math:`\mathbf{True}`; the eigenvector corresponding to the **first** eigenvalue in the pair is computed.

        **h** : float, array-like, shape :math:`\left(n, n\right)`
            The :math:`n\times n` upper Hessenberg matrix :math:`H`. If a NaN is detected in :math:`\mathrm{h}`, the function will return with :math:`\mathrm{errno}` = -6.

        **wr** : float, array-like, shape :math:`\left(n\right)`
            The real and imaginary parts, respectively, of the eigenvalues of the matrix :math:`H`. Complex conjugate pairs of values must be stored in consecutive elements of the arrays. If :math:`\mathrm{eigsrc} = \texttt{'Q'}`, the arrays **must** be exactly as returned by :meth:`dhseqr`.

        **wi** : float, array-like, shape :math:`\left(n\right)`
            The real and imaginary parts, respectively, of the eigenvalues of the matrix :math:`H`. Complex conjugate pairs of values must be stored in consecutive elements of the arrays. If :math:`\mathrm{eigsrc} = \texttt{'Q'}`, the arrays **must** be exactly as returned by :meth:`dhseqr`.

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

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{job}\text{ in } (\texttt{'L'}, \texttt{'B'})`: :math:`\textit{mm}`; if :math:`\mathrm{job}=\texttt{'R'}`: :math:`1`; otherwise: :math:`0`.

            If :math:`\mathrm{initv} = \texttt{'U'}` and :math:`\mathrm{job} = \texttt{'L'}` or :math:`\texttt{'B'}`, :math:`\mathrm{vl}` must contain starting vectors for inverse iteration for the left eigenvectors. Each starting vector must be stored in the same column or columns as will be used to store the corresponding eigenvector.

            If :math:`\mathrm{initv} = \texttt{'N'}`, :math:`\mathrm{vl}` need not be set.

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

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{job}\text{ in } (\texttt{'R'}, \texttt{'B'})`: :math:`\textit{mm}`; if :math:`\mathrm{job}=\texttt{'L'}`: :math:`1`; otherwise: :math:`0`.

            If :math:`\mathrm{initv} = \texttt{'U'}` and :math:`\mathrm{job} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{vr}` must contain starting vectors for inverse iteration for the right eigenvectors. Each starting vector must be stored in the same column or columns as will be used to store the corresponding eigenvector.

            If :math:`\mathrm{initv} = \texttt{'N'}`, :math:`\mathrm{vr}` need not be set.

    **Returns**
        **select** : bool, ndarray, shape :math:`\left(n\right)`
            If a complex eigenvector was selected as specified above, :math:`\mathrm{select}[j-1]` is set to :math:`\mathbf{True}` and :math:`\mathrm{select}[j]` to :math:`\mathbf{False}`.

        **wr** : float, ndarray, shape :math:`\left(n\right)`
            Some elements of :math:`\mathrm{wr}` may be modified, as close eigenvalues are perturbed slightly in searching for independent eigenvectors.

        **vl** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{job} = \texttt{'L'}` or :math:`\texttt{'B'}`, :math:`\mathrm{vl}` contains the computed left eigenvectors (as specified by :math:`\mathrm{select}`). The eigenvectors are stored consecutively in the columns of the array, in the same order as their eigenvalues. Corresponding to each selected real eigenvalue is a real eigenvector, occupying one column. Corresponding to each selected complex eigenvalue is a complex eigenvector, occupying two columns: the first column holds the real part and the second column holds the imaginary part.

            If :math:`\mathrm{job} = \texttt{'R'}`, :math:`\mathrm{vl}` is not referenced.

        **vr** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{job} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{vr}` contains the computed right eigenvectors (as specified by :math:`\mathrm{select}`). The eigenvectors are stored consecutively in the columns of the array, in the same order as their eigenvalues. Corresponding to each selected real eigenvalue is a real eigenvector, occupying one column. Corresponding to each selected complex eigenvalue is a complex eigenvector, occupying two columns: the first column holds the real part and the second column holds the imaginary part.

            If :math:`\mathrm{job} = \texttt{'L'}`, :math:`\mathrm{vr}` is not referenced.

        **m** : int
            :math:`\textit{m}`, the number of columns of :math:`\mathrm{vl}` and/or :math:`\mathrm{vr}` required to store the selected eigenvectors.

        **ifaill** : int, ndarray, shape :math:`\left(:\right)`
            If :math:`\mathrm{job} = \texttt{'L'}` or :math:`\texttt{'B'}`, then :math:`\mathrm{ifaill}[i-1] = 0` if the selected left eigenvector converged and :math:`\mathrm{ifaill}[i-1] = j > 0` if the eigenvector stored in the :math:`i`\ th column of :math:`\mathrm{vl}` (corresponding to the :math:`j`\ th eigenvalue as held in :math:`\left({\mathrm{wr}[j-1]}, {\mathrm{wi}[j-1]}\right)` failed to converge. If the :math:`i`\ th and :math:`\left(i+1\right)`\ th columns of :math:`\mathrm{vl}` contain a selected complex eigenvector, then :math:`\mathrm{ifaill}[i-1]` and :math:`\mathrm{ifaill}[i]` are set to the same value.

            If :math:`\mathrm{job} = \texttt{'R'}`, :math:`\mathrm{ifaill}` is not referenced.

        **ifailr** : int, ndarray, shape :math:`\left(:\right)`
            If :math:`\mathrm{job} = \texttt{'R'}` or :math:`\texttt{'B'}`, then :math:`\mathrm{ifailr}[i-1] = 0` if the selected right eigenvector converged and :math:`\mathrm{ifailr}[i-1] = j > 0` if the eigenvector stored in the :math:`i`\ th row or column of :math:`\mathrm{vr}` (corresponding to the :math:`j`\ th eigenvalue as held in :math:`\left({\mathrm{wr}[j-1]}, {\mathrm{wi}[j-1]}\right)`) failed to converge. If the :math:`i`\ th and :math:`\left(i+1\right)`\ th rows or columns of :math:`\mathrm{vr}` contain a selected complex eigenvector, then :math:`\mathrm{ifailr}[i-1]` and :math:`\mathrm{ifailr}[i]` are set to the same value.

            If :math:`\mathrm{job} = \texttt{'L'}`, :math:`\mathrm{ifailr}` is not referenced.

    .. _f08pk-py2-py-errors:

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

                Constraint: :math:`\mathrm{job} = \texttt{'R'}`, :math:`\texttt{'L'}` or :math:`\texttt{'B'}`.

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

                Constraint: :math:`\mathrm{eigsrc} = \texttt{'Q'}` or :math:`\texttt{'N'}`.

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

                Constraint: :math:`\mathrm{initv} = \texttt{'N'}` or :math:`\texttt{'U'}`.

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

                Constraint: No element of :math:`\mathrm{h}` is equal to NaN.

            (`errno` :math:`-14`)
                On entry, error in parameter :math:`\textit{mm}`.

                Constraint: :math:`\textit{mm}\geq \textit{m}`.

    **Warns**
        **NagAlgorithmicWarning**
            (`errno` :math:`i > 0`)
                :math:`\langle\mathit{\boldsymbol{value}}\rangle` eigenvectors (as indicated by arguments :math:`\mathrm{ifaill}` and/or :math:`\mathrm{ifailr}`) failed to converge. The corresponding columns of :math:`\mathrm{vl}` and/or :math:`\mathrm{vr}` contain no useful information.

    .. _f08pk-py2-py-notes:

    **Notes**
        ``dhsein`` computes left and/or right eigenvectors of a real upper Hessenberg matrix :math:`H`, corresponding to selected eigenvalues.

        The right eigenvector :math:`x`, and the left eigenvector :math:`y`, corresponding to an eigenvalue :math:`\lambda`, are defined by:

        .. math::
            Hx = \lambda x\quad \text{ and }\quad y^\mathrm{H}H = \lambda y^\mathrm{H}\left(\quad \text{ or }H^\mathrm{T}y = \bar{\lambda }y\right)\text{.}

        Note that even though :math:`H` is real, :math:`\lambda`, :math:`x` and :math:`y` may be complex.
        If :math:`x` is an eigenvector corresponding to a complex eigenvalue :math:`\lambda`, then the complex conjugate vector :math:`\bar{x}` is the eigenvector corresponding to the complex conjugate eigenvalue :math:`\bar{\lambda }`.

        The eigenvectors are computed by inverse iteration.
        They are scaled so that, for a real eigenvector :math:`x`, :math:`\mathrm{max}\left(\left\lvert x_i\right\rvert \right) = 1`, and for a complex eigenvector, :math:`\mathrm{max}\left({\left\lvert \mathrm{Re}\left(x_i\right)\right\rvert +\left\lvert \mathrm{Im}\left(x_i\right)\right\rvert }\right) = 1`.

        If :math:`H` has been formed by reduction of a real general matrix :math:`A` to upper Hessenberg form, then the eigenvectors of :math:`H` may be transformed to eigenvectors of :math:`A` by a call to :meth:`dormhr`.

    .. _f08pk-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 zgees(jobvs, sort, a, select=None, data=None):
    r"""
    ``zgees`` computes the eigenvalues, the Schur form :math:`T`, and, optionally, the matrix of Schur vectors :math:`Z` for an :math:`n\times n` complex nonsymmetric matrix :math:`A`.

    .. _f08pn-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08pnf.html

    .. _f08pn-py2-py-parameters:

    **Parameters**
        **jobvs** : str, length 1
            If :math:`\mathrm{jobvs} = \texttt{'N'}`, Schur vectors are not computed.

            If :math:`\mathrm{jobvs} = \texttt{'V'}`, Schur vectors are computed.

        **sort** : str, length 1
            Specifies whether or not to order the eigenvalues on the diagonal of the Schur form.

            :math:`\mathrm{sort} = \texttt{'N'}`

                Eigenvalues are not ordered.

            :math:`\mathrm{sort} = \texttt{'S'}`

                Eigenvalues are ordered (see :math:`\mathrm{select}`).

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

        **select** : None or callable retval = select(w, data=None), optional
            Note: if this argument is **None** then a NAG-supplied facility will be used.

            If :math:`\mathrm{sort} = \texttt{'S'}`, :math:`\mathrm{select}` is used to select eigenvalues to sort to the top left of the Schur form.

            An eigenvalue :math:`\mathrm{w}[j-1]` is selected if :math:`\mathrm{select}\left(\mathrm{w}[j-1]\right)` is :math:`\mathbf{True}`.

            **Parameters**
                **w** : complex
                    The real and imaginary parts of the eigenvalue.

                **data** : arbitrary, optional, modifiable in place
                    User-communication data for callback functions.

            **Returns**
                **retval** : bool
                    Must be :math:`\mathbf{True}` if the eigenvalue is to be selected.

        **data** : arbitrary, optional
            User-communication data for callback functions.

    **Returns**
        **a** : complex, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{a}` is overwritten by its Schur form :math:`T`.

        **sdim** : int
            If :math:`\mathrm{sort} = \texttt{'N'}`, :math:`\mathrm{sdim} = 0`.

            If :math:`\mathrm{sort} = \texttt{'S'}`, :math:`\mathrm{sdim} = \text{}` number of eigenvalues for which :math:`\mathrm{select}` is :math:`\mathbf{True}`.

        **w** : complex, ndarray, shape :math:`\left(n\right)`
            Contains the computed eigenvalues, in the same order that they appear on the diagonal of the output Schur form :math:`T`.

        **vs** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobvs} = \texttt{'V'}`, :math:`\mathrm{vs}` contains the unitary matrix :math:`Z` of Schur vectors.

            If :math:`\mathrm{jobvs} = \texttt{'N'}`, :math:`\mathrm{vs}` is not referenced.

    .. _f08pn-py2-py-errors:

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

                Constraint: :math:`\mathrm{jobvs} = \texttt{'N'}` or :math:`\texttt{'V'}`.

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

                Constraint: :math:`\mathrm{sort} = \texttt{'N'}` or :math:`\texttt{'S'}`.

            (`errno` :math:`-4`)
                On entry, error in parameter :math:`\textit{n}`.

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

            (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq n\right)`)
                The :math:`QR` algorithm failed to compute all the eigenvalues.

    **Warns**
        **NagAlgorithmicWarning**
            (`errno` :math:`n+1`)
                The eigenvalues could not be reordered because some eigenvalues were too close to separate (the problem is very ill-conditioned).

            (`errno` :math:`n+2`)
                After reordering, roundoff changed values of some complex eigenvalues so that leading eigenvalues in the Schur form no longer satisfy :math:`\mathrm{select} = \mathbf{True}`. This could also be caused by underflow due to scaling.

    .. _f08pn-py2-py-notes:

    **Notes**
        The Schur factorization of :math:`A` is given by

        .. math::
            A = ZTZ^\mathrm{H}\text{,}

        where :math:`Z`, the matrix of Schur vectors, is unitary and :math:`T` is the Schur form.
        A complex matrix is in Schur form if it is upper triangular.

        Optionally, ``zgees`` also orders the eigenvalues on the diagonal of the Schur form so that selected eigenvalues are at the top left.
        The leading columns of :math:`Z` form an orthonormal basis for the invariant subspace corresponding to the selected eigenvalues.

    .. _f08pn-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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 zgeesx(jobvs, sort, sense, a, select=None, data=None):
    r"""
    ``zgeesx`` computes the eigenvalues, the Schur form :math:`T`, and, optionally, the matrix of Schur vectors :math:`Z` for an :math:`n\times n` complex nonsymmetric matrix :math:`A`.

    .. _f08pp-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08ppf.html

    .. _f08pp-py2-py-parameters:

    **Parameters**
        **jobvs** : str, length 1
            If :math:`\mathrm{jobvs} = \texttt{'N'}`, Schur vectors are not computed.

            If :math:`\mathrm{jobvs} = \texttt{'V'}`, Schur vectors are computed.

        **sort** : str, length 1
            Specifies whether or not to order the eigenvalues on the diagonal of the Schur form.

            :math:`\mathrm{sort} = \texttt{'N'}`

                Eigenvalues are not ordered.

            :math:`\mathrm{sort} = \texttt{'S'}`

                Eigenvalues are ordered (see :math:`\mathrm{select}`).

        **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 average of selected eigenvalues only.

            :math:`\mathrm{sense} = \texttt{'V'}`

                Computed for selected right invariant subspace only.

            :math:`\mathrm{sense} = \texttt{'B'}`

                Computed for both.

            If :math:`\mathrm{sense} = \texttt{'E'}`, :math:`\texttt{'V'}` or :math:`\texttt{'B'}`, :math:`\mathrm{sort} = \texttt{'S'}`.

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

        **select** : None or callable retval = select(w, data=None), optional
            Note: if this argument is **None** then a NAG-supplied facility will be used.

            If :math:`\mathrm{sort} = \texttt{'S'}`, :math:`\mathrm{select}` is used to select eigenvalues to sort to the top left of the Schur form.

            An eigenvalue :math:`\mathrm{w}[j-1]` is selected if :math:`\mathrm{select}\left(\mathrm{w}[j-1]\right)` is :math:`\mathbf{True}`.

            **Parameters**
                **w** : complex
                    The real and imaginary parts of the eigenvalue.

                **data** : arbitrary, optional, modifiable in place
                    User-communication data for callback functions.

            **Returns**
                **retval** : bool
                    Must be :math:`\mathbf{True}` if the eigenvalue is to be selected.

        **data** : arbitrary, optional
            User-communication data for callback functions.

    **Returns**
        **a** : complex, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{a}` is overwritten by its Schur form :math:`T`.

        **sdim** : int
            If :math:`\mathrm{sort} = \texttt{'N'}`, :math:`\mathrm{sdim} = 0`.

            If :math:`\mathrm{sort} = \texttt{'S'}`, :math:`\mathrm{sdim} = \text{}` number of eigenvalues for which :math:`\mathrm{select}` is :math:`\mathbf{True}`.

        **w** : complex, ndarray, shape :math:`\left(n\right)`
            Contains the computed eigenvalues, in the same order that they appear on the diagonal of the output Schur form :math:`T`.

        **vs** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobvs} = \texttt{'V'}`, :math:`\mathrm{vs}` contains the unitary matrix :math:`Z` of Schur vectors.

            If :math:`\mathrm{jobvs} = \texttt{'N'}`, :math:`\mathrm{vs}` is not referenced.

        **rconde** : float
            If :math:`\mathrm{sense} = \texttt{'E'}` or :math:`\texttt{'B'}`, contains the reciprocal condition number for the average of the selected eigenvalues.

            If :math:`\mathrm{sense} = \texttt{'N'}` or :math:`\texttt{'V'}`, :math:`\mathrm{rconde}` is not referenced.

        **rcondv** : float
            If :math:`\mathrm{sense} = \texttt{'V'}` or :math:`\texttt{'B'}`, :math:`\mathrm{rcondv}` contains the reciprocal condition number for the selected right invariant subspace.

            If :math:`\mathrm{sense} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{rcondv}` is not referenced.

    .. _f08pp-py2-py-errors:

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

                Constraint: :math:`\mathrm{jobvs} = \texttt{'N'}` or :math:`\texttt{'V'}`.

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

                Constraint: :math:`\mathrm{sort} = \texttt{'N'}` or :math:`\texttt{'S'}`.

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

            (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq n\right)`)
                The :math:`QR` algorithm failed to compute all the eigenvalues.

    **Warns**
        **NagAlgorithmicWarning**
            (`errno` :math:`n+1`)
                The eigenvalues could not be reordered because some eigenvalues were too close to separate (the problem is very ill-conditioned).

            (`errno` :math:`n+2`)
                After reordering, roundoff changed values of some complex eigenvalues so that leading eigenvalues in the Schur form no longer satisfy :math:`\mathrm{select} = \mathbf{True}`. This could also be caused by underflow due to scaling.

    .. _f08pp-py2-py-notes:

    **Notes**
        The Schur factorization of :math:`A` is given by

        .. math::
            A = ZTZ^\mathrm{H}\text{,}

        where :math:`Z`, the matrix of Schur vectors, is unitary and :math:`T` is the Schur form.
        A complex matrix is in Schur form if it is upper triangular.

        Optionally, ``zgeesx`` also orders the eigenvalues on the diagonal of the Schur form so that selected eigenvalues are at the top left; computes a reciprocal condition number for the average of the selected eigenvalues (:math:`\mathrm{rconde}`); and computes a reciprocal condition number for the right invariant subspace corresponding to the selected eigenvalues (:math:`\mathrm{rcondv}`).
        The leading columns of :math:`Z` form an orthonormal basis for this invariant subspace.

        For further explanation of the reciprocal condition numbers :math:`\mathrm{rconde}` and :math:`\mathrm{rcondv}`, see Section 4.8 of Anderson `et al.` (1999) (where these quantities are called :math:`s` and :math:`\textit{sep}` respectively).

    .. _f08pp-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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 zhseqr(job, compz, ilo, ihi, h, z=None):
    r"""
    ``zhseqr`` computes all the eigenvalues and, optionally, the Schur factorization of a complex Hessenberg matrix or a complex general matrix which has been reduced to Hessenberg form.

    .. _f08ps-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08psf.html

    .. _f08ps-py2-py-parameters:

    **Parameters**
        **job** : str, length 1
            Indicates whether eigenvalues only or the Schur form :math:`T` is required.

            :math:`\mathrm{job} = \texttt{'E'}`

                Eigenvalues only are required.

            :math:`\mathrm{job} = \texttt{'S'}`

                The Schur form :math:`T` is required.

        **compz** : str, length 1
            Indicates whether the Schur vectors are to be computed.

            :math:`\mathrm{compz} = \texttt{'N'}`

                No Schur vectors are computed (and the array :math:`\mathrm{z}` is not referenced).

            :math:`\mathrm{compz} = \texttt{'V'}`

                The Schur vectors 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 Schur vectors of :math:`H` are computed (and the array :math:`\mathrm{z}` is initialized by the function).

        **ilo** : int
            If the matrix :math:`A` has been balanced by :meth:`zgebal`, :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 the matrix :math:`A` has been balanced by :meth:`zgebal`, :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}`.

        **h** : complex, array-like, shape :math:`\left(n, n\right)`
            The :math:`n\times n` upper Hessenberg matrix :math:`H`, as returned by :meth:`zgehrd`.

        **z** : 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{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 Hessenberg form.

            If :math:`\mathrm{compz} = \texttt{'I'}`, :math:`\mathrm{z}` need not be set.

    **Returns**
        **h** : complex, ndarray, shape :math:`\left(n, n\right)`
            If :math:`\mathrm{job} = \texttt{'E'}`, the array contains no useful information.

            If :math:`\mathrm{job} = \texttt{'S'}`, :math:`\mathrm{h}` is overwritten by the upper triangular matrix :math:`T` from the Schur decomposition (the Schur form) unless :math:`\mathrm{errno}` > 0.

        **w** : complex, ndarray, shape :math:`\left(n\right)`
            The computed eigenvalues, unless :math:`\mathrm{errno}` > 0 (in which case see :ref:`Exceptions <f08ps-py2-py-errors>`). The eigenvalues are stored in the same order as on the diagonal of the Schur form :math:`T` (if computed).

        **z** : None or complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{compz} = \texttt{'V'}` or :math:`\texttt{'I'}`, :math:`\mathrm{z}` contains the unitary matrix of the required Schur vectors, unless :math:`\mathrm{errno}` > 0.

            If :math:`\mathrm{compz} = \texttt{'N'}`, :math:`\mathrm{z}` is not referenced.

    .. _f08ps-py2-py-errors:

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

                Constraint: :math:`\mathrm{job} = \texttt{'E'}` or :math:`\texttt{'S'}`.

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

                Constraint: :math:`\mathrm{compz} = \texttt{'N'}`, :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:`-4`)
                On entry, error in parameter :math:`\mathrm{ilo}`.

            (`errno` :math:`-5`)
                On entry, error in parameter :math:`\mathrm{ihi}`.

            (`errno` :math:`i > 0`)
                The algorithm has failed to find all the eigenvalues after a total of :math:`30\left(\mathrm{ihi}-\mathrm{ilo}+1\right)` iterations.

    .. _f08ps-py2-py-notes:

    **Notes**
        ``zhseqr`` computes all the eigenvalues and, optionally, the Schur factorization of a complex upper Hessenberg matrix :math:`H`:

        .. math::
            H = ZTZ^\mathrm{H}\text{,}

        where :math:`T` is an upper triangular matrix (the Schur form of :math:`H`), and :math:`Z` is the unitary matrix whose columns are the Schur vectors :math:`z_i`.
        The diagonal elements of :math:`T` are the eigenvalues of :math:`H`.

        The function may also be used to compute the Schur factorization of a complex general matrix :math:`A` which has been reduced to upper Hessenberg form :math:`H`:

        .. math::
            \begin{array}{lll}A& = &QHQ^\mathrm{H}\text{, where }Q\text{ is unitary,}\\& = &\left(QZ\right)T\left(QZ\right)^\mathrm{H}\text{.}\end{array}

        In this case, after :meth:`zgehrd` has been called to reduce :math:`A` to Hessenberg form, :meth:`zunghr` must be called to form :math:`Q` explicitly; :math:`Q` is then passed to ``zhseqr``, which must be called with :math:`\mathrm{compz} = \texttt{'V'}`.

        The function can also take advantage of a previous call to :meth:`zgebal` which may have balanced the original matrix before reducing it to Hessenberg form, so that the Hessenberg matrix :math:`H` has the structure:

        .. math::
            \begin{pmatrix}H_{11}&H_{12}&H_{13}\\&H_{22}&H_{23}\\&&H_{33}\end{pmatrix}

        where :math:`H_{11}` and :math:`H_{33}` are upper triangular.
        If so, only the central diagonal block :math:`H_{22}` (in rows and columns :math:`i_{\mathrm{lo}}` to :math:`i_{\mathrm{hi}}`) needs to be further reduced to Schur form (the blocks :math:`H_{12}` and :math:`H_{23}` are also affected).
        Therefore, the values of :math:`i_{\mathrm{lo}}` and :math:`i_{\mathrm{hi}}` can be supplied to ``zhseqr`` directly.
        Also, :meth:`zgebak` must be called after this function to permute the Schur vectors of the balanced matrix to those of the original matrix.
        If :meth:`zgebal` has not been called however, then :math:`i_{\mathrm{lo}}` must be set to :math:`1` and :math:`i_{\mathrm{hi}}` to :math:`n`.
        Note that if the Schur factorization of :math:`A` is required, :meth:`zgebal` must **not** be called with :math:`{\textit{job}} = \texttt{'S'}` or :math:`\texttt{'B'}`, because the balancing transformation is not unitary.

        ``zhseqr`` uses a multishift form of the upper Hessenberg :math:`QR` algorithm, due to Bai and Demmel (1989).
        The Schur vectors 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`.

    .. _f08ps-py2-py-references:

    **References**
        Bai, Z and Demmel, J W, 1989, `On a block implementation of Hessenberg multishift` :math:`{QR}` `iteration`, Internat. J. High Speed Comput. (1), 97--112

        Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore
    """
    raise NotImplementedError

def zhsein(job, eigsrc, initv, select, h, w, vl=None, vr=None):
    r"""
    ``zhsein`` computes selected left and/or right eigenvectors of a complex upper Hessenberg matrix corresponding to specified eigenvalues, by inverse iteration.

    .. _f08px-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08pxf.html

    .. _f08px-py2-py-parameters:

    **Parameters**
        **job** : str, length 1
            Indicates whether left and/or right eigenvectors are to be computed.

            :math:`\mathrm{job} = \texttt{'R'}`

                Only right eigenvectors are computed.

            :math:`\mathrm{job} = \texttt{'L'}`

                Only left eigenvectors are computed.

            :math:`\mathrm{job} = \texttt{'B'}`

                Both left and right eigenvectors are computed.

        **eigsrc** : str, length 1
            Indicates whether the eigenvalues of :math:`H` (stored in :math:`\mathrm{w}`) were found using :meth:`zhseqr`.

            :math:`\mathrm{eigsrc} = \texttt{'Q'}`

                The eigenvalues of :math:`H` were found using :meth:`zhseqr`; thus if :math:`H` has any zero subdiagonal elements (and so is block triangular), then the :math:`j`\ th eigenvalue can be assumed to be an eigenvalue of the block containing the :math:`j`\ th row/column. This property allows the function to perform inverse iteration on just one diagonal block.

            :math:`\mathrm{eigsrc} = \texttt{'N'}`

                No such assumption is made and the function performs inverse iteration using the whole matrix.

        **initv** : str, length 1
            Indicates whether you are supplying initial estimates for the selected eigenvectors.

            :math:`\mathrm{initv} = \texttt{'N'}`

                No initial estimates are supplied.

            :math:`\mathrm{initv} = \texttt{'U'}`

                Initial estimates are supplied in :math:`\mathrm{vl}` and/or :math:`\mathrm{vr}`.

        **select** : bool, array-like, shape :math:`\left(n\right)`
            Specifies which eigenvectors are to be computed. To select the eigenvector corresponding to the eigenvalue :math:`\mathrm{w}[j-1]`, :math:`\mathrm{select}[j-1]` must be set to :math:`\mathbf{True}`.

        **h** : complex, array-like, shape :math:`\left(n, n\right)`
            The :math:`n\times n` upper Hessenberg matrix :math:`H`. If a NaN is detected in :math:`\mathrm{h}`, the function will return with :math:`\mathrm{errno}` = -6.

        **w** : complex, array-like, shape :math:`\left(n\right)`
            The eigenvalues of the matrix :math:`H`. If :math:`\mathrm{eigsrc} = \texttt{'Q'}`, the array **must** be exactly as returned by :meth:`zhseqr`.

        **vl** : 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{job}\text{ in } (\texttt{'L'}, \texttt{'B'})`: :math:`n`; if :math:`\mathrm{job}=\texttt{'R'}`: :math:`1`; otherwise: :math:`0`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{job}\text{ in } (\texttt{'L'}, \texttt{'B'})`: :math:`\textit{mm}`; if :math:`\mathrm{job}=\texttt{'R'}`: :math:`1`; otherwise: :math:`0`.

            If :math:`\mathrm{initv} = \texttt{'U'}` and :math:`\mathrm{job} = \texttt{'L'}` or :math:`\texttt{'B'}`, :math:`\mathrm{vl}` must contain starting vectors for inverse iteration for the left eigenvectors. Each starting vector must be stored in the same column as will be used to store the corresponding eigenvector.

            If :math:`\mathrm{initv} = \texttt{'N'}`, :math:`\mathrm{vl}` need not be set.

        **vr** : 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{job}\text{ in } (\texttt{'R'}, \texttt{'B'})`: :math:`n`; if :math:`\mathrm{job}=\texttt{'L'}`: :math:`1`; otherwise: :math:`0`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{job}\text{ in } (\texttt{'R'}, \texttt{'B'})`: :math:`\textit{mm}`; if :math:`\mathrm{job}=\texttt{'L'}`: :math:`1`; otherwise: :math:`0`.

            If :math:`\mathrm{initv} = \texttt{'U'}` and :math:`\mathrm{job} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{vr}` must contain starting vectors for inverse iteration for the right eigenvectors. Each starting vector must be stored in the same column as will be used to store the corresponding eigenvector.

            If :math:`\mathrm{initv} = \texttt{'N'}`, :math:`\mathrm{vr}` need not be set.

    **Returns**
        **w** : complex, ndarray, shape :math:`\left(n\right)`
            The real parts of some elements of :math:`\mathrm{w}` may be modified, as close eigenvalues are perturbed slightly in searching for independent eigenvectors.

        **vl** : None or complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{job} = \texttt{'L'}` or :math:`\texttt{'B'}`, :math:`\mathrm{vl}` contains the computed left eigenvectors (as specified by :math:`\mathrm{select}`). The eigenvectors are stored consecutively in the columns of the array, in the same order as their eigenvalues.

            If :math:`\mathrm{job} = \texttt{'R'}`, :math:`\mathrm{vl}` is not referenced.

        **vr** : None or complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{job} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{vr}` contains the computed right eigenvectors (as specified by :math:`\mathrm{select}`). The eigenvectors are stored consecutively in the columns of the array, in the same order as their eigenvalues.

            If :math:`\mathrm{job} = \texttt{'L'}`, :math:`\mathrm{vr}` is not referenced.

        **m** : int
            :math:`\textit{m}`, the number of selected eigenvectors.

        **ifaill** : int, ndarray, shape :math:`\left(:\right)`
            If :math:`\mathrm{job} = \texttt{'L'}` or :math:`\texttt{'B'}`, then :math:`\mathrm{ifaill}[i-1] = 0` if the selected left eigenvector converged and :math:`\mathrm{ifaill}[i-1] = j > 0` if the eigenvector stored in the :math:`i`\ th row or column of :math:`\mathrm{vl}` (corresponding to the :math:`j`\ th eigenvalue) failed to converge.

            If :math:`\mathrm{job} = \texttt{'R'}`, :math:`\mathrm{ifaill}` is not referenced.

        **ifailr** : int, ndarray, shape :math:`\left(:\right)`
            If :math:`\mathrm{job} = \texttt{'R'}` or :math:`\texttt{'B'}`, then :math:`\mathrm{ifailr}[i-1] = 0` if the selected right eigenvector converged and :math:`\mathrm{ifailr}[i-1] = j > 0` if the eigenvector stored in the :math:`i`\ th column of :math:`\mathrm{vr}` (corresponding to the :math:`j`\ th eigenvalue) failed to converge.

            If :math:`\mathrm{job} = \texttt{'L'}`, :math:`\mathrm{ifailr}` is not referenced.

    .. _f08px-py2-py-errors:

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

                Constraint: :math:`\mathrm{job} = \texttt{'R'}`, :math:`\texttt{'L'}` or :math:`\texttt{'B'}`.

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

                Constraint: :math:`\mathrm{eigsrc} = \texttt{'Q'}` or :math:`\texttt{'N'}`.

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

                Constraint: :math:`\mathrm{initv} = \texttt{'N'}` or :math:`\texttt{'U'}`.

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

                Constraint: No element of :math:`\mathrm{h}` is equal to NaN.

            (`errno` :math:`-13`)
                On entry, error in parameter :math:`\textit{mm}`.

                Constraint: :math:`\textit{mm}\geq \textit{m}`.

            (`errno` :math:`i > 0`)
                :math:`\langle\mathit{\boldsymbol{value}}\rangle` eigenvectors (as indicated by arguments :math:`\mathrm{ifaill}` and/or :math:`\mathrm{ifailr}`) failed to converge. The corresponding columns of :math:`\mathrm{vl}` and/or :math:`\mathrm{vr}` contain no useful information.

    .. _f08px-py2-py-notes:

    **Notes**
        ``zhsein`` computes left and/or right eigenvectors of a complex upper Hessenberg matrix :math:`H`, corresponding to selected eigenvalues.

        The right eigenvector :math:`x`, and the left eigenvector :math:`y`, corresponding to an eigenvalue :math:`\lambda`, are defined by:

        .. math::
            Hx = \lambda x\quad \text{ and }\quad y^\mathrm{H}H = \lambda y^\mathrm{H}\left(\quad \text{ or }H^\mathrm{H}y = \bar{\lambda }y\right)\text{.}

        The eigenvectors are computed by inverse iteration.
        They are scaled so that :math:`\mathrm{max}\left({\left\lvert \mathrm{Re}\left(x_i\right)\right\rvert +\left\lvert \mathrm{Im}\left(x_i\right)\right\rvert }\right) = 1`.

        If :math:`H` has been formed by reduction of a complex general matrix :math:`A` to upper Hessenberg form, then the eigenvectors of :math:`H` may be transformed to eigenvectors of :math:`A` by a call to :meth:`zunmhr`.

    .. _f08px-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 dtrexc(compq, t, q, ifst, ilst):
    r"""
    ``dtrexc`` reorders the Schur factorization of a real general matrix.

    .. _f08qf-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08qff.html

    .. _f08qf-py2-py-parameters:

    **Parameters**
        **compq** : str, length 1
            Indicates whether the matrix :math:`Q` of Schur vectors is to be updated.

            :math:`\mathrm{compq} = \texttt{'V'}`

                The matrix :math:`Q` of Schur vectors is updated.

            :math:`\mathrm{compq} = \texttt{'N'}`

                No Schur vectors are updated.

        **t** : float, array-like, shape :math:`\left(n, n\right)`
            The :math:`n\times n` upper quasi-triangular matrix :math:`T` in canonical Schur form, as returned by :meth:`dhseqr`.

        **q** : float, array-like, shape :math:`\left(:, :\right)`
            Note: the required extent for this argument in dimension 1 is determined as follows: if :math:`\mathrm{compq}=\texttt{'V'}`: :math:`n`; if :math:`\mathrm{compq}=\texttt{'N'}`: :math:`1`; otherwise: :math:`0`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{compq}=\texttt{'V'}`: :math:`n`; if :math:`\mathrm{compq}=\texttt{'N'}`: :math:`1`; otherwise: :math:`0`.

            If :math:`\mathrm{compq} = \texttt{'V'}`, :math:`\mathrm{q}` must contain the :math:`n\times n` orthogonal matrix :math:`Q` of Schur vectors.

        **ifst** : int
            :math:`\mathrm{ifst}` and :math:`\mathrm{ilst}` must specify the reordering of the diagonal elements or blocks of :math:`T`. The element or block with row index :math:`\mathrm{ifst}` is moved to row :math:`\mathrm{ilst}` by a sequence of exchanges between adjacent elements or blocks.

        **ilst** : int
            :math:`\mathrm{ifst}` and :math:`\mathrm{ilst}` must specify the reordering of the diagonal elements or blocks of :math:`T`. The element or block with row index :math:`\mathrm{ifst}` is moved to row :math:`\mathrm{ilst}` by a sequence of exchanges between adjacent elements or blocks.

    **Returns**
        **t** : float, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{t}` is overwritten by the updated matrix :math:`\tilde{T}`. See also `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08qff.html#fcomments>`__.

        **q** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{compq} = \texttt{'V'}`, :math:`\mathrm{q}` contains the updated matrix of Schur vectors.

            If :math:`\mathrm{compq} = \texttt{'N'}`, :math:`\mathrm{q}` is not referenced.

        **ifst** : int
            If :math:`\mathrm{ifst}` pointed to the second row of a :math:`2\times 2` block on entry, it is changed to point to the first row. :math:`\mathrm{ilst}` always points to the first row of the block in its final position (which may differ from its input value by :math:`{\pm 1}`).

        **ilst** : int
            If :math:`\mathrm{ifst}` pointed to the second row of a :math:`2\times 2` block on entry, it is changed to point to the first row. :math:`\mathrm{ilst}` always points to the first row of the block in its final position (which may differ from its input value by :math:`{\pm 1}`).

    .. _f08qf-py2-py-errors:

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

                Constraint: :math:`\mathrm{compq} = \texttt{'V'}` or :math:`\texttt{'N'}`.

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

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

            (`errno` :math:`-7`)
                On entry, error in parameter :math:`\mathrm{ifst}`.

            (`errno` :math:`-8`)
                On entry, error in parameter :math:`\mathrm{ilst}`.

    **Warns**
        **NagAlgorithmicWarning**
            (`errno` :math:`1`)
                Two adjacent diagonal elements or blocks could not be successfully exchanged. This error can only occur if the exchange involves at least one :math:`2\times 2` block; it implies that the problem is very ill-conditioned, and that the eigenvalues of the two blocks are very close. On exit, :math:`T` may have been partially reordered, and :math:`\mathrm{ilst}` points to the first row of the current position of the block being moved; :math:`Q` (if requested) is updated consistently with :math:`T`.

    .. _f08qf-py2-py-notes:

    **Notes**
        ``dtrexc`` reorders the Schur factorization of a real general matrix :math:`A = QTQ^\mathrm{T}`, so that the diagonal element or block of :math:`T` with row index :math:`\mathrm{ifst}` is moved to row :math:`\mathrm{ilst}`.

        The reordered Schur form :math:`\tilde{T}` is computed by an orthogonal similarity transformation: :math:`\tilde{T} = Z^\mathrm{T}TZ`.
        Optionally the updated matrix :math:`\tilde{Q}` of Schur vectors is computed as :math:`\tilde{Q} = QZ`, giving :math:`A = \tilde{Q}\tilde{T}\tilde{Q}^\mathrm{T}`.

    .. _f08qf-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 dtrsen(job, compq, select, t, q):
    r"""
    ``dtrsen`` reorders the Schur factorization of a real general matrix so that a selected cluster of eigenvalues appears in the leading elements or blocks on the diagonal of the Schur form.
    The function also optionally computes the reciprocal condition numbers of the cluster of eigenvalues and/or the invariant subspace.

    .. _f08qg-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08qgf.html

    .. _f08qg-py2-py-parameters:

    **Parameters**
        **job** : str, length 1
            Indicates whether condition numbers are required for the cluster of eigenvalues and/or the invariant subspace.

            :math:`\mathrm{job} = \texttt{'N'}`

                No condition numbers are required.

            :math:`\mathrm{job} = \texttt{'E'}`

                Only the condition number for the cluster of eigenvalues is computed.

            :math:`\mathrm{job} = \texttt{'V'}`

                Only the condition number for the invariant subspace is computed.

            :math:`\mathrm{job} = \texttt{'B'}`

                Condition numbers for both the cluster of eigenvalues and the invariant subspace are computed.

        **compq** : str, length 1
            Indicates whether the matrix :math:`Q` of Schur vectors is to be updated.

            :math:`\mathrm{compq} = \texttt{'V'}`

                The matrix :math:`Q` of Schur vectors is updated.

            :math:`\mathrm{compq} = \texttt{'N'}`

                No Schur vectors are updated.

        **select** : bool, array-like, shape :math:`\left(n\right)`
            The eigenvalues in the selected cluster. To select a real eigenvalue :math:`\lambda_j`, :math:`\mathrm{select}[j-1]` must be set :math:`\mathbf{True}`. To select a complex conjugate pair of eigenvalues :math:`\lambda_j` and :math:`\lambda_{{j+1}}` (corresponding to a :math:`2\times 2` diagonal block), :math:`\mathrm{select}[j-1]` and/or :math:`\mathrm{select}[j]` must be set to :math:`\mathbf{True}`. A complex conjugate pair of eigenvalues **must** be either both included in the cluster or both excluded. See also `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08qgf.html#fcomments>`__.

        **t** : float, array-like, shape :math:`\left(n, n\right)`
            The :math:`n\times n` upper quasi-triangular matrix :math:`T` in canonical Schur form, as returned by :meth:`dhseqr`. See also `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08qgf.html#fcomments>`__.

        **q** : float, array-like, shape :math:`\left(:, :\right)`
            Note: the required extent for this argument in dimension 1 is determined as follows: if :math:`\mathrm{compq}=\texttt{'V'}`: :math:`n`; if :math:`\mathrm{compq}=\texttt{'N'}`: :math:`1`; otherwise: :math:`0`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{compq}=\texttt{'V'}`: :math:`n`; if :math:`\mathrm{compq}=\texttt{'N'}`: :math:`1`; otherwise: :math:`0`.

            If :math:`\mathrm{compq} = \texttt{'V'}`, :math:`\mathrm{q}` must contain the :math:`n\times n` orthogonal matrix :math:`Q` of Schur vectors, as returned by :meth:`dhseqr`.

    **Returns**
        **t** : float, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{t}` is overwritten by the updated matrix :math:`\tilde{T}`.

        **q** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{compq} = \texttt{'V'}`, :math:`\mathrm{q}` contains the updated matrix of Schur vectors; the first :math:`m` columns of :math:`Q` form an orthonormal basis for the specified invariant subspace.

            If :math:`\mathrm{compq} = \texttt{'N'}`, :math:`\mathrm{q}` is not referenced.

        **wr** : float, ndarray, shape :math:`\left(n\right)`
            The real and imaginary parts, respectively, of the reordered eigenvalues of :math:`\tilde{T}`. The eigenvalues are stored in the same order as on the diagonal of :math:`\tilde{T}`; see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08qgf.html#fcomments>`__ for details. Note that if a complex eigenvalue is sufficiently ill-conditioned, then its value may differ significantly from its value before reordering.

        **wi** : float, ndarray, shape :math:`\left(n\right)`
            The real and imaginary parts, respectively, of the reordered eigenvalues of :math:`\tilde{T}`. The eigenvalues are stored in the same order as on the diagonal of :math:`\tilde{T}`; see `Further Comments <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08qgf.html#fcomments>`__ for details. Note that if a complex eigenvalue is sufficiently ill-conditioned, then its value may differ significantly from its value before reordering.

        **m** : int
            :math:`m`, the dimension of the specified invariant subspace. The value of :math:`m` is obtained by counting :math:`1` for each selected real eigenvalue and :math:`2` for each selected complex conjugate pair of eigenvalues (see :math:`\mathrm{select}`); :math:`0\leq m\leq n`.

        **s** : float
            If :math:`\mathrm{job} = \texttt{'E'}` or :math:`\texttt{'B'}`, :math:`\mathrm{s}` is a lower bound on the reciprocal condition number of the average of the selected cluster of eigenvalues. If :math:`\mathrm{m} = 0` or :math:`n`, :math:`\mathrm{s} = 1`; if :math:`\mathrm{errno}` = 1 (see :ref:`Exceptions <f08qg-py2-py-errors>`), :math:`\mathrm{s}` is set to zero.

            If :math:`\mathrm{job} = \texttt{'N'}` or :math:`\texttt{'V'}`, :math:`\mathrm{s}` is not referenced.

        **sep** : float
            If :math:`\mathrm{job} = \texttt{'V'}` or :math:`\texttt{'B'}`, :math:`\mathrm{sep}` is the estimated reciprocal condition number of the specified invariant subspace. If :math:`\mathrm{m} = 0` or :math:`n`, :math:`\mathrm{sep} = \left\lVert T\right\rVert`; if :math:`\mathrm{errno}` = 1 (see :ref:`Exceptions <f08qg-py2-py-errors>`), :math:`\mathrm{sep}` is set to zero.

            If :math:`\mathrm{job} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{sep}` is not referenced.

    .. _f08qg-py2-py-errors:

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

                Constraint: :math:`\mathrm{job} = \texttt{'N'}`, :math:`\texttt{'E'}`, :math:`\texttt{'V'}` or :math:`\texttt{'B'}`.

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

                Constraint: :math:`\mathrm{compq} = \texttt{'V'}` or :math:`\texttt{'N'}`.

            (`errno` :math:`-4`)
                On entry, error in parameter :math:`\textit{n}`.

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

    **Warns**
        **NagAlgorithmicWarning**
            (`errno` :math:`1`)
                The reordering of :math:`T` failed because a selected eigenvalue was too close to an unselected eigenvalue.

    .. _f08qg-py2-py-notes:

    **Notes**
        ``dtrsen`` reorders the Schur factorization of a real general matrix :math:`A = QTQ^\mathrm{T}`, so that a selected cluster of eigenvalues appears in the leading diagonal elements or blocks of the Schur form.

        The reordered Schur form :math:`\tilde{T}` is computed by an orthogonal similarity transformation: :math:`\tilde{T} = Z^\mathrm{T}TZ`.
        Optionally the updated matrix :math:`\tilde{Q}` of Schur vectors is computed as :math:`\tilde{Q} = QZ`, giving :math:`A = \tilde{Q}\tilde{T}\tilde{Q}^\mathrm{T}`.

        Let :math:`\tilde{T} = \begin{pmatrix}T_{11}&T_{12}\\0&T_{22}\end{pmatrix}`, where the selected eigenvalues are precisely the eigenvalues of the leading :math:`m\times m` sub-matrix :math:`T_{11}`.
        Let :math:`\tilde{Q}` be correspondingly partitioned as :math:`\begin{pmatrix}Q_1&Q_2\end{pmatrix}` where :math:`Q_1` consists of the first :math:`m` columns of :math:`Q`.
        Then :math:`AQ_1 = Q_1T_{11}`, and so the :math:`m` columns of :math:`Q_1` form an orthonormal basis for the invariant subspace corresponding to the selected cluster of eigenvalues.

        Optionally the function also computes estimates of the reciprocal condition numbers of the average of the cluster of eigenvalues and of the invariant subspace.

    .. _f08qg-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 dtrsyl(trana, tranb, isgn, a, b, c):
    r"""
    ``dtrsyl`` solves the real quasi-triangular Sylvester matrix equation.

    .. _f08qh-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08qhf.html

    .. _f08qh-py2-py-parameters:

    **Parameters**
        **trana** : str, length 1
            Specifies the option :math:`\mathrm{op}\left(A\right)`.

            :math:`\mathrm{trana} = \texttt{'N'}`

                :math:`\mathrm{op}\left(A\right) = A`.

            :math:`\mathrm{trana} = \texttt{'T'}` or :math:`\texttt{'C'}`

                :math:`\mathrm{op}\left(A\right) = A^\mathrm{T}`.

        **tranb** : str, length 1
            Specifies the option :math:`\mathrm{op}\left(B\right)`.

            :math:`\mathrm{tranb} = \texttt{'N'}`

                :math:`\mathrm{op}\left(B\right) = B`.

            :math:`\mathrm{tranb} = \texttt{'T'}` or :math:`\texttt{'C'}`

                :math:`\mathrm{op}\left(B\right) = B^\mathrm{T}`.

        **isgn** : int
            Indicates the form of the Sylvester equation.

            :math:`\mathrm{isgn} = +1`

                The equation is of the form :math:`\mathrm{op}\left(A\right)X+X\mathrm{op}\left(B\right) = \alpha C`.

            :math:`\mathrm{isgn} = -1`

                The equation is of the form :math:`\mathrm{op}\left(A\right)X-X\mathrm{op}\left(B\right) = \alpha C`.

        **a** : float, array-like, shape :math:`\left(m, m\right)`
            The :math:`m\times m` upper quasi-triangular matrix :math:`A` in canonical Schur form, as returned by :meth:`dhseqr`.

        **b** : float, array-like, shape :math:`\left(n, n\right)`
            The :math:`n\times n` upper quasi-triangular matrix :math:`B` in canonical Schur form, as returned by :meth:`dhseqr`.

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

    **Returns**
        **c** : float, ndarray, shape :math:`\left(m, n\right)`
            :math:`\mathrm{c}` is overwritten by the solution matrix :math:`X`.

        **scale** : float
            The value of the scale factor :math:`\alpha`.

    .. _f08qh-py2-py-errors:

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

                Constraint: :math:`\mathrm{trana} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`.

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

                Constraint: :math:`\mathrm{tranb} = \texttt{'N'}`, :math:`\texttt{'T'}` or :math:`\texttt{'C'}`.

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

                Constraint: :math:`\mathrm{isgn} = +1` or :math:`-1`.

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

    **Warns**
        **NagAlgorithmicWarning**
            (`errno` :math:`1`)
                :math:`A` and :math:`B` have common or close eigenvalues, perturbed values of which were used to solve the equation.

    .. _f08qh-py2-py-notes:

    **Notes**
        ``dtrsyl`` solves the real Sylvester matrix equation

        .. math::
            \mathrm{op}\left(A\right)X\pm X\mathrm{op}\left(B\right) = \alpha C\text{,}

        where :math:`\mathrm{op}\left(A\right) = A` or :math:`A^\mathrm{T}`, and the matrices :math:`A` and :math:`B` are upper quasi-triangular matrices in canonical Schur form (as returned by :meth:`dhseqr`); :math:`\alpha` is a scale factor (:math:`\text{}\leq 1`) determined by the function to avoid overflow in :math:`X`; :math:`A` is :math:`m\times m` and :math:`B` is :math:`n\times n` while the right-hand side matrix :math:`C` and the solution matrix :math:`X` are both :math:`m\times n`.
        The matrix :math:`X` is obtained by a straightforward process of back-substitution (see Golub and Van Loan (1996)).

        Note that the equation has a unique solution if and only if :math:`\alpha_i\pm \beta_j\neq 0`, where :math:`\left\{\alpha_i\right\}` and :math:`\left\{\beta_j\right\}` are the eigenvalues of :math:`A` and :math:`B` respectively and the sign (:math:`+` or :math:`-`) is the same as that used in the equation to be solved.

    .. _f08qh-py2-py-references:

    **References**
        Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore

        Higham, N J, 1992, `Perturbation theory and backward error for` :math:`{AX}-{XB} = C`, Numerical Analysis Report, University of Manchester
    """
    raise NotImplementedError

def dtrevc(job, howmny, t, select=None, vl=None, vr=None):
    r"""
    ``dtrevc`` computes selected left and/or right eigenvectors of a real upper quasi-triangular matrix.

    .. _f08qk-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08qkf.html

    .. _f08qk-py2-py-parameters:

    **Parameters**
        **job** : str, length 1
            Indicates whether left and/or right eigenvectors are to be computed.

            :math:`\mathrm{job} = \texttt{'R'}`

                Only right eigenvectors are computed.

            :math:`\mathrm{job} = \texttt{'L'}`

                Only left eigenvectors are computed.

            :math:`\mathrm{job} = \texttt{'B'}`

                Both left and right eigenvectors are computed.

        **howmny** : str, length 1
            Indicates how many eigenvectors are to be computed.

            :math:`\mathrm{howmny} = \texttt{'A'}`

                All eigenvectors (as specified by :math:`\mathrm{job}`) are computed.

            :math:`\mathrm{howmny} = \texttt{'B'}`

                All eigenvectors (as specified by :math:`\mathrm{job}`) are computed and then pre-multiplied by the matrix :math:`Q` (which is overwritten).

            :math:`\mathrm{howmny} = \texttt{'S'}`

                Selected eigenvectors (as specified by :math:`\mathrm{job}` and :math:`\mathrm{select}`) are computed.

        **t** : float, array-like, shape :math:`\left(n, n\right)`
            The :math:`n\times n` upper quasi-triangular matrix :math:`T` in canonical Schur form, as returned by :meth:`dhseqr`.

        **select** : None or bool, array-like, shape :math:`\left(:\right)`, optional
            Note: the required length for this argument is determined as follows: if :math:`\mathrm{howmny}=\texttt{'S'}`: :math:`n`; otherwise: :math:`1`.

            Specifies which eigenvectors are to be computed if :math:`\mathrm{howmny} = \texttt{'S'}`. To obtain the real eigenvector corresponding to the real eigenvalue :math:`\lambda_j`, :math:`\mathrm{select}[j-1]` must be set :math:`\mathbf{True}`. To select the complex eigenvector corresponding to a complex conjugate pair of eigenvalues :math:`\lambda_j` and :math:`\lambda_{{j+1}}`, :math:`\mathrm{select}[j-1]` and/or :math:`\mathrm{select}[j]` must be set :math:`\mathbf{True}`; the eigenvector corresponding to the **first** eigenvalue in the pair is computed.

        **vl** : 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{job}\text{ in } (\texttt{'L'}, \texttt{'B'})`: :math:`n`; if :math:`\mathrm{job}=\texttt{'R'}`: :math:`1`; otherwise: :math:`0`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{job}\text{ in } (\texttt{'L'}, \texttt{'B'})`: :math:`\textit{mm}`; otherwise: :math:`0`.

            If :math:`\mathrm{howmny} = \texttt{'B'}` and :math:`\mathrm{job} = \texttt{'L'}` or :math:`\texttt{'B'}`, :math:`\mathrm{vl}` must contain an :math:`n\times n` matrix :math:`Q` (usually the matrix of Schur vectors returned by :meth:`dhseqr`).

            If :math:`\mathrm{howmny} = \texttt{'A'}` or :math:`\texttt{'S'}`, :math:`\mathrm{vl}` need not be set.

        **vr** : 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{job}\text{ in } (\texttt{'R'}, \texttt{'B'})`: :math:`n`; if :math:`\mathrm{job}=\texttt{'L'}`: :math:`1`; otherwise: :math:`0`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{job}\text{ in } (\texttt{'R'}, \texttt{'B'})`: :math:`\textit{mm}`; otherwise: :math:`0`.

            If :math:`\mathrm{howmny} = \texttt{'B'}` and :math:`\mathrm{job} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{vr}` must contain an :math:`n\times n` matrix :math:`Q` (usually the matrix of Schur vectors returned by :meth:`dhseqr`).

            If :math:`\mathrm{howmny} = \texttt{'A'}` or :math:`\texttt{'S'}`, :math:`\mathrm{vr}` need not be set.

    **Returns**
        **select** : None or bool, ndarray, shape :math:`\left(:\right)`
            If a complex eigenvector was selected as specified above, :math:`\mathrm{select}[j-1]` is set to :math:`\mathbf{True}` and :math:`\mathrm{select}[j]` to :math:`\mathbf{False}`.

            If :math:`\mathrm{howmny} = \texttt{'A'}` or :math:`\texttt{'B'}`, :math:`\mathrm{select}` is not referenced.

        **vl** : None or float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{job} = \texttt{'L'}` or :math:`\texttt{'B'}`, :math:`\mathrm{vl}` contains the computed left eigenvectors (as specified by :math:`\mathrm{howmny}` and :math:`\mathrm{select}`). The eigenvectors are stored consecutively in the columns of the array, in the same order as their eigenvalues. Corresponding to each real eigenvalue is a real eigenvector, occupying one column. Corresponding to each complex conjugate pair of eigenvalues, is a complex eigenvector occupying two columns; the first column holds the real part and the second column holds the imaginary part.

            If :math:`\mathrm{job} = \texttt{'R'}`, :math:`\mathrm{vl}` is not referenced.

        **vr** : None or float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{job} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{vr}` contains the computed right eigenvectors (as specified by :math:`\mathrm{howmny}` and :math:`\mathrm{select}`). The eigenvectors are stored consecutively in the columns of the array, in the same order as their eigenvalues. Corresponding to each real eigenvalue is a real eigenvector, occupying one column. Corresponding to each complex conjugate pair of eigenvalues, is a complex eigenvector occupying two columns; the first column holds the real part and the second column holds the imaginary part.

            If :math:`\mathrm{job} = \texttt{'L'}`, :math:`\mathrm{vr}` is not referenced.

        **m** : int
            :math:`\textit{m}`, the number of columns of :math:`\mathrm{vl}` and/or :math:`\mathrm{vr}` actually used to store the computed eigenvectors. If :math:`\mathrm{howmny} = \texttt{'A'}` or :math:`\texttt{'B'}`, :math:`\mathrm{m}` is set to :math:`n`.

    .. _f08qk-py2-py-errors:

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

                Constraint: :math:`\mathrm{job} = \texttt{'R'}`, :math:`\texttt{'L'}` or :math:`\texttt{'B'}`.

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

                Constraint: :math:`\mathrm{howmny} = \texttt{'A'}`, :math:`\texttt{'B'}`, :math:`\texttt{'O'}` or :math:`\texttt{'S'}`.

            (`errno` :math:`-4`)
                On entry, error in parameter :math:`\textit{n}`.

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

            (`errno` :math:`-11`)
                On entry, error in parameter :math:`\textit{mm}`.

                Constraint: :math:`\textit{mm}\geq n`.

            (`errno` :math:`-11`)
                On entry, error in parameter :math:`\textit{mm}`.

                Constraint: :math:`\textit{mm}\geq \textit{m}`.

    .. _f08qk-py2-py-notes:

    **Notes**
        ``dtrevc`` computes left and/or right eigenvectors of a real upper quasi-triangular matrix :math:`T` in canonical Schur form.
        Such a matrix arises from the Schur factorization of a real general matrix, as computed by :meth:`dhseqr`, for example.

        The right eigenvector :math:`x`, and the left eigenvector :math:`y`, corresponding to an eigenvalue :math:`\lambda`, are defined by:

        .. math::
            Tx = \lambda x\quad \text{ and }\quad y^\mathrm{H}T = \lambda y^\mathrm{H}\left(\text{or }T^\mathrm{T}y = \bar{\lambda }y\right)\text{.}

        Note that even though :math:`T` is real, :math:`\lambda`, :math:`x` and :math:`y` may be complex.
        If :math:`x` is an eigenvector corresponding to a complex eigenvalue :math:`\lambda`, then the complex conjugate vector :math:`\bar{x}` is the eigenvector corresponding to the complex conjugate eigenvalue :math:`\bar{\lambda }`.

        The function can compute the eigenvectors corresponding to selected eigenvalues, or it can compute all the eigenvectors.
        In the latter case the eigenvectors may optionally be pre-multiplied by an input matrix :math:`Q`.
        Normally :math:`Q` is an orthogonal matrix from the Schur factorization of a matrix :math:`A` as :math:`A = QTQ^\mathrm{T}`; if :math:`x` is a (left or right) eigenvector of :math:`T`, then :math:`Qx` is an eigenvector of :math:`A`.

        The eigenvectors are computed by forward or backward substitution.
        They are scaled so that, for a real eigenvector :math:`x`, :math:`\mathrm{max}\left(\left\lvert x_i\right\rvert \right) = 1`, and for a complex eigenvector, :math:`\mathrm{max}\left(\left\lvert \mathrm{Re}\left(x_i\right)\right\rvert +\left\lvert \mathrm{Im}\left(x_i\right)\right\rvert \right) = 1`.

    .. _f08qk-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 dtrsna(job, howmny, t, select=None, vl=None, vr=None):
    r"""
    ``dtrsna`` estimates condition numbers for specified eigenvalues and/or right eigenvectors of a real upper quasi-triangular matrix.

    .. _f08ql-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08qlf.html

    .. _f08ql-py2-py-parameters:

    **Parameters**
        **job** : str, length 1
            Indicates whether condition numbers are required for eigenvalues and/or eigenvectors.

            :math:`\mathrm{job} = \texttt{'E'}`

                Condition numbers for eigenvalues only are computed.

            :math:`\mathrm{job} = \texttt{'V'}`

                Condition numbers for eigenvectors only are computed.

            :math:`\mathrm{job} = \texttt{'B'}`

                Condition numbers for both eigenvalues and eigenvectors are computed.

        **howmny** : str, length 1
            Indicates how many condition numbers are to be computed.

            :math:`\mathrm{howmny} = \texttt{'A'}`

                Condition numbers for all eigenpairs are computed.

            :math:`\mathrm{howmny} = \texttt{'S'}`

                Condition numbers for selected eigenpairs (as specified by :math:`\mathrm{select}`) are computed.

        **t** : float, array-like, shape :math:`\left(n, n\right)`
            The :math:`n\times n` upper quasi-triangular matrix :math:`T` in canonical Schur form, as returned by :meth:`dhseqr`.

        **select** : None or bool, array-like, shape :math:`\left(:\right)`, optional
            Note: the required length for this argument is determined as follows: if :math:`\mathrm{howmny}=\texttt{'S'}`: :math:`n`; otherwise: :math:`1`.

            Specifies the eigenpairs for which condition numbers are to be computed if :math:`\mathrm{howmny} = \texttt{'S'}`. To select condition numbers for the eigenpair corresponding to the real eigenvalue :math:`\lambda_j`, :math:`\mathrm{select}[j-1]` must be set :math:`\mathbf{True}`. To select condition numbers corresponding to a complex conjugate pair of eigenvalues :math:`\lambda_j` and :math:`\lambda_{{j+1}}`, :math:`\mathrm{select}[j-1]` and/or :math:`\mathrm{select}[j]` must be set to :math:`\mathbf{True}`.

            If :math:`\mathrm{howmny} = \texttt{'A'}`, :math:`\mathrm{select}` is not referenced.

        **vl** : 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{job}\text{ in } (\texttt{'E'}, \texttt{'B'})`: :math:`n`; if :math:`\mathrm{job}=\texttt{'V'}`: :math:`1`; otherwise: :math:`0`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{job}\text{ in } (\texttt{'E'}, \texttt{'B'})`: :math:`\textit{mm}`; otherwise: :math:`0`.

            If :math:`\mathrm{job} = \texttt{'E'}` or :math:`\texttt{'B'}`, :math:`\mathrm{vl}` must contain the left eigenvectors of :math:`T` (or of any matrix :math:`QTQ^\mathrm{T}` with :math:`Q` orthogonal) corresponding to the eigenpairs specified by :math:`\mathrm{howmny}` and :math:`\mathrm{select}`. The eigenvectors **must** be stored in consecutive columns of :math:`\mathrm{vl}`, as returned by :meth:`dtrevc` or :meth:`dhsein`.

            If :math:`\mathrm{job} = \texttt{'V'}`, :math:`\mathrm{vl}` is not referenced.

        **vr** : 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{job}\text{ in } (\texttt{'E'}, \texttt{'B'})`: :math:`n`; if :math:`\mathrm{job}=\texttt{'V'}`: :math:`1`; otherwise: :math:`0`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{job}\text{ in } (\texttt{'E'}, \texttt{'B'})`: :math:`\textit{mm}`; otherwise: :math:`0`.

            If :math:`\mathrm{job} = \texttt{'E'}` or :math:`\texttt{'B'}`, :math:`\mathrm{vr}` must contain the right eigenvectors of :math:`T` (or of any matrix :math:`QTQ^\mathrm{T}` with :math:`Q` orthogonal) corresponding to the eigenpairs specified by :math:`\mathrm{howmny}` and :math:`\mathrm{select}`. The eigenvectors **must** be stored in consecutive columns of :math:`\mathrm{vr}`, as returned by :meth:`dtrevc` or :meth:`dhsein`.

            If :math:`\mathrm{job} = \texttt{'V'}`, :math:`\mathrm{vr}` is not referenced.

    **Returns**
        **s** : None or float, ndarray, shape :math:`\left(:\right)`
            The reciprocal condition numbers of the selected eigenvalues if :math:`\mathrm{job} = \texttt{'E'}` or :math:`\texttt{'B'}`, stored in consecutive elements of the array. Thus :math:`\mathrm{s}[j-1]`, :math:`\mathrm{sep}[j-1]` and the :math:`j`\ th columns of :math:`\mathrm{vl}` and :math:`\mathrm{vr}` all correspond to the same eigenpair (but not in general the :math:`j`\ th eigenpair unless all eigenpairs have been selected). For a complex conjugate pair of eigenvalues, two consecutive elements of :math:`\mathrm{s}` are set to the same value.

            If :math:`\mathrm{job} = \texttt{'V'}`, :math:`\mathrm{s}` is not referenced.

        **sep** : None or float, ndarray, shape :math:`\left(:\right)`
            The estimated reciprocal condition numbers of the selected right eigenvectors if :math:`\mathrm{job} = \texttt{'V'}` or :math:`\texttt{'B'}`, stored in consecutive elements of the array. For a complex eigenvector, two consecutive elements of :math:`\mathrm{sep}` are set to the same value. If the eigenvalues cannot be reordered to compute :math:`\mathrm{sep}[j]`, :math:`\mathrm{sep}[j]` is set to zero; this can only occur when the true value would be very small anyway.

            If :math:`\mathrm{job} = \texttt{'E'}`, :math:`\mathrm{sep}` is not referenced.

        **m** : int
            :math:`m`, the number of elements of :math:`\mathrm{s}` and/or :math:`\mathrm{sep}` actually used to store the estimated condition numbers. If :math:`\mathrm{howmny} = \texttt{'A'}`, :math:`\mathrm{m}` is set to :math:`n`.

    .. _f08ql-py2-py-errors:

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

                Constraint: :math:`\mathrm{job} = \texttt{'E'}`, :math:`\texttt{'V'}` or :math:`\texttt{'B'}`.

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

                Constraint: :math:`\mathrm{howmny} = \texttt{'A'}` or :math:`\texttt{'S'}`.

            (`errno` :math:`-4`)
                On entry, error in parameter :math:`\textit{n}`.

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

            (`errno` :math:`-13`)
                On entry, error in parameter :math:`\textit{mm}`.

    .. _f08ql-py2-py-notes:

    **Notes**
        ``dtrsna`` estimates condition numbers for specified eigenvalues and/or right eigenvectors of a real upper quasi-triangular matrix :math:`T` in canonical Schur form.
        These are the same as the condition numbers of the eigenvalues and right eigenvectors of an original matrix :math:`A = ZTZ^\mathrm{T}` (with orthogonal :math:`Z`), from which :math:`T` may have been derived.

        ``dtrsna`` computes the reciprocal of the condition number of an eigenvalue :math:`\lambda_i` as

        .. math::
            s_i = \frac{{\left\lvert v^\mathrm{H}u\right\rvert }}{{\left\lVert u\right\rVert_E\left\lVert v\right\rVert_E}}\text{,}

        where :math:`u` and :math:`v` are the right and left eigenvectors of :math:`T`, respectively, corresponding to :math:`\lambda_i`.
        This reciprocal condition number always lies between zero (i.e., ill-conditioned) and one (i.e., well-conditioned).

        An approximate error estimate for a computed eigenvalue :math:`\lambda_i` is then given by

        .. math::
            \frac{{\epsilon \left\lVert T\right\rVert }}{s_i}\text{,}

        where :math:`\epsilon` is the machine precision.

        To estimate the reciprocal of the condition number of the right eigenvector corresponding to :math:`\lambda_i`, the function first calls :meth:`dtrexc` to reorder the eigenvalues so that :math:`\lambda_i` is in the leading position:

        .. math::
            T = Q\begin{pmatrix}\lambda_i&c^\mathrm{T}\\0&T_{22}\end{pmatrix}Q^\mathrm{T}\text{.}

        The reciprocal condition number of the eigenvector is then estimated as :math:`\textit{sep}_i`, the smallest singular value of the matrix :math:`\left(T_{22}-\lambda_iI\right)`.
        This number ranges from zero (i.e., ill-conditioned) to very large (i.e., well-conditioned).

        An approximate error estimate for a computed right eigenvector :math:`u` corresponding to :math:`\lambda_i` is then given by

        .. math::
            \frac{{\epsilon \left\lVert T\right\rVert }}{\textit{sep}_i}\text{.}

    .. _f08ql-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 ztrexc(compq, t, q, ifst, ilst):
    r"""
    ``ztrexc`` reorders the Schur factorization of a complex general matrix.

    .. _f08qt-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08qtf.html

    .. _f08qt-py2-py-parameters:

    **Parameters**
        **compq** : str, length 1
            Indicates whether the matrix :math:`Q` of Schur vectors is to be updated.

            :math:`\mathrm{compq} = \texttt{'V'}`

                The matrix :math:`Q` of Schur vectors is updated.

            :math:`\mathrm{compq} = \texttt{'N'}`

                No Schur vectors are updated.

        **t** : complex, array-like, shape :math:`\left(n, n\right)`
            The :math:`n\times n` upper triangular matrix :math:`T`, as returned by :meth:`zhseqr`.

        **q** : complex, array-like, shape :math:`\left(:, :\right)`
            Note: the required extent for this argument in dimension 1 is determined as follows: if :math:`\mathrm{compq}=\texttt{'V'}`: :math:`n`; if :math:`\mathrm{compq}=\texttt{'N'}`: :math:`1`; otherwise: :math:`0`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{compq}=\texttt{'V'}`: :math:`n`; if :math:`\mathrm{compq}=\texttt{'N'}`: :math:`1`; otherwise: :math:`0`.

            If :math:`\mathrm{compq} = \texttt{'V'}`, :math:`\mathrm{q}` must contain the :math:`n\times n` unitary matrix :math:`Q` of Schur vectors.

        **ifst** : int
            :math:`\mathrm{ifst}` and :math:`\mathrm{ilst}` must specify the reordering of the diagonal elements of :math:`T`. The element with row index :math:`\mathrm{ifst}` is moved to row :math:`\mathrm{ilst}` by a sequence of exchanges between adjacent elements.

        **ilst** : int
            :math:`\mathrm{ifst}` and :math:`\mathrm{ilst}` must specify the reordering of the diagonal elements of :math:`T`. The element with row index :math:`\mathrm{ifst}` is moved to row :math:`\mathrm{ilst}` by a sequence of exchanges between adjacent elements.

    **Returns**
        **t** : complex, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{t}` is overwritten by the updated matrix :math:`\tilde{T}`.

        **q** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{compq} = \texttt{'V'}`, :math:`\mathrm{q}` contains the updated matrix of Schur vectors.

            If :math:`\mathrm{compq} = \texttt{'N'}`, :math:`\mathrm{q}` is not referenced.

    .. _f08qt-py2-py-errors:

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

                Constraint: :math:`\mathrm{compq} = \texttt{'V'}` or :math:`\texttt{'N'}`.

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

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

            (`errno` :math:`-7`)
                On entry, error in parameter :math:`\mathrm{ifst}`.

                Constraint: :math:`1\leq \mathrm{ifst}\leq n`.

            (`errno` :math:`-8`)
                On entry, error in parameter :math:`\mathrm{ilst}`.

                Constraint: :math:`1\leq \mathrm{ilst}\leq n`.

    .. _f08qt-py2-py-notes:

    **Notes**
        ``ztrexc`` reorders the Schur factorization of a complex general matrix :math:`A = QTQ^\mathrm{H}`, so that the diagonal element of :math:`T` with row index :math:`\mathrm{ifst}` is moved to row :math:`\mathrm{ilst}`.

        The reordered Schur form :math:`\tilde{T}` is computed by a unitary similarity transformation: :math:`\tilde{T} = Z^\mathrm{H}TZ`.
        Optionally the updated matrix :math:`\tilde{Q}` of Schur vectors is computed as :math:`\tilde{Q} = QZ`, giving :math:`A = \tilde{Q}\tilde{T}\tilde{Q}^\mathrm{H}`.

    .. _f08qt-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 ztrsen(job, compq, select, t, q):
    r"""
    ``ztrsen`` reorders the Schur factorization of a complex general matrix so that a selected cluster of eigenvalues appears in the leading elements on the diagonal of the Schur form.
    The function also optionally computes the reciprocal condition numbers of the cluster of eigenvalues and/or the invariant subspace.

    .. _f08qu-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08quf.html

    .. _f08qu-py2-py-parameters:

    **Parameters**
        **job** : str, length 1
            Indicates whether condition numbers are required for the cluster of eigenvalues and/or the invariant subspace.

            :math:`\mathrm{job} = \texttt{'N'}`

                No condition numbers are required.

            :math:`\mathrm{job} = \texttt{'E'}`

                Only the condition number for the cluster of eigenvalues is computed.

            :math:`\mathrm{job} = \texttt{'V'}`

                Only the condition number for the invariant subspace is computed.

            :math:`\mathrm{job} = \texttt{'B'}`

                Condition numbers for both the cluster of eigenvalues and the invariant subspace are computed.

        **compq** : str, length 1
            Indicates whether the matrix :math:`Q` of Schur vectors is to be updated.

            :math:`\mathrm{compq} = \texttt{'V'}`

                The matrix :math:`Q` of Schur vectors is updated.

            :math:`\mathrm{compq} = \texttt{'N'}`

                No Schur vectors are updated.

        **select** : bool, array-like, shape :math:`\left(n\right)`
            Specifies the eigenvalues in the selected cluster. To select a complex eigenvalue :math:`\lambda_j`, :math:`\mathrm{select}[j-1]` must be set :math:`\mathbf{True}`.

        **t** : complex, array-like, shape :math:`\left(n, n\right)`
            The :math:`n\times n` upper triangular matrix :math:`T`, as returned by :meth:`zhseqr`.

        **q** : complex, array-like, shape :math:`\left(:, :\right)`
            Note: the required extent for this argument in dimension 1 is determined as follows: if :math:`\mathrm{compq}=\texttt{'V'}`: :math:`n`; if :math:`\mathrm{compq}=\texttt{'N'}`: :math:`1`; otherwise: :math:`0`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{compq}=\texttt{'V'}`: :math:`n`; if :math:`\mathrm{compq}=\texttt{'N'}`: :math:`1`; otherwise: :math:`0`.

            If :math:`\mathrm{compq} = \texttt{'V'}`, :math:`\mathrm{q}` must contain the :math:`n\times n` unitary matrix :math:`Q` of Schur vectors, as returned by :meth:`zhseqr`.

    **Returns**
        **t** : complex, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{t}` is overwritten by the updated matrix :math:`\tilde{T}`.

        **q** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{compq} = \texttt{'V'}`, :math:`\mathrm{q}` contains the updated matrix of Schur vectors; the first :math:`m` columns of :math:`Q` form an orthonormal basis for the specified invariant subspace.

            If :math:`\mathrm{compq} = \texttt{'N'}`, :math:`\mathrm{q}` is not referenced.

        **w** : complex, ndarray, shape :math:`\left(n\right)`
            The reordered eigenvalues of :math:`\tilde{T}`. The eigenvalues are stored in the same order as on the diagonal of :math:`\tilde{T}`.

        **m** : int
            :math:`m`, the dimension of the specified invariant subspace, which is the same as the number of selected eigenvalues (see :math:`\mathrm{select}`); :math:`0\leq m\leq n`.

        **s** : float
            If :math:`\mathrm{job} = \texttt{'E'}` or :math:`\texttt{'B'}`, :math:`\mathrm{s}` is a lower bound on the reciprocal condition number of the average of the selected cluster of eigenvalues. If :math:`\mathrm{m} = 0` or :math:`n`, :math:`\mathrm{s} = 1`.

            If :math:`\mathrm{job} = \texttt{'N'}` or :math:`\texttt{'V'}`, :math:`\mathrm{s}` is not referenced.

        **sep** : float
            If :math:`\mathrm{job} = \texttt{'V'}` or :math:`\texttt{'B'}`, :math:`\mathrm{sep}` is the estimated reciprocal condition number of the specified invariant subspace. If :math:`\mathrm{m} = 0` or :math:`n`, :math:`\mathrm{sep} = \left\lVert T\right\rVert`.

            If :math:`\mathrm{job} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{sep}` is not referenced.

    .. _f08qu-py2-py-errors:

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

                Constraint: :math:`\mathrm{job} = \texttt{'N'}`, :math:`\texttt{'E'}`, :math:`\texttt{'V'}` or :math:`\texttt{'B'}`.

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

                Constraint: :math:`\mathrm{compq} = \texttt{'V'}` or :math:`\texttt{'N'}`.

            (`errno` :math:`-4`)
                On entry, error in parameter :math:`\textit{n}`.

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

    .. _f08qu-py2-py-notes:

    **Notes**
        ``ztrsen`` reorders the Schur factorization of a complex general matrix :math:`A = QTQ^\mathrm{H}`, so that a selected cluster of eigenvalues appears in the leading diagonal elements of the Schur form.

        The reordered Schur form :math:`\tilde{T}` is computed by a unitary similarity transformation: :math:`\tilde{T} = Z^\mathrm{H}TZ`.
        Optionally the updated matrix :math:`\tilde{Q}` of Schur vectors is computed as :math:`\tilde{Q} = QZ`, giving :math:`A = \tilde{Q}\tilde{T}\tilde{Q}^\mathrm{H}`.

        Let :math:`\tilde{T} = \begin{pmatrix}T_{11}&T_{12}\\0&T_{22}\end{pmatrix}`, where the selected eigenvalues are precisely the eigenvalues of the leading :math:`m\times m` sub-matrix :math:`T_{11}`.
        Let :math:`\tilde{Q}` be correspondingly partitioned as :math:`\begin{pmatrix}Q_1&Q_2\end{pmatrix}` where :math:`Q_1` consists of the first :math:`m` columns of :math:`Q`.
        Then :math:`AQ_1 = Q_1T_{11}`, and so the :math:`m` columns of :math:`Q_1` form an orthonormal basis for the invariant subspace corresponding to the selected cluster of eigenvalues.

        Optionally the function also computes estimates of the reciprocal condition numbers of the average of the cluster of eigenvalues and of the invariant subspace.

    .. _f08qu-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 ztrsyl(trana, tranb, isgn, a, b, c):
    r"""
    ``ztrsyl`` solves the complex triangular Sylvester matrix equation.

    .. _f08qv-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08qvf.html

    .. _f08qv-py2-py-parameters:

    **Parameters**
        **trana** : str, length 1
            Specifies the option :math:`\mathrm{op}\left(A\right)`.

            :math:`\mathrm{trana} = \texttt{'N'}`

                :math:`\mathrm{op}\left(A\right) = A`.

            :math:`\mathrm{trana} = \texttt{'C'}`

                :math:`\mathrm{op}\left(A\right) = A^\mathrm{H}`.

        **tranb** : str, length 1
            Specifies the option :math:`\mathrm{op}\left(B\right)`.

            :math:`\mathrm{tranb} = \texttt{'N'}`

                :math:`\mathrm{op}\left(B\right) = B`.

            :math:`\mathrm{tranb} = \texttt{'C'}`

                :math:`\mathrm{op}\left(B\right) = B^\mathrm{H}`.

        **isgn** : int
            Indicates the form of the Sylvester equation.

            :math:`\mathrm{isgn} = +1`

                The equation is of the form :math:`\mathrm{op}\left(A\right)X+X\mathrm{op}\left(B\right) = \alpha C`.

            :math:`\mathrm{isgn} = -1`

                The equation is of the form :math:`\mathrm{op}\left(A\right)X-X\mathrm{op}\left(B\right) = \alpha C`.

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

        **b** : complex, array-like, shape :math:`\left(n, n\right)`
            The :math:`n\times n` upper triangular matrix :math:`B`.

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

    **Returns**
        **c** : complex, ndarray, shape :math:`\left(m, n\right)`
            :math:`\mathrm{c}` is overwritten by the solution matrix :math:`X`.

        **scal** : float
            The value of the scale factor :math:`\alpha`.

    .. _f08qv-py2-py-errors:

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

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

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

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

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

                Constraint: :math:`\mathrm{isgn} = +1` or :math:`-1`.

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

    **Warns**
        **NagAlgorithmicWarning**
            (`errno` :math:`1`)
                :math:`A` and :math:`B` have common or close eigenvalues, perturbed values of which were used to solve the equation.

    .. _f08qv-py2-py-notes:

    **Notes**
        ``ztrsyl`` solves the complex Sylvester matrix equation

        .. math::
            \mathrm{op}\left(A\right)X\pm X\mathrm{op}\left(B\right) = \alpha C\text{,}

        where :math:`\mathrm{op}\left(A\right) = A` or :math:`A^\mathrm{H}`, and the matrices :math:`A` and :math:`B` are upper triangular; :math:`\alpha` is a scale factor (:math:`\text{}\leq 1`) determined by the function to avoid overflow in :math:`X`; :math:`A` is :math:`m\times m` and :math:`B` is :math:`n\times n` while the right-hand side matrix :math:`C` and the solution matrix :math:`X` are both :math:`m\times n`.
        The matrix :math:`X` is obtained by a straightforward process of back-substitution (see Golub and Van Loan (1996)).

        Note that the equation has a unique solution if and only if :math:`\alpha_i\pm \beta_j\neq 0`, where :math:`\left\{\alpha_i\right\}` and :math:`\left\{\beta_j\right\}` are the eigenvalues of :math:`A` and :math:`B` respectively and the sign (:math:`+` or :math:`-`) is the same as that used in the equation to be solved.

    .. _f08qv-py2-py-references:

    **References**
        Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore

        Higham, N J, 1992, `Perturbation theory and backward error for` :math:`{AX}-{XB} = C`, Numerical Analysis Report, University of Manchester
    """
    raise NotImplementedError

def ztrevc(job, howmny, t, select=None, vl=None, vr=None):
    r"""
    ``ztrevc`` computes selected left and/or right eigenvectors of a complex upper triangular matrix.

    .. _f08qx-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08qxf.html

    .. _f08qx-py2-py-parameters:

    **Parameters**
        **job** : str, length 1
            Indicates whether left and/or right eigenvectors are to be computed.

            :math:`\mathrm{job} = \texttt{'R'}`

                Only right eigenvectors are computed.

            :math:`\mathrm{job} = \texttt{'L'}`

                Only left eigenvectors are computed.

            :math:`\mathrm{job} = \texttt{'B'}`

                Both left and right eigenvectors are computed.

        **howmny** : str, length 1
            Indicates how many eigenvectors are to be computed.

            :math:`\mathrm{howmny} = \texttt{'A'}`

                All eigenvectors (as specified by :math:`\mathrm{job}`) are computed.

            :math:`\mathrm{howmny} = \texttt{'B'}`

                All eigenvectors (as specified by :math:`\mathrm{job}`) are computed and then pre-multiplied by the matrix :math:`Q` (which is overwritten).

            :math:`\mathrm{howmny} = \texttt{'S'}`

                Selected eigenvectors (as specified by :math:`\mathrm{job}` and :math:`\mathrm{select}`) are computed.

        **t** : complex, array-like, shape :math:`\left(n, n\right)`
            The :math:`n\times n` upper triangular matrix :math:`T`, as returned by :meth:`zhseqr`.

        **select** : None or bool, array-like, shape :math:`\left(:\right)`, optional
            Note: the required length for this argument is determined as follows: if :math:`\mathrm{howmny}=\texttt{'S'}`: :math:`n`; otherwise: :math:`1`.

            Specifies which eigenvectors are to be computed if :math:`\mathrm{howmny} = \texttt{'S'}`. To obtain the eigenvector corresponding to the eigenvalue :math:`\lambda_j`, :math:`\mathrm{select}[j-1]` must be set :math:`\mathbf{True}`.

            If :math:`\mathrm{howmny} = \texttt{'A'}` or :math:`\texttt{'B'}`, :math:`\mathrm{select}` is not referenced.

        **vl** : 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{job}\text{ in } (\texttt{'L'}, \texttt{'B'})`: :math:`n`; if :math:`\mathrm{job}=\texttt{'R'}`: :math:`1`; otherwise: :math:`0`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{job}\text{ in } (\texttt{'L'}, \texttt{'B'})`: :math:`\textit{mm}`; otherwise: :math:`0`.

            If :math:`\mathrm{howmny} = \texttt{'B'}` and :math:`\mathrm{job} = \texttt{'L'}` or :math:`\texttt{'B'}`, :math:`\mathrm{vl}` must contain an :math:`n\times n` matrix :math:`Q` (usually the matrix of Schur vectors returned by :meth:`zhseqr`).

            If :math:`\mathrm{howmny} = \texttt{'A'}` or :math:`\texttt{'S'}`, :math:`\mathrm{vl}` need not be set.

        **vr** : 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{job}\text{ in } (\texttt{'R'}, \texttt{'B'})`: :math:`n`; if :math:`\mathrm{job}=\texttt{'L'}`: :math:`1`; otherwise: :math:`0`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{job}\text{ in } (\texttt{'R'}, \texttt{'B'})`: :math:`\textit{mm}`; otherwise: :math:`0`.

            If :math:`\mathrm{howmny} = \texttt{'B'}` and :math:`\mathrm{job} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{vr}` must contain an :math:`n\times n` matrix :math:`Q` (usually the matrix of Schur vectors returned by :meth:`zhseqr`).

            If :math:`\mathrm{howmny} = \texttt{'A'}` or :math:`\texttt{'S'}`, :math:`\mathrm{vr}` need not be set.

    **Returns**
        **t** : complex, ndarray, shape :math:`\left(n, n\right)`
            Is used as internal workspace prior to being restored and hence is unchanged.

        **vl** : None or complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{job} = \texttt{'L'}` or :math:`\texttt{'B'}`, :math:`\mathrm{vl}` contains the computed left eigenvectors (as specified by :math:`\mathrm{howmny}` and :math:`\mathrm{select}`). The eigenvectors are stored consecutively in the columns of the array, in the same order as their eigenvalues.

            If :math:`\mathrm{job} = \texttt{'R'}`, :math:`\mathrm{vl}` is not referenced.

        **vr** : None or complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{job} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{vr}` contains the computed right eigenvectors (as specified by :math:`\mathrm{howmny}` and :math:`\mathrm{select}`). The eigenvectors are stored consecutively in the columns of the array, in the same order as their eigenvalues.

            If :math:`\mathrm{job} = \texttt{'L'}`, :math:`\mathrm{vr}` is not referenced.

        **m** : int
            :math:`\textit{m}`, the number of selected eigenvectors. If :math:`\mathrm{howmny} = \texttt{'A'}` or :math:`\texttt{'B'}`, :math:`\mathrm{m}` is set to :math:`n`.

    .. _f08qx-py2-py-errors:

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

                Constraint: :math:`\mathrm{job} = \texttt{'R'}`, :math:`\texttt{'L'}` or :math:`\texttt{'B'}`.

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

                Constraint: :math:`\mathrm{howmny} = \texttt{'A'}`, :math:`\texttt{'B'}`, :math:`\texttt{'O'}` or :math:`\texttt{'S'}`.

            (`errno` :math:`-4`)
                On entry, error in parameter :math:`\textit{n}`.

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

            (`errno` :math:`-11`)
                On entry, error in parameter :math:`\textit{mm}`.

                Constraint: :math:`\textit{mm}\geq n`.

            (`errno` :math:`-11`)
                On entry, error in parameter :math:`\textit{mm}`.

                Constraint: :math:`\textit{mm}\geq \textit{m}`.

    .. _f08qx-py2-py-notes:

    **Notes**
        ``ztrevc`` computes left and/or right eigenvectors of a complex upper triangular matrix :math:`T`.
        Such a matrix arises from the Schur factorization of a complex general matrix, as computed by :meth:`zhseqr`, for example.

        The right eigenvector :math:`x`, and the left eigenvector :math:`y`, corresponding to an eigenvalue :math:`\lambda`, are defined by:

        .. math::
            Tx = \lambda x\quad \text{ and }\quad y^\mathrm{H}T = \lambda y^\mathrm{H}\left(\text{or }T^\mathrm{H}y = \bar{\lambda }y\right)\text{.}

        The function can compute the eigenvectors corresponding to selected eigenvalues, or it can compute all the eigenvectors.
        In the latter case the eigenvectors may optionally be pre-multiplied by an input matrix :math:`Q`.
        Normally :math:`Q` is a unitary matrix from the Schur factorization of a matrix :math:`A` as :math:`A = QTQ^\mathrm{H}`; if :math:`x` is a (left or right) eigenvector of :math:`T`, then :math:`Qx` is an eigenvector of :math:`A`.

        The eigenvectors are computed by forward or backward substitution.
        They are scaled so that :math:`\mathrm{max}\left({\left\lvert \mathrm{Re}\left(x_i\right)\right\rvert +\left\lvert \mathrm{Im}\left(x_i\right)\right\rvert }\right) = 1`.

    .. _f08qx-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 ztrsna(job, howmny, t, select=None, vl=None, vr=None):
    r"""
    ``ztrsna`` estimates condition numbers for specified eigenvalues and/or right eigenvectors of a complex upper triangular matrix.

    .. _f08qy-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08qyf.html

    .. _f08qy-py2-py-parameters:

    **Parameters**
        **job** : str, length 1
            Indicates whether condition numbers are required for eigenvalues and/or eigenvectors.

            :math:`\mathrm{job} = \texttt{'E'}`

                Condition numbers for eigenvalues only are computed.

            :math:`\mathrm{job} = \texttt{'V'}`

                Condition numbers for eigenvectors only are computed.

            :math:`\mathrm{job} = \texttt{'B'}`

                Condition numbers for both eigenvalues and eigenvectors are computed.

        **howmny** : str, length 1
            Indicates how many condition numbers are to be computed.

            :math:`\mathrm{howmny} = \texttt{'A'}`

                Condition numbers for all eigenpairs are computed.

            :math:`\mathrm{howmny} = \texttt{'S'}`

                Condition numbers for selected eigenpairs (as specified by :math:`\mathrm{select}`) are computed.

        **t** : complex, array-like, shape :math:`\left(n, n\right)`
            The :math:`n\times n` upper triangular matrix :math:`T`, as returned by :meth:`zhseqr`.

        **select** : None or bool, array-like, shape :math:`\left(:\right)`, optional
            Note: the required length for this argument is determined as follows: if :math:`\mathrm{howmny}=\texttt{'S'}`: :math:`n`; otherwise: :math:`1`.

            Specifies the eigenpairs for which condition numbers are to be computed if :math:`\mathrm{howmny} = \texttt{'S'}`. To select condition numbers for the eigenpair corresponding to the eigenvalue :math:`\lambda_j`, :math:`\mathrm{select}[j-1]` must be set to :math:`\mathbf{True}`.

            If :math:`\mathrm{howmny} = \texttt{'A'}`, :math:`\mathrm{select}` is not referenced.

        **vl** : 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{job}\text{ in } (\texttt{'E'}, \texttt{'B'})`: :math:`n`; if :math:`\mathrm{job}=\texttt{'V'}`: :math:`1`; otherwise: :math:`0`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{job}\text{ in } (\texttt{'E'}, \texttt{'B'})`: :math:`\textit{mm}`; otherwise: :math:`0`.

            If :math:`\mathrm{job} = \texttt{'E'}` or :math:`\texttt{'B'}`, :math:`\mathrm{vl}` must contain the left eigenvectors of :math:`T` (or of any matrix :math:`QTQ^\mathrm{H}` with :math:`Q` unitary) corresponding to the eigenpairs specified by :math:`\mathrm{howmny}` and :math:`\mathrm{select}`. The eigenvectors **must** be stored in consecutive columns of :math:`\mathrm{vl}`, as returned by :meth:`ztrevc` or :meth:`zhsein`.

            If :math:`\mathrm{job} = \texttt{'V'}`, :math:`\mathrm{vl}` is not referenced.

        **vr** : 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{job}\text{ in } (\texttt{'E'}, \texttt{'B'})`: :math:`n`; if :math:`\mathrm{job}=\texttt{'V'}`: :math:`1`; otherwise: :math:`0`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{job}\text{ in } (\texttt{'E'}, \texttt{'B'})`: :math:`\textit{mm}`; otherwise: :math:`0`.

            If :math:`\mathrm{job} = \texttt{'E'}` or :math:`\texttt{'B'}`, :math:`\mathrm{vr}` must contain the right eigenvectors of :math:`T` (or of any matrix :math:`QTQ^\mathrm{H}` with :math:`Q` unitary) corresponding to the eigenpairs specified by :math:`\mathrm{howmny}` and :math:`\mathrm{select}`. The eigenvectors **must** be stored in consecutive columns of :math:`\mathrm{vr}`, as returned by :meth:`ztrevc` or :meth:`zhsein`.

            If :math:`\mathrm{job} = \texttt{'V'}`, :math:`\mathrm{vr}` is not referenced.

    **Returns**
        **s** : None or float, ndarray, shape :math:`\left(:\right)`
            The reciprocal condition numbers of the selected eigenvalues if :math:`\mathrm{job} = \texttt{'E'}` or :math:`\texttt{'B'}`, stored in consecutive elements of the array. Thus :math:`\mathrm{s}[j-1]`, :math:`\mathrm{sep}[j-1]` and the :math:`j`\ th columns of :math:`\mathrm{vl}` and :math:`\mathrm{vr}` all correspond to the same eigenpair (but not in general the :math:`j`\ th eigenpair unless all eigenpairs have been selected).

            If :math:`\mathrm{job} = \texttt{'V'}`, :math:`\mathrm{s}` is not referenced.

        **sep** : None or float, ndarray, shape :math:`\left(:\right)`
            The estimated reciprocal condition numbers of the selected right eigenvectors if :math:`\mathrm{job} = \texttt{'V'}` or :math:`\texttt{'B'}`, stored in consecutive elements of the array.

            If :math:`\mathrm{job} = \texttt{'E'}`, :math:`\mathrm{sep}` is not referenced.

        **m** : int
            :math:`\textit{m}`, the number of selected eigenpairs. If :math:`\mathrm{howmny} = \texttt{'A'}`, :math:`\mathrm{m}` is set to :math:`n`.

    .. _f08qy-py2-py-errors:

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

                Constraint: :math:`\mathrm{job} = \texttt{'E'}`, :math:`\texttt{'V'}` or :math:`\texttt{'B'}`.

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

                Constraint: :math:`\mathrm{howmny} = \texttt{'A'}` or :math:`\texttt{'S'}`.

            (`errno` :math:`-4`)
                On entry, error in parameter :math:`\textit{n}`.

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

            (`errno` :math:`-13`)
                On entry, error in parameter :math:`\textit{mm}`.

                Constraint: :math:`\textit{mm}\geq n`.

            (`errno` :math:`-13`)
                On entry, error in parameter :math:`\textit{mm}`.

                Constraint: :math:`\textit{mm}\geq \textit{m}`.

    .. _f08qy-py2-py-notes:

    **Notes**
        ``ztrsna`` estimates condition numbers for specified eigenvalues and/or right eigenvectors of a complex upper triangular matrix :math:`T`.
        These are the same as the condition numbers of the eigenvalues and right eigenvectors of an original matrix :math:`A = ZTZ^\mathrm{H}` (with unitary :math:`Z`), from which :math:`T` may have been derived.

        ``ztrsna`` computes the reciprocal of the condition number of an eigenvalue :math:`\lambda_i` as

        .. math::
            s_i = \frac{{\left\lvert v^\mathrm{H}u\right\rvert }}{{\left\lVert u\right\rVert_E\left\lVert v\right\rVert_E}}\text{,}

        where :math:`u` and :math:`v` are the right and left eigenvectors of :math:`T`, respectively, corresponding to :math:`\lambda_i`.
        This reciprocal condition number always lies between zero (i.e., ill-conditioned) and one (i.e., well-conditioned).

        An approximate error estimate for a computed eigenvalue :math:`\lambda_i` is then given by

        .. math::
            \frac{{\epsilon \left\lVert T\right\rVert }}{s_i}\text{,}

        where :math:`\epsilon` is the machine precision.

        To estimate the reciprocal of the condition number of the right eigenvector corresponding to :math:`\lambda_i`, the function first calls :meth:`ztrexc` to reorder the eigenvalues so that :math:`\lambda_i` is in the leading position:

        .. math::
            T = Q\begin{pmatrix}\lambda_i&c^\mathrm{H}\\0&T_{22}\end{pmatrix}Q^\mathrm{H}\text{.}

        The reciprocal condition number of the eigenvector is then estimated as :math:`\textit{sep}_i`, the smallest singular value of the matrix :math:`\left(T_{22}-\lambda_iI\right)`.
        This number ranges from zero (i.e., ill-conditioned) to very large (i.e., well-conditioned).

        An approximate error estimate for a computed right eigenvector :math:`u` corresponding to :math:`\lambda_i` is then given by

        .. math::
            \frac{{\epsilon \left\lVert T\right\rVert }}{\textit{sep}_i}\text{.}

    .. _f08qy-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 dorcsd(m, p, q, x11, x12, x21, x22, jobu1='Y', jobu2='Y', jobv1t='Y', jobv2t='Y', trans='N', signs='D'):
    r"""
    ``dorcsd`` computes the CS decomposition of a real :math:`m\times m` orthogonal matrix :math:`X`, partitioned into a :math:`2\times 2` array of submatrices.

    .. _f08ra-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08raf.html

    .. _f08ra-py2-py-parameters:

    **Parameters**
        **m** : int
            :math:`m`, the number of rows and columns in the orthogonal matrix :math:`X`.

        **p** : int
            :math:`p`, the number of rows in :math:`X_{{11}}` and :math:`X_{{12}}`.

        **q** : int
            :math:`q`, the number of columns in :math:`X_{{11}}` and :math:`X_{{21}}`.

        **x11** : float, array-like, shape :math:`\left(:, :\right)`
            Note: the required extent for this argument in dimension 1 is determined as follows: if :math:`\mathrm{trans}=\texttt{'T'}`: :math:`\mathrm{q}`; otherwise: :math:`\mathrm{p}`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{trans}=\texttt{'T'}`: :math:`\mathrm{p}`; otherwise: :math:`\mathrm{q}`.

            The upper left partition of the orthogonal matrix :math:`X` whose CSD is desired.

        **x12** : float, array-like, shape :math:`\left(:, :\right)`
            Note: the required extent for this argument in dimension 1 is determined as follows: if :math:`\mathrm{trans}=\texttt{'T'}`: :math:`{\mathrm{m}-\mathrm{q}}`; otherwise: :math:`\mathrm{p}`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{trans}=\texttt{'T'}`: :math:`\mathrm{p}`; otherwise: :math:`{ \mathrm{m}-\mathrm{q} }`.

            The upper right partition of the orthogonal matrix :math:`X` whose CSD is desired.

        **x21** : float, array-like, shape :math:`\left(:, :\right)`
            Note: the required extent for this argument in dimension 1 is determined as follows: if :math:`\mathrm{trans}=\texttt{'T'}`: :math:`\mathrm{q}`; otherwise: :math:`{\mathrm{m}-\mathrm{p}}`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{trans}=\texttt{'T'}`: :math:`{\mathrm{m}-\mathrm{p}}`; otherwise: :math:`\mathrm{q}`.

            The lower left partition of the orthogonal matrix :math:`X` whose CSD is desired.

        **x22** : float, array-like, shape :math:`\left(:, :\right)`
            Note: the required extent for this argument in dimension 1 is determined as follows: if :math:`\mathrm{trans}=\texttt{'T'}`: :math:`{\mathrm{m}-\mathrm{q}}`; otherwise: :math:`{\mathrm{m}-\mathrm{p}}`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{trans}=\texttt{'T'}`: :math:`{\mathrm{m}-\mathrm{p}}`; otherwise: :math:`{ \mathrm{m}-\mathrm{q} }`.

            The lower right partition of the orthogonal matrix :math:`X` CSD is desired.

        **jobu1** : str, length 1, optional
                If :math:`\mathrm{jobu1} = \texttt{'Y'}`, :math:`U_1` is computed;

                otherwise, :math:`U_1` is not computed.

        **jobu2** : str, length 1, optional
                If :math:`\mathrm{jobu2} = \texttt{'Y'}`, :math:`U_2` is computed;

                otherwise, :math:`U_2` is not computed.

        **jobv1t** : str, length 1, optional
                If :math:`\mathrm{jobv1t} = \texttt{'Y'}`, :math:`V_1^\mathrm{T}` is computed;

                otherwise, :math:`V_1^\mathrm{T}` is not computed.

        **jobv2t** : str, length 1, optional
                If :math:`\mathrm{jobv2t} = \texttt{'Y'}`, :math:`V_2^\mathrm{T}` is computed;

                otherwise, :math:`V_2^\mathrm{T}` is not computed.

        **trans** : str, length 1, optional
                If :math:`\mathrm{trans} = \texttt{'T'}`, :math:`X`, :math:`U_1`, :math:`U_2`, :math:`V_1^\mathrm{T}` and :math:`V_2^\mathrm{T}` are stored in row-major order;

                otherwise, :math:`X`, :math:`U_1`, :math:`U_2`, :math:`V_1^\mathrm{T}` and :math:`V_2^\mathrm{T}` are stored in column-major order.

        **signs** : str, length 1, optional
                If :math:`\mathrm{signs} = \texttt{'O'}`, the lower-left block is made nonpositive (the other convention);

                otherwise, the upper-right block is made nonpositive (the default convention).

    **Returns**
        **x11** : float, ndarray, shape :math:`\left(:, :\right)`
            Contains details of the orthogonal matrix used in a simultaneous bidiagonalization process.

        **x12** : float, ndarray, shape :math:`\left(:, :\right)`
            Contains details of the orthogonal matrix used in a simultaneous bidiagonalization process.

        **x21** : float, ndarray, shape :math:`\left(:, :\right)`
            Contains details of the orthogonal matrix used in a simultaneous bidiagonalization process.

        **x22** : float, ndarray, shape :math:`\left(:, :\right)`
            Contains details of the orthogonal matrix used in a simultaneous bidiagonalization process.

        **theta** : float, ndarray, shape :math:`\left(\min\left(\mathrm{p},{\mathrm{m}-\mathrm{p}}\right)\right)`
            The values :math:`\theta_i` for :math:`i = 1,2,\ldots,r` where :math:`r = \mathrm{min}\left(p, {m-p}, q, {m-q}\right)`. The diagonal submatrices :math:`C` and :math:`S` of :math:`\Sigma_p` are constructed from these values as

                :math:`C = \mathrm{diag}\left(\cos\left(\mathrm{theta}[0]\right), \ldots, \cos\left(\mathrm{theta}[r-1]\right)\right)` and

                :math:`S = \mathrm{diag}\left(\sin\left(\mathrm{theta}[0]\right), \ldots, \sin\left(\mathrm{theta}[r-1]\right)\right)`.

        **u1** : None or float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobu1} = \texttt{'Y'}`, :math:`\mathrm{u1}` contains the :math:`p\times p` orthogonal matrix :math:`U_1`.

        **u2** : None or float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobu2} = \texttt{'Y'}`, :math:`\mathrm{u2}` contains the :math:`m-p\times m-p` orthogonal matrix :math:`U_2`.

        **v1t** : None or float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobv1t} = \texttt{'Y'}`, :math:`\mathrm{v1t}` contains the :math:`q\times q` orthogonal matrix :math:`V_1^T`.

        **v2t** : None or float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobv2t} = \texttt{'Y'}`, :math:`\mathrm{v2t}` contains the :math:`m-q\times m-q` orthogonal matrix :math:`V_2^T`.

    .. _f08ra-py2-py-errors:

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

                Constraint: :math:`\mathrm{m}\geq 0`.

            (`errno` :math:`-8`)
                On entry, error in parameter :math:`\mathrm{p}`.

                Constraint: :math:`0\leq \mathrm{p}\leq \mathrm{m}`.

            (`errno` :math:`-9`)
                On entry, error in parameter :math:`\mathrm{q}`.

                Constraint: :math:`0\leq \mathrm{q}\leq \mathrm{m}`.

            (`errno` :math:`i > 0`)
                The Jacobi-type procedure failed to converge during an internal reduction to bidiagonal-block form. The process requires convergence to :math:`\mathrm{min}\left(\mathrm{p}, {\mathrm{m}-\mathrm{p}}, \mathrm{q}, {\mathrm{m}-\mathrm{q}}\right)` values, the value of :math:`\textit{errno}` gives the number of converged values.

    .. _f08ra-py2-py-notes:

    **Notes**
        The :math:`m\times m` orthogonal matrix :math:`X` is partitioned as

        .. math::
            X = \begin{pmatrix}X_{{11}}&X_{{12}}\\X_{{21}}&X_{{22}}\end{pmatrix}

        where :math:`X_{{11}}` is a :math:`p\times q` submatrix and the dimensions of the other submatrices :math:`X_{{12}}`, :math:`X_{{21}}` and :math:`X_{{22}}` are such that :math:`X` remains :math:`m\times m`.

        The CS decomposition of :math:`X` is :math:`X = U\Sigma_pV^\mathrm{T}` where :math:`U`, :math:`V` and :math:`\Sigma_p` are :math:`m\times m` matrices, such that

        .. math::
            U = \begin{pmatrix}U_1&0\\0&U_2\end{pmatrix}

        is an orthogonal matrix containing the :math:`p\times p` orthogonal matrix :math:`U_1` and the :math:`\left(m-p\right)\times \left(m-p\right)` orthogonal matrix :math:`U_2`;

        .. math::
            V = \begin{pmatrix}V_1&0\\0&V_2\end{pmatrix}

        is an orthogonal matrix containing the :math:`q\times q` orthogonal matrix :math:`V_1` and the :math:`\left(m-q\right)\times \left(m-q\right)` orthogonal matrix :math:`V_2`; and

        .. math::
            \Sigma_p = \begin{pmatrix}I_{{11}}&&0&&0&0\\&C&0&0&{-S}&\\0&0&&0&&{-I}_{{12}}\\&0&0&I_{{22}}&&0\\0&S&&&C&0\\0&&I_{{21}}&0&0&\end{pmatrix}

        contains the :math:`r\times r` non-negative diagonal submatrices :math:`C` and :math:`S` satisfying :math:`C^2+S^2 = I`, where :math:`r = \mathrm{min}\left(p, {m-p}, q, {m-q}\right)` and the top left partition is :math:`p\times q`.

        The identity matrix :math:`I_{{11}}` is of order :math:`\mathrm{min}\left(p, q\right)-r` and vanishes if :math:`\mathrm{min}\left(p, q\right) = r`.

        The identity matrix :math:`I_{{12}}` is of order :math:`\mathrm{min}\left(p, {m-q}\right)-r` and vanishes if :math:`\mathrm{min}\left(p, {m-q}\right) = r`.

        The identity matrix :math:`I_{{21}}` is of order :math:`\mathrm{min}\left({m-p}, q\right)-r` and vanishes if :math:`\mathrm{min}\left({m-p}, q\right) = r`.

        The identity matrix :math:`I_{{22}}` is of order :math:`\mathrm{min}\left({m-p}, {m-q}\right)-r` and vanishes if :math:`\mathrm{min}\left({m-p}, {m-q}\right) = r`.

        In each of the four cases :math:`r = p,q{,m-p},{m-q}` at least two of the identity matrices vanish.

        The indicated zeros represent augmentations by additional rows or columns (but not both) to the square diagonal matrices formed by :math:`I_{{ij}}` and :math:`C` or :math:`S`.

        :math:`\Sigma_p` does not need to be stored in full; it is sufficient to return only the values :math:`\theta_i` for :math:`i = 1,2,\ldots,r` where :math:`C_{{ii}} = \cos\left(\theta_i\right)` and :math:`S_{{ii}} = \sin\left(\theta_i\right)`.

        The algorithm used to perform the complete :math:`CS` decomposition is described fully in Sutton (2009) including discussions of the stability and accuracy of the algorithm.

    .. _f08ra-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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, 2012, `Matrix Computations`, (4th Edition), Johns Hopkins University Press, Baltimore

        Sutton, B D, 2009, `Computing the complete` :math:`CS` `decomposition`, Numerical Algorithms (Volume 50) (1017--1398), Springer US, 33--65, https://dx.doi.org/10.1007/s11075-008-9215-6
    """
    raise NotImplementedError

def zuncsd(m, p, q, x11, x12, x21, x22, jobu1='Y', jobu2='Y', jobv1t='Y', jobv2t='Y', trans='N', signs='D'):
    r"""
    ``zuncsd`` computes the CS decomposition of a complex :math:`m\times m` unitary matrix :math:`X`, partitioned into a :math:`2\times 2` array of submatrices.

    .. _f08rn-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08rnf.html

    .. _f08rn-py2-py-parameters:

    **Parameters**
        **m** : int
            :math:`m`, the number of rows and columns in the unitary matrix :math:`X`.

        **p** : int
            :math:`p`, the number of rows in :math:`X_{{11}}` and :math:`X_{{12}}`.

        **q** : int
            :math:`q`, the number of columns in :math:`X_{{11}}` and :math:`X_{{21}}`.

        **x11** : complex, array-like, shape :math:`\left(:, :\right)`
            Note: the required extent for this argument in dimension 1 is determined as follows: if :math:`\mathrm{trans}=\texttt{'T'}`: :math:`\mathrm{q}`; otherwise: :math:`\mathrm{p}`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{trans}=\texttt{'T'}`: :math:`\mathrm{p}`; otherwise: :math:`\mathrm{q}`.

            The upper left partition of the unitary matrix :math:`X` whose CSD is desired.

        **x12** : complex, array-like, shape :math:`\left(:, :\right)`
            Note: the required extent for this argument in dimension 1 is determined as follows: if :math:`\mathrm{trans}=\texttt{'T'}`: :math:`{\mathrm{m}-\mathrm{q}}`; otherwise: :math:`\mathrm{p}`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{trans}=\texttt{'T'}`: :math:`\mathrm{p}`; otherwise: :math:`{ \mathrm{m}-\mathrm{q} }`.

            The upper right partition of the unitary matrix :math:`X` whose CSD is desired.

        **x21** : complex, array-like, shape :math:`\left(:, :\right)`
            Note: the required extent for this argument in dimension 1 is determined as follows: if :math:`\mathrm{trans}=\texttt{'T'}`: :math:`\mathrm{q}`; otherwise: :math:`{\mathrm{m}-\mathrm{p}}`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{trans}=\texttt{'T'}`: :math:`{\mathrm{m}-\mathrm{p}}`; otherwise: :math:`\mathrm{q}`.

            The lower left partition of the unitary matrix :math:`X` whose CSD is desired.

        **x22** : complex, array-like, shape :math:`\left(:, :\right)`
            Note: the required extent for this argument in dimension 1 is determined as follows: if :math:`\mathrm{trans}=\texttt{'T'}`: :math:`{\mathrm{m}-\mathrm{q}}`; otherwise: :math:`{\mathrm{m}-\mathrm{p}}`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{trans}=\texttt{'T'}`: :math:`{\mathrm{m}-\mathrm{p}}`; otherwise: :math:`{ \mathrm{m}-\mathrm{q} }`.

            The lower right partition of the unitary matrix :math:`X` CSD is desired.

        **jobu1** : str, length 1, optional
                If :math:`\mathrm{jobu1} = \texttt{'Y'}`, :math:`U_1` is computed;

                otherwise, :math:`U_1` is not computed.

        **jobu2** : str, length 1, optional
                If :math:`\mathrm{jobu2} = \texttt{'Y'}`, :math:`U_2` is computed;

                otherwise, :math:`U_2` is not computed.

        **jobv1t** : str, length 1, optional
                If :math:`\mathrm{jobv1t} = \texttt{'Y'}`, :math:`V_1^\mathrm{T}` is computed;

                otherwise, :math:`V_1^\mathrm{T}` is not computed.

        **jobv2t** : str, length 1, optional
                If :math:`\mathrm{jobv2t} = \texttt{'Y'}`, :math:`V_2^\mathrm{T}` is computed;

                otherwise, :math:`V_2^\mathrm{T}` is not computed.

        **trans** : str, length 1, optional
                If :math:`\mathrm{trans} = \texttt{'T'}`, :math:`X`, :math:`U_1`, :math:`U_2`, :math:`V_1^\mathrm{T}` and :math:`V_2^\mathrm{T}` are stored in row-major order;

                otherwise, :math:`X`, :math:`U_1`, :math:`U_2`, :math:`V_1^\mathrm{T}` and :math:`V_2^\mathrm{T}` are stored in column-major order.

        **signs** : str, length 1, optional
                If :math:`\mathrm{signs} = \texttt{'O'}`, the lower-left block is made nonpositive (the other convention);

                otherwise, the upper-right block is made nonpositive (the default convention).

    **Returns**
        **x11** : complex, ndarray, shape :math:`\left(:, :\right)`
            Contains details of the unitary matrix used in a simultaneous bidiagonalization process.

        **x12** : complex, ndarray, shape :math:`\left(:, :\right)`
            Contains details of the unitary matrix used in a simultaneous bidiagonalization process.

        **x21** : complex, ndarray, shape :math:`\left(:, :\right)`
            Contains details of the unitary matrix used in a simultaneous bidiagonalization process.

        **x22** : complex, ndarray, shape :math:`\left(:, :\right)`
            Contains details of the unitary matrix used in a simultaneous bidiagonalization process.

        **theta** : float, ndarray, shape :math:`\left(\min\left(\mathrm{p},{\mathrm{m}-\mathrm{p}}\right)\right)`
            The values :math:`\theta_i` for :math:`i = 1,2,\ldots,r` where :math:`r = \mathrm{min}\left(p, {m-p}, q, {m-q}\right)`. The diagonal submatrices :math:`C` and :math:`S` of :math:`\Sigma_p` are constructed from these values as

                :math:`C = \mathrm{diag}\left(\cos\left(\mathrm{theta}[0]\right), \ldots, \cos\left(\mathrm{theta}[r-1]\right)\right)` and

                :math:`S = \mathrm{diag}\left(\sin\left(\mathrm{theta}[0]\right), \ldots, \sin\left(\mathrm{theta}[r-1]\right)\right)`.

        **u1** : None or complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobu1} = \texttt{'Y'}`, :math:`\mathrm{u1}` contains the :math:`p\times p` unitary matrix :math:`U_1`.

        **u2** : None or complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobu2} = \texttt{'Y'}`, :math:`\mathrm{u2}` contains the :math:`m-p\times m-p` unitary matrix :math:`U_2`.

        **v1t** : None or complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobv1t} = \texttt{'Y'}`, :math:`\mathrm{v1t}` contains the :math:`q\times q` unitary matrix :math:`V_1^H`.

        **v2t** : None or complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobv2t} = \texttt{'Y'}`, :math:`\mathrm{v2t}` contains the :math:`m-q\times m-q` unitary matrix :math:`V_2^H`.

    .. _f08rn-py2-py-errors:

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

                Constraint: :math:`\mathrm{m}\geq 0`.

            (`errno` :math:`-8`)
                On entry, error in parameter :math:`\mathrm{p}`.

                Constraint: :math:`0\leq \mathrm{p}\leq \mathrm{m}`.

            (`errno` :math:`-9`)
                On entry, error in parameter :math:`\mathrm{q}`.

                Constraint: :math:`0\leq \mathrm{q}\leq \mathrm{m}`.

            (`errno` :math:`i > 0`)
                The Jacobi-type procedure failed to converge during an internal reduction to bidiagonal-block form. The process requires convergence to :math:`\mathrm{min}\left(\mathrm{p}, {\mathrm{m}-\mathrm{p}}, \mathrm{q}, {\mathrm{m}-\mathrm{q}}\right)` values, the value of :math:`\textit{errno}` gives the number of converged values.

    .. _f08rn-py2-py-notes:

    **Notes**
        The :math:`m\times m` unitary matrix :math:`X` is partitioned as

        .. math::
            X = \begin{pmatrix}X_{{11}}&X_{{12}}\\X_{{21}}&X_{{22}}\end{pmatrix}

        where :math:`X_{{11}}` is a :math:`p\times q` submatrix and the dimensions of the other submatrices :math:`X_{{12}}`, :math:`X_{{21}}` and :math:`X_{{22}}` are such that :math:`X` remains :math:`m\times m`.

        The CS decomposition of :math:`X` is :math:`X = U\Sigma_pV^\mathrm{T}` where :math:`U`, :math:`V` and :math:`\Sigma_p` are :math:`m\times m` matrices, such that

        .. math::
            U = \begin{pmatrix}U_1&0\\0&U_2\end{pmatrix}

        is a unitary matrix containing the :math:`p\times p` unitary matrix :math:`U_1` and the :math:`\left(m-p\right)\times \left(m-p\right)` unitary matrix :math:`U_2`;

        .. math::
            V = \begin{pmatrix}V_1&0\\0&V_2\end{pmatrix}

        is a unitary matrix containing the :math:`q\times q` unitary matrix :math:`V_1` and the :math:`\left(m-q\right)\times \left(m-q\right)` unitary matrix :math:`V_2`; and

        .. math::
            \Sigma_p = \begin{pmatrix}I_{{11}}&&0&&0&0\\&C&0&0&{-S}&\\0&0&&0&&{-I}_{{12}}\\&0&0&I_{{22}}&&0\\0&S&&&C&0\\0&&I_{{21}}&0&0&\end{pmatrix}

        contains the :math:`r\times r` non-negative diagonal submatrices :math:`C` and :math:`S` satisfying :math:`C^2+S^2 = I`, where :math:`r = \mathrm{min}\left(p, {m-p}, q, {m-q}\right)` and the top left partition is :math:`p\times q`.

        The identity matrix :math:`I_{{11}}` is of order :math:`\mathrm{min}\left(p, q\right)-r` and vanishes if :math:`\mathrm{min}\left(p, q\right) = r`.

        The identity matrix :math:`I_{{12}}` is of order :math:`\mathrm{min}\left(p, {m-q}\right)-r` and vanishes if :math:`\mathrm{min}\left(p, {m-q}\right) = r`.

        The identity matrix :math:`I_{{21}}` is of order :math:`\mathrm{min}\left({m-p}, q\right)-r` and vanishes if :math:`\mathrm{min}\left({m-p}, q\right) = r`.

        The identity matrix :math:`I_{{22}}` is of order :math:`\mathrm{min}\left({m-p}, {m-q}\right)-r` and vanishes if :math:`\mathrm{min}\left({m-p}, {m-q}\right) = r`.

        In each of the four cases :math:`r = p,q{,m-p},{m-q}` at least two of the identity matrices vanish.

        The indicated zeros represent augmentations by additional rows or columns (but not both) to the square diagonal matrices formed by :math:`I_{{ij}}` and :math:`C` or :math:`S`.

        :math:`\Sigma_p` does not need to be stored in full; it is sufficient to return only the values :math:`\theta_i` for :math:`i = 1,2,\ldots,r` where :math:`C_{{ii}} = \cos\left(\theta_i\right)` and :math:`S_{{ii}} = \sin\left(\theta_i\right)`.

        The algorithm used to perform the complete :math:`CS` decomposition is described fully in Sutton (2009) including discussions of the stability and accuracy of the algorithm.

    .. _f08rn-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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, 2012, `Matrix Computations`, (4th Edition), Johns Hopkins University Press, Baltimore

        Sutton, B D, 2009, `Computing the complete` :math:`CS` `decomposition`, Numerical Algorithms (Volume 50) (1017--1398), Springer US, 33--65, https://dx.doi.org/10.1007/s11075-008-9215-6
    """
    raise NotImplementedError

def dsygv(itype, jobz, uplo, a, b):
    r"""
    ``dsygv`` computes all the eigenvalues and, optionally, the eigenvectors of a real generalized symmetric-definite eigenproblem, of the form

    .. math::
        Az = \lambda Bz\text{, }\quad ABz = \lambda z\quad \text{ or }\quad BAz = \lambda z\text{,}

    where :math:`A` and :math:`B` are symmetric and :math:`B` is also positive definite.

    .. _f08sa-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08saf.html

    .. _f08sa-py2-py-parameters:

    **Parameters**
        **itype** : int
            Specifies the problem type to be solved.

            :math:`\mathrm{itype} = 1`

                :math:`Az = \lambda Bz`.

            :math:`\mathrm{itype} = 2`

                :math:`ABz = \lambda z`.

            :math:`\mathrm{itype} = 3`

                :math:`BAz = \lambda z`.

        **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 triangles of :math:`A` and :math:`B` are stored.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangles of :math:`A` and :math:`B` are stored.

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

        **b** : float, array-like, shape :math:`\left(n, n\right)`
            The :math:`n\times n` symmetric positive definite matrix :math:`B`.

    **Returns**
        **a** : float, ndarray, shape :math:`\left(n, n\right)`
            If :math:`\mathrm{jobz} = \texttt{'V'}`, :math:`\mathrm{a}` contains the matrix :math:`Z` of eigenvectors. The eigenvectors are normalized as follows:

                if :math:`\mathrm{itype} = 1` or :math:`2`, :math:`Z^\mathrm{T}BZ = I`;

                if :math:`\mathrm{itype} = 3`, :math:`Z^\mathrm{T}B^{-1}Z = I`.

            If :math:`\mathrm{jobz} = \texttt{'N'}`, the upper triangle (if :math:`\mathrm{uplo} = \texttt{'U'}`) or the lower triangle (if :math:`\mathrm{uplo} = \texttt{'L'}`) of :math:`\mathrm{a}`, including the diagonal, is overwritten.

        **b** : float, ndarray, shape :math:`\left(n, n\right)`
            If the function exits successfully or :math:`\mathrm{errno}` = 1 ... :math:`\mathrm{n}`, the part of :math:`\mathrm{b}` containing the matrix is overwritten by the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`B = U^\mathrm{T}U` or :math:`B = LL^\mathrm{T}`.

        **w** : float, ndarray, shape :math:`\left(n\right)`
            The eigenvalues in ascending order.

    .. _f08sa-py2-py-errors:

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

                Constraint: :math:`\mathrm{itype} = 1`, :math:`2` or :math:`3`.

            (`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{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:`i \leq n`)
                The algorithm failed to converge; :math:`\langle\mathit{\boldsymbol{value}}\rangle` off-diagonal elements of an intermediate tridiagonal form did not converge to zero.

            (`errno` :math:`i > n`)
                If :math:`\textit{errno} = n+\langle\mathit{\boldsymbol{value}}\rangle`, for :math:`1\leq \langle\mathit{\boldsymbol{value}}\rangle\leq n`, then the leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`B` is not positive definite. The factorization of :math:`B` could not be completed and no eigenvalues or eigenvectors were computed.

    .. _f08sa-py2-py-notes:

    **Notes**
        ``dsygv`` first performs a Cholesky factorization of the matrix :math:`B` as :math:`B = U^\mathrm{T}U`, when :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`B = LL^\mathrm{T}`, when :math:`\mathrm{uplo} = \texttt{'L'}`.
        The generalized problem is then reduced to a standard symmetric eigenvalue problem

        .. math::
            Cx = \lambda x\text{,}

        which is solved for the eigenvalues and, optionally, the eigenvectors; the eigenvectors are then backtransformed to give the eigenvectors of the original problem.

        For the problem :math:`Az = \lambda Bz`, the eigenvectors are normalized so that the matrix of eigenvectors, :math:`z`, satisfies

        .. math::
            Z^\mathrm{T}AZ = \Lambda \quad \text{ and }\quad Z^\mathrm{T}BZ = I\text{,}

        where :math:`\Lambda` is the diagonal matrix whose diagonal elements are the eigenvalues.
        For the problem :math:`ABz = \lambda z` we correspondingly have

        .. math::
            Z^{-1}AZ^{-\mathrm{T}} = \Lambda \quad \text{ and }\quad Z^\mathrm{T}BZ = I\text{,}

        and for :math:`BAz = \lambda z` we have

        .. math::
            Z^\mathrm{T}AZ = \Lambda \quad \text{ and }\quad Z^\mathrm{T}B^{-1}Z = I\text{.}

    .. _f08sa-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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 dsygvx(itype, jobz, erange, uplo, a, b, vl, vu, il, iu, abstol):
    r"""
    ``dsygvx`` computes selected eigenvalues and, optionally, eigenvectors of a real generalized symmetric-definite eigenproblem, of the form

    .. math::
        Az = \lambda Bz\text{, }\quad ABz = \lambda z\quad \text{ or }\quad BAz = \lambda z\text{,}

    where :math:`A` and :math:`B` are symmetric and :math:`B` is also positive definite.
    Eigenvalues and eigenvectors can be selected by specifying either a range of values or a range of indices for the desired eigenvalues.

    .. _f08sb-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08sbf.html

    .. _f08sb-py2-py-parameters:

    **Parameters**
        **itype** : int
            Specifies the problem type to be solved.

            :math:`\mathrm{itype} = 1`

                :math:`Az = \lambda Bz`.

            :math:`\mathrm{itype} = 2`

                :math:`ABz = \lambda z`.

            :math:`\mathrm{itype} = 3`

                :math:`BAz = \lambda z`.

        **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 triangles of :math:`A` and :math:`B` are stored.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangles of :math:`A` and :math:`B` are stored.

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

        **b** : float, array-like, shape :math:`\left(n, n\right)`
            The :math:`n\times n` symmetric matrix :math:`B`.

        **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:`C` 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}` = 1 ... :math:`\mathrm{n}`, 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.

        **b** : float, ndarray, shape :math:`\left(n, n\right)`
            The triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`B = U^\mathrm{T}U` or :math:`B = LL^\mathrm{T}`.

        **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]`. The eigenvectors are normalized as follows:

                    if :math:`\mathrm{itype} = 1` or :math:`2`, :math:`Z^\mathrm{T}BZ = I`;

                    if :math:`\mathrm{itype} = 3`, :math:`Z^\mathrm{T}B^{-1}Z = I`;

                if an eigenvector fails to converge (:math:`\mathrm{errno}` = 1 ... :math:`\mathrm{n}`), 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}` = 1 ... :math:`\mathrm{n}`, the first :math:`\textit{errno}` elements of :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.

    .. _f08sb-py2-py-errors:

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

                Constraint: :math:`\mathrm{itype} = 1`, :math:`2` or :math:`3`.

            (`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:`\mathrm{uplo}`.

                Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.

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

                Constraint: :math:`n\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}`.

            (`errno` :math:`i \leq n`)
                The algorithm failed to converge; :math:`\langle\mathit{\boldsymbol{value}}\rangle` eigenvectors failed to converge.

            (`errno` :math:`i > n`)
                If :math:`\textit{errno} = n+\langle\mathit{\boldsymbol{value}}\rangle`, for :math:`1\leq \langle\mathit{\boldsymbol{value}}\rangle\leq n`, then the leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`B` is not positive definite. The factorization of :math:`B` could not be completed and no eigenvalues or eigenvectors were computed.

    .. _f08sb-py2-py-notes:

    **Notes**
        ``dsygvx`` first performs a Cholesky factorization of the matrix :math:`B` as :math:`B = U^\mathrm{T}U`, when :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`B = LL^\mathrm{T}`, when :math:`\mathrm{uplo} = \texttt{'L'}`.
        The generalized problem is then reduced to a standard symmetric eigenvalue problem

        .. math::
            Cx = \lambda x\text{,}

        which is solved for the desired eigenvalues and eigenvectors; the eigenvectors are then backtransformed to give the eigenvectors of the original problem.

        For the problem :math:`Az = \lambda Bz`, the eigenvectors are normalized so that the matrix of eigenvectors, :math:`Z`, satisfies

        .. math::
            Z^\mathrm{T}AZ = \Lambda \quad \text{ and }\quad Z^\mathrm{T}BZ = I\text{,}

        where :math:`\Lambda` is the diagonal matrix whose diagonal elements are the eigenvalues.
        For the problem :math:`ABz = \lambda z` we correspondingly have

        .. math::
            Z^{-1}AZ^{-\mathrm{T}} = \Lambda \quad \text{ and }\quad Z^\mathrm{T}BZ = I\text{,}

        and for :math:`BAz = \lambda z` we have

        .. math::
            Z^\mathrm{T}AZ = \Lambda \quad \text{ and }\quad Z^\mathrm{T}B^{-1}Z = I\text{.}

    .. _f08sb-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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 dsygvd(itype, jobz, uplo, a, b):
    r"""
    ``dsygvd`` computes all the eigenvalues and, optionally, the eigenvectors of a real generalized symmetric-definite eigenproblem, of the form

    .. math::
        Az = \lambda Bz\text{, }\quad ABz = \lambda z\quad \text{ or }\quad BAz = \lambda z\text{,}

    where :math:`A` and :math:`B` are symmetric and :math:`B` is also positive definite.
    If eigenvectors are desired, it uses a divide-and-conquer algorithm.

    .. _f08sc-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08scf.html

    .. _f08sc-py2-py-parameters:

    **Parameters**
        **itype** : int
            Specifies the problem type to be solved.

            :math:`\mathrm{itype} = 1`

                :math:`Az = \lambda Bz`.

            :math:`\mathrm{itype} = 2`

                :math:`ABz = \lambda z`.

            :math:`\mathrm{itype} = 3`

                :math:`BAz = \lambda z`.

        **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 triangles of :math:`A` and :math:`B` are stored.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangles of :math:`A` and :math:`B` are stored.

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

        **b** : float, array-like, shape :math:`\left(n, n\right)`
            The :math:`n\times n` symmetric matrix :math:`B`.

    **Returns**
        **a** : float, ndarray, shape :math:`\left(n, n\right)`
            If :math:`\mathrm{jobz} = \texttt{'V'}`, :math:`\mathrm{a}` contains the matrix :math:`Z` of eigenvectors. The eigenvectors are normalized as follows:

                if :math:`\mathrm{itype} = 1` or :math:`2`, :math:`Z^\mathrm{T}BZ = I`;

                if :math:`\mathrm{itype} = 3`, :math:`Z^\mathrm{T}B^{-1}Z = I`.

            If :math:`\mathrm{jobz} = \texttt{'N'}`, the upper triangle (if :math:`\mathrm{uplo} = \texttt{'U'}`) or the lower triangle (if :math:`\mathrm{uplo} = \texttt{'L'}`) of :math:`\mathrm{a}`, including the diagonal, is overwritten.

        **b** : float, ndarray, shape :math:`\left(n, n\right)`
            The triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`B = U^\mathrm{T}U` or :math:`B = LL^\mathrm{T}`.

        **w** : float, ndarray, shape :math:`\left(n\right)`
            The eigenvalues in ascending order.

    .. _f08sc-py2-py-errors:

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

                Constraint: :math:`\mathrm{itype} = 1`, :math:`2` or :math:`3`.

            (`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{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:`i \leq n`)
                The algorithm failed to converge; :math:`\langle\mathit{\boldsymbol{value}}\rangle` off-diagonal elements of an intermediate tridiagonal form did not converge to zero.

            (`errno` :math:`i > n`)
                If :math:`\textit{errno} = n+\langle\mathit{\boldsymbol{value}}\rangle`, for :math:`1\leq \langle\mathit{\boldsymbol{value}}\rangle\leq n`, then the leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`B` is not positive definite. The factorization of :math:`B` could not be completed and no eigenvalues or eigenvectors were computed.

    .. _f08sc-py2-py-notes:

    **Notes**
        ``dsygvd`` first performs a Cholesky factorization of the matrix :math:`B` as :math:`B = U^\mathrm{T}U`, when :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`B = LL^\mathrm{T}`, when :math:`\mathrm{uplo} = \texttt{'L'}`.
        The generalized problem is then reduced to a standard symmetric eigenvalue problem

        .. math::
            Cx = \lambda x\text{,}

        which is solved for the eigenvalues and, optionally, the eigenvectors; the eigenvectors are then backtransformed to give the eigenvectors of the original problem.

        For the problem :math:`Az = \lambda Bz`, the eigenvectors are normalized so that the matrix of eigenvectors, :math:`z`, satisfies

        .. math::
            Z^\mathrm{T}AZ = \Lambda \quad \text{ and }\quad Z^\mathrm{T}BZ = I\text{,}

        where :math:`\Lambda` is the diagonal matrix whose diagonal elements are the eigenvalues.
        For the problem :math:`ABz = \lambda z` we correspondingly have

        .. math::
            Z^{-1}AZ^{-\mathrm{T}} = \Lambda \quad \text{ and }\quad Z^\mathrm{T}BZ = I\text{,}

        and for :math:`BAz = \lambda z` we have

        .. math::
            Z^\mathrm{T}AZ = \Lambda \quad \text{ and }\quad Z^\mathrm{T}B^{-1}Z = I\text{.}

    .. _f08sc-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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 dsygst(itype, uplo, a, b):
    r"""
    ``dsygst`` reduces a real symmetric-definite generalized eigenproblem :math:`Az = \lambda Bz`, :math:`ABz = \lambda z` or :math:`BAz = \lambda z` to the standard form :math:`Cy = \lambda y`, where :math:`A` is a real symmetric matrix and :math:`B` has been factorized by :meth:`lapacklin.dpotrf <naginterfaces.library.lapacklin.dpotrf>`.

    .. _f08se-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08sef.html

    .. _f08se-py2-py-parameters:

    **Parameters**
        **itype** : int
            Indicates how the standard form is computed.

            :math:`\mathrm{itype} = 1`

                    if :math:`\mathrm{uplo} = \texttt{'U'}`, :math:`C = U^{-\mathrm{T}}AU^{-1}`;

                    if :math:`\mathrm{uplo} = \texttt{'L'}`, :math:`C = L^{-1}AL^{-\mathrm{T}}`.

            :math:`\mathrm{itype} = 2` or :math:`3`

                    if :math:`\mathrm{uplo} = \texttt{'U'}`, :math:`C = UAU^\mathrm{T}`;

                    if :math:`\mathrm{uplo} = \texttt{'L'}`, :math:`C = L^\mathrm{T}AL`.

        **uplo** : str, length 1
            Indicates whether the upper or lower triangular part of :math:`A` is stored and how :math:`B` has been factorized.

            :math:`\mathrm{uplo} = \texttt{'U'}`

                The upper triangular part of :math:`A` is stored and :math:`B = U^\mathrm{T}U`.

            :math:`\mathrm{uplo} = \texttt{'L'}`

                The lower triangular part of :math:`A` is stored and :math:`B = LL^\mathrm{T}`.

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

        **b** : float, array-like, shape :math:`\left(n, n\right)`
            The Cholesky factor of :math:`B` as specified by :math:`\textit{uplo}` and returned by :meth:`lapacklin.dpotrf <naginterfaces.library.lapacklin.dpotrf>`.

    **Returns**
        **a** : float, ndarray, shape :math:`\left(n, n\right)`
            The upper or lower triangle of :math:`\mathrm{a}` is overwritten by the corresponding upper or lower triangle of :math:`C` as specified by :math:`\mathrm{itype}` and :math:`\mathrm{uplo}`.

    .. _f08se-py2-py-errors:

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

                Constraint: :math:`\mathrm{itype} = 1`, :math:`2` or :math:`3`.

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

    .. _f08se-py2-py-notes:

    **Notes**
        To reduce the real symmetric-definite generalized eigenproblem :math:`Az = \lambda Bz`, :math:`ABz = \lambda z` or :math:`BAz = \lambda z` to the standard form :math:`Cy = \lambda y`, ``dsygst`` must be preceded by a call to :meth:`lapacklin.dpotrf <naginterfaces.library.lapacklin.dpotrf>` which computes the Cholesky factorization of :math:`B`; :math:`B` must be positive definite.

        The different problem types are specified by the argument :math:`\mathrm{itype}`, as indicated in the table below.
        The table shows how :math:`C` is computed by the function, and also how the eigenvectors :math:`z` of the original problem can be recovered from the eigenvectors of the standard form.

        +----------------------+-----------------------+---------------------+-------------------------------------------+-------------------------------------------------------------+----------------------------------------+
        |:math:`\mathrm{itype}`|Problem                |:math:`\mathrm{uplo}`|:math:`B`                                  |:math:`C`                                                    |:math:`z`                               |
        +======================+=======================+=====================+===========================================+=============================================================+========================================+
        |:math:`1`             |:math:`Az = \lambda Bz`|'U' 'L'              |:math:`U^\mathrm{T}U` :math:`LL^\mathrm{T}`|:math:`U^{-\mathrm{T}}AU^{-1}` :math:`L^{-1}AL^{-\mathrm{T}}`|:math:`U^{-1}y` :math:`L^{-\mathrm{T}}y`|
        +----------------------+-----------------------+---------------------+-------------------------------------------+-------------------------------------------------------------+----------------------------------------+
        |:math:`2`             |:math:`ABz = \lambda z`|'U' 'L'              |:math:`U^\mathrm{T}U` :math:`LL^\mathrm{T}`|:math:`UAU^\mathrm{T}` :math:`L^\mathrm{T}AL`                |:math:`U^{-1}y` :math:`L^{-\mathrm{T}}y`|
        +----------------------+-----------------------+---------------------+-------------------------------------------+-------------------------------------------------------------+----------------------------------------+
        |:math:`3`             |:math:`BAz = \lambda z`|'U' 'L'              |:math:`U^\mathrm{T}U` :math:`LL^\mathrm{T}`|:math:`UAU^\mathrm{T}` :math:`L^\mathrm{T}AL`                |:math:`U^\mathrm{T}y` :math:`Ly`        |
        +----------------------+-----------------------+---------------------+-------------------------------------------+-------------------------------------------------------------+----------------------------------------+

    .. _f08se-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 zhegv(itype, jobz, uplo, a, b):
    r"""
    ``zhegv`` computes all the eigenvalues and, optionally, the eigenvectors of a complex generalized Hermitian-definite eigenproblem, of the form

    .. math::
        Az = \lambda Bz\text{, }\quad ABz = \lambda z\quad \text{ or }\quad BAz = \lambda z\text{,}

    where :math:`A` and :math:`B` are Hermitian and :math:`B` is also positive definite.

    .. _f08sn-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08snf.html

    .. _f08sn-py2-py-parameters:

    **Parameters**
        **itype** : int
            Specifies the problem type to be solved.

            :math:`\mathrm{itype} = 1`

                :math:`Az = \lambda Bz`.

            :math:`\mathrm{itype} = 2`

                :math:`ABz = \lambda z`.

            :math:`\mathrm{itype} = 3`

                :math:`BAz = \lambda z`.

        **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 triangles of :math:`A` and :math:`B` are stored.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangles of :math:`A` and :math:`B` are stored.

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

        **b** : complex, array-like, shape :math:`\left(n, n\right)`
            The :math:`n\times n` Hermitian positive definite matrix :math:`B`.

    **Returns**
        **a** : complex, ndarray, shape :math:`\left(n, n\right)`
            If :math:`\mathrm{jobz} = \texttt{'V'}`, :math:`\mathrm{a}` contains the matrix :math:`Z` of eigenvectors. The eigenvectors are normalized as follows:

                if :math:`\mathrm{itype} = 1` or :math:`2`, :math:`Z^\mathrm{H}BZ = I`;

                if :math:`\mathrm{itype} = 3`, :math:`Z^\mathrm{H}B^{-1}Z = I`.

            If :math:`\mathrm{jobz} = \texttt{'N'}`, the upper triangle (if :math:`\mathrm{uplo} = \texttt{'U'}`) or the lower triangle (if :math:`\mathrm{uplo} = \texttt{'L'}`) of :math:`\mathrm{a}`, including the diagonal, is overwritten.

        **b** : complex, ndarray, shape :math:`\left(n, n\right)`
            If the function exits successfully or :math:`\mathrm{errno}` = 1 ... :math:`\mathrm{n}`, the part of :math:`\mathrm{b}` containing the matrix is overwritten by the triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`B = U^\mathrm{H}U` or :math:`B = LL^\mathrm{H}`.

        **w** : float, ndarray, shape :math:`\left(n\right)`
            The eigenvalues in ascending order.

    .. _f08sn-py2-py-errors:

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

                Constraint: :math:`\mathrm{itype} = 1`, :math:`2` or :math:`3`.

            (`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{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:`i \leq n`)
                The algorithm failed to converge; :math:`\langle\mathit{\boldsymbol{value}}\rangle` off-diagonal elements of an intermediate tridiagonal form did not converge to zero.

            (`errno` :math:`i > n`)
                If :math:`\textit{errno} = n+\langle\mathit{\boldsymbol{value}}\rangle`, for :math:`1\leq \langle\mathit{\boldsymbol{value}}\rangle\leq n`, then the leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`B` is not positive definite. The factorization of :math:`B` could not be completed and no eigenvalues or eigenvectors were computed.

    .. _f08sn-py2-py-notes:

    **Notes**
        ``zhegv`` first performs a Cholesky factorization of the matrix :math:`B` as :math:`B = U^\mathrm{H}U`, when :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`B = LL^\mathrm{H}`, when :math:`\mathrm{uplo} = \texttt{'L'}`.
        The generalized problem is then reduced to a standard symmetric eigenvalue problem

        .. math::
            Cx = \lambda x\text{,}

        which is solved for the eigenvalues and, optionally, the eigenvectors; the eigenvectors are then backtransformed to give the eigenvectors of the original problem.

        For the problem :math:`Az = \lambda Bz`, the eigenvectors are normalized so that the matrix of eigenvectors, :math:`z`, satisfies

        .. math::
            Z^\mathrm{H}AZ = \Lambda \quad \text{ and }\quad Z^\mathrm{H}BZ = I\text{,}

        where :math:`\Lambda` is the diagonal matrix whose diagonal elements are the eigenvalues.
        For the problem :math:`ABz = \lambda z` we correspondingly have

        .. math::
            Z^{-1}AZ^{-\mathrm{H}} = \Lambda \quad \text{ and }\quad Z^\mathrm{H}BZ = I\text{,}

        and for :math:`BAz = \lambda z` we have

        .. math::
            Z^\mathrm{H}AZ = \Lambda \quad \text{ and }\quad Z^\mathrm{H}B^{-1}Z = I\text{.}

    .. _f08sn-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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 zhegvx(itype, jobz, erange, uplo, a, b, vl, vu, il, iu, abstol):
    r"""
    ``zhegvx`` computes selected eigenvalues and, optionally, eigenvectors of a complex generalized Hermitian-definite eigenproblem, of the form

    .. math::
        Az = \lambda Bz\text{, }\quad ABz = \lambda z\quad \text{ or }\quad BAz = \lambda z\text{,}

    where :math:`A` and :math:`B` are Hermitian and :math:`B` is also positive definite.
    Eigenvalues and eigenvectors can be selected by specifying either a range of values or a range of indices for the desired eigenvalues.

    .. _f08sp-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08spf.html

    .. _f08sp-py2-py-parameters:

    **Parameters**
        **itype** : int
            Specifies the problem type to be solved.

            :math:`\mathrm{itype} = 1`

                :math:`Az = \lambda Bz`.

            :math:`\mathrm{itype} = 2`

                :math:`ABz = \lambda z`.

            :math:`\mathrm{itype} = 3`

                :math:`BAz = \lambda z`.

        **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 triangles of :math:`A` and :math:`B` are stored.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangles of :math:`A` and :math:`B` are stored.

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

        **b** : complex, array-like, shape :math:`\left(n, n\right)`
            The :math:`n\times n` Hermitian matrix :math:`B`.

        **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:`C` 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}` = 1 ... :math:`\mathrm{n}`, 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.

        **b** : complex, ndarray, shape :math:`\left(n, n\right)`
            The triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`B = U^\mathrm{H}U` or :math:`B = LL^\mathrm{H}`.

        **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]`. The eigenvectors are normalized as follows:

                    if :math:`\mathrm{itype} = 1` or :math:`2`, :math:`Z^\mathrm{H}BZ = I`;

                    if :math:`\mathrm{itype} = 3`, :math:`Z^\mathrm{H}B^{-1}Z = I`;

                if an eigenvector fails to converge (:math:`\mathrm{errno}` = 1 ... :math:`\mathrm{n}`), 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}` = 1 ... :math:`\mathrm{n}`, the first :math:`\textit{errno}` elements of :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.

    .. _f08sp-py2-py-errors:

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

                Constraint: :math:`\mathrm{itype} = 1`, :math:`2` or :math:`3`.

            (`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:`\mathrm{uplo}`.

                Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.

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

                Constraint: :math:`n\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}`.

            (`errno` :math:`i > n`)
                If :math:`\textit{errno} = n+\langle\mathit{\boldsymbol{value}}\rangle`, for :math:`1\leq \langle\mathit{\boldsymbol{value}}\rangle\leq n`, then the leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`B` is not positive definite. The factorization of :math:`B` could not be completed and no eigenvalues or eigenvectors were computed.

    **Warns**
        **NagAlgorithmicWarning**
            (`errno` :math:`i \leq n`)
                The algorithm failed to converge; :math:`\langle\mathit{\boldsymbol{value}}\rangle` eigenvectors failed to converge.

    .. _f08sp-py2-py-notes:

    **Notes**
        ``zhegvx`` first performs a Cholesky factorization of the matrix :math:`B` as :math:`B = U^\mathrm{H}U`, when :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`B = LL^\mathrm{H}`, when :math:`\mathrm{uplo} = \texttt{'L'}`.
        The generalized problem is then reduced to a standard symmetric eigenvalue problem

        .. math::
            Cx = \lambda x\text{,}

        which is solved for the desired eigenvalues and eigenvectors; the eigenvectors are then backtransformed to give the eigenvectors of the original problem.

        For the problem :math:`Az = \lambda Bz`, the eigenvectors are normalized so that the matrix of eigenvectors, :math:`Z`, satisfies

        .. math::
            Z^\mathrm{H}AZ = \Lambda \quad \text{ and }\quad Z^\mathrm{H}BZ = I\text{,}

        where :math:`\Lambda` is the diagonal matrix whose diagonal elements are the eigenvalues.
        For the problem :math:`ABz = \lambda z` we correspondingly have

        .. math::
            Z^{-1}AZ^{-\mathrm{H}} = \Lambda \quad \text{ and }\quad Z^\mathrm{H}BZ = I\text{,}

        and for :math:`BAz = \lambda z` we have

        .. math::
            Z^\mathrm{H}AZ = \Lambda \quad \text{ and }\quad Z^\mathrm{H}B^{-1}Z = I\text{.}

    .. _f08sp-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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 zhegvd(itype, jobz, uplo, a, b):
    r"""
    ``zhegvd`` computes all the eigenvalues and, optionally, the eigenvectors of a complex generalized Hermitian-definite eigenproblem, of the form

    .. math::
        Az = \lambda Bz\text{, }\quad ABz = \lambda z\quad \text{ or }\quad BAz = \lambda z\text{,}

    where :math:`A` and :math:`B` are Hermitian and :math:`B` is also positive definite.
    If eigenvectors are desired, it uses a divide-and-conquer algorithm.

    .. _f08sq-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08sqf.html

    .. _f08sq-py2-py-parameters:

    **Parameters**
        **itype** : int
            Specifies the problem type to be solved.

            :math:`\mathrm{itype} = 1`

                :math:`Az = \lambda Bz`.

            :math:`\mathrm{itype} = 2`

                :math:`ABz = \lambda z`.

            :math:`\mathrm{itype} = 3`

                :math:`BAz = \lambda z`.

        **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 triangles of :math:`A` and :math:`B` are stored.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangles of :math:`A` and :math:`B` are stored.

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

        **b** : complex, array-like, shape :math:`\left(n, n\right)`
            The :math:`n\times n` Hermitian matrix :math:`B`.

    **Returns**
        **a** : complex, ndarray, shape :math:`\left(n, n\right)`
            If :math:`\mathrm{jobz} = \texttt{'V'}`, :math:`\mathrm{a}` contains the matrix :math:`Z` of eigenvectors. The eigenvectors are normalized as follows:

                if :math:`\mathrm{itype} = 1` or :math:`2`, :math:`Z^\mathrm{H}BZ = I`;

                if :math:`\mathrm{itype} = 3`, :math:`Z^\mathrm{H}B^{-1}Z = I`.

            If :math:`\mathrm{jobz} = \texttt{'N'}`, the upper triangle (if :math:`\mathrm{uplo} = \texttt{'U'}`) or the lower triangle (if :math:`\mathrm{uplo} = \texttt{'L'}`) of :math:`\mathrm{a}`, including the diagonal, is overwritten.

        **b** : complex, ndarray, shape :math:`\left(n, n\right)`
            The triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`B = U^\mathrm{H}U` or :math:`B = LL^\mathrm{H}`.

        **w** : float, ndarray, shape :math:`\left(n\right)`
            The eigenvalues in ascending order.

    .. _f08sq-py2-py-errors:

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

                Constraint: :math:`\mathrm{itype} = 1`, :math:`2` or :math:`3`.

            (`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{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:`i \leq n`)
                The algorithm failed to converge; :math:`\langle\mathit{\boldsymbol{value}}\rangle` off-diagonal elements of an intermediate tridiagonal form did not converge to zero.

            (`errno` :math:`i > n`)
                If :math:`\textit{errno} = n+\langle\mathit{\boldsymbol{value}}\rangle`, for :math:`1\leq \langle\mathit{\boldsymbol{value}}\rangle\leq n`, then the leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`B` is not positive definite. The factorization of :math:`B` could not be completed and no eigenvalues or eigenvectors were computed.

    .. _f08sq-py2-py-notes:

    **Notes**
        ``zhegvd`` first performs a Cholesky factorization of the matrix :math:`B` as :math:`B = U^\mathrm{H}U`, when :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`B = LL^\mathrm{H}`, when :math:`\mathrm{uplo} = \texttt{'L'}`.
        The generalized problem is then reduced to a standard symmetric eigenvalue problem

        .. math::
            Cx = \lambda x\text{,}

        which is solved for the eigenvalues and, optionally, the eigenvectors; the eigenvectors are then backtransformed to give the eigenvectors of the original problem.

        For the problem :math:`Az = \lambda Bz`, the eigenvectors are normalized so that the matrix of eigenvectors, :math:`z`, satisfies

        .. math::
            Z^\mathrm{H}AZ = \Lambda \quad \text{ and }\quad Z^\mathrm{H}BZ = I\text{,}

        where :math:`\Lambda` is the diagonal matrix whose diagonal elements are the eigenvalues.
        For the problem :math:`ABz = \lambda z` we correspondingly have

        .. math::
            Z^{-1}AZ^{-\mathrm{H}} = \Lambda \quad \text{ and }\quad Z^\mathrm{H}BZ = I\text{,}

        and for :math:`BAz = \lambda z` we have

        .. math::
            Z^\mathrm{H}AZ = \Lambda \quad \text{ and }\quad Z^\mathrm{H}B^{-1}Z = I\text{.}

    .. _f08sq-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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 zhegst(itype, uplo, a, b):
    r"""
    ``zhegst`` reduces a complex Hermitian-definite generalized eigenproblem :math:`Az = \lambda Bz`, :math:`ABz = \lambda z` or :math:`BAz = \lambda z` to the standard form :math:`Cy = \lambda y`, where :math:`A` is a complex Hermitian matrix and :math:`B` has been factorized by :meth:`lapacklin.zpotrf <naginterfaces.library.lapacklin.zpotrf>`.

    .. _f08ss-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08ssf.html

    .. _f08ss-py2-py-parameters:

    **Parameters**
        **itype** : int
            Indicates how the standard form is computed.

            :math:`\mathrm{itype} = 1`

                    if :math:`\mathrm{uplo} = \texttt{'U'}`, :math:`C = U^{-\mathrm{H}}AU^{-1}`;

                    if :math:`\mathrm{uplo} = \texttt{'L'}`, :math:`C = L^{-1}AL^{-\mathrm{H}}`.

            :math:`\mathrm{itype} = 2` or :math:`3`

                    if :math:`\mathrm{uplo} = \texttt{'U'}`, :math:`C = UAU^\mathrm{H}`;

                    if :math:`\mathrm{uplo} = \texttt{'L'}`, :math:`C = L^\mathrm{H}AL`.

        **uplo** : str, length 1
            Indicates whether the upper or lower triangular part of :math:`A` is stored and how :math:`B` has been factorized.

            :math:`\mathrm{uplo} = \texttt{'U'}`

                The upper triangular part of :math:`A` is stored and :math:`B = U^\mathrm{H}U`.

            :math:`\mathrm{uplo} = \texttt{'L'}`

                The lower triangular part of :math:`A` is stored and :math:`B = LL^\mathrm{H}`.

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

        **b** : complex, array-like, shape :math:`\left(n, n\right)`
            The Cholesky factor of :math:`B` as specified by :math:`\textit{uplo}` and returned by :meth:`lapacklin.zpotrf <naginterfaces.library.lapacklin.zpotrf>`.

    **Returns**
        **a** : complex, ndarray, shape :math:`\left(n, n\right)`
            The upper or lower triangle of :math:`\mathrm{a}` is overwritten by the corresponding upper or lower triangle of :math:`C` as specified by :math:`\mathrm{itype}` and :math:`\mathrm{uplo}`.

    .. _f08ss-py2-py-errors:

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

                Constraint: :math:`\mathrm{itype} = 1`, :math:`2` or :math:`3`.

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

    .. _f08ss-py2-py-notes:

    **Notes**
        To reduce the complex Hermitian-definite generalized eigenproblem :math:`Az = \lambda Bz`, :math:`ABz = \lambda z` or :math:`BAz = \lambda z` to the standard form :math:`Cy = \lambda y`, ``zhegst`` must be preceded by a call to :meth:`lapacklin.zpotrf <naginterfaces.library.lapacklin.zpotrf>` which computes the Cholesky factorization of :math:`B`; :math:`B` must be positive definite.

        The different problem types are specified by the argument :math:`\mathrm{itype}`, as indicated in the table below.
        The table shows how :math:`C` is computed by the function, and also how the eigenvectors :math:`z` of the original problem can be recovered from the eigenvectors of the standard form.

        +----------------------+-----------------------+---------------------+-------------------------------------------+-------------------------------------------------------------+----------------------------------------+
        |:math:`\mathrm{itype}`|Problem                |:math:`\mathrm{uplo}`|:math:`B`                                  |:math:`C`                                                    |:math:`z`                               |
        +======================+=======================+=====================+===========================================+=============================================================+========================================+
        |:math:`1`             |:math:`Az = \lambda Bz`|'U' 'L'              |:math:`U^\mathrm{H}U` :math:`LL^\mathrm{H}`|:math:`U^{-\mathrm{H}}AU^{-1}` :math:`L^{-1}AL^{-\mathrm{H}}`|:math:`U^{-1}y` :math:`L^{-\mathrm{H}}y`|
        +----------------------+-----------------------+---------------------+-------------------------------------------+-------------------------------------------------------------+----------------------------------------+
        |:math:`2`             |:math:`ABz = \lambda z`|'U' 'L'              |:math:`U^\mathrm{H}U` :math:`LL^\mathrm{H}`|:math:`UAU^\mathrm{H}` :math:`L^\mathrm{H}AL`                |:math:`U^{-1}y` :math:`L^{-\mathrm{H}}y`|
        +----------------------+-----------------------+---------------------+-------------------------------------------+-------------------------------------------------------------+----------------------------------------+
        |:math:`3`             |:math:`BAz = \lambda z`|'U' 'L'              |:math:`U^\mathrm{H}U` :math:`LL^\mathrm{H}`|:math:`UAU^\mathrm{H}` :math:`L^\mathrm{H}AL`                |:math:`U^\mathrm{H}y` :math:`Ly`        |
        +----------------------+-----------------------+---------------------+-------------------------------------------+-------------------------------------------------------------+----------------------------------------+

    .. _f08ss-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 dspgv(itype, jobz, uplo, n, ap, bp):
    r"""
    ``dspgv`` computes all the eigenvalues and, optionally, all the eigenvectors of a real generalized symmetric-definite eigenproblem, of the form

    .. math::
        Az = \lambda Bz\text{, }\quad ABz = \lambda z\quad \text{ or }\quad BAz = \lambda z\text{,}

    where :math:`A` and :math:`B` are symmetric, stored in packed format, and :math:`B` is also positive definite.

    .. _f08ta-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08taf.html

    .. _f08ta-py2-py-parameters:

    **Parameters**
        **itype** : int
            Specifies the problem type to be solved.

            :math:`\mathrm{itype} = 1`

                :math:`Az = \lambda Bz`.

            :math:`\mathrm{itype} = 2`

                :math:`ABz = \lambda z`.

            :math:`\mathrm{itype} = 3`

                :math:`BAz = \lambda z`.

        **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 triangles of :math:`A` and :math:`B` are stored.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangles of :math:`A` and :math:`B` are stored.

        **n** : int
            :math:`n`, the order of the matrices :math:`A` and :math:`B`.

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

        **bp** : 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:`B`, packed by columns.

    **Returns**
        **ap** : float, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
            The contents of :math:`\mathrm{ap}` are destroyed.

        **bp** : float, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
            The triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`B = U^\mathrm{T}U` or :math:`B = LL^\mathrm{T}`, in the same storage format as :math:`B`.

        **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 matrix :math:`Z` of eigenvectors. The eigenvectors are normalized as follows:

                if :math:`\mathrm{itype} = 1` or :math:`2`, :math:`Z^\mathrm{T}BZ = I`;

                if :math:`\mathrm{itype} = 3`, :math:`Z^\mathrm{T}B^{-1}Z = I`.

            If :math:`\mathrm{jobz} = \texttt{'N'}`, :math:`\mathrm{z}` is not referenced.

    .. _f08ta-py2-py-errors:

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

                Constraint: :math:`\mathrm{itype} = 1`, :math:`2` or :math:`3`.

            (`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{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:`i \leq \mathrm{n}`)
                The algorithm failed to converge; :math:`\langle\mathit{\boldsymbol{value}}\rangle` off-diagonal elements of an intermediate tridiagonal form did not converge to zero.

            (`errno` :math:`i > \mathrm{n}`)
                If :math:`\textit{errno} = \mathrm{n}+\langle\mathit{\boldsymbol{value}}\rangle`, for :math:`1\leq \langle\mathit{\boldsymbol{value}}\rangle\leq \mathrm{n}`, then the leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`B` is not positive definite. The factorization of :math:`B` could not be completed and no eigenvalues or eigenvectors were computed.

    .. _f08ta-py2-py-notes:

    **Notes**
        ``dspgv`` first performs a Cholesky factorization of the matrix :math:`B` as :math:`B = U^\mathrm{T}U`, when :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`B = LL^\mathrm{T}`, when :math:`\mathrm{uplo} = \texttt{'L'}`.
        The generalized problem is then reduced to a standard symmetric eigenvalue problem

        .. math::
            Cx = \lambda x\text{,}

        which is solved for the eigenvalues and, optionally, the eigenvectors; the eigenvectors are then backtransformed to give the eigenvectors of the original problem.

        For the problem :math:`Az = \lambda Bz`, the eigenvectors are normalized so that the matrix of eigenvectors, :math:`Z`, satisfies

        .. math::
            Z^\mathrm{T}AZ = \Lambda \quad \text{ and }\quad Z^\mathrm{T}BZ = I\text{,}

        where :math:`\Lambda` is the diagonal matrix whose diagonal elements are the eigenvalues.
        For the problem :math:`ABz = \lambda z` we correspondingly have

        .. math::
            Z^{-1}AZ^{-\mathrm{T}} = \Lambda \quad \text{ and }\quad Z^\mathrm{T}BZ = I\text{,}

        and for :math:`BAz = \lambda z` we have

        .. math::
            Z^\mathrm{T}AZ = \Lambda \quad \text{ and }\quad Z^\mathrm{T}B^{-1}Z = I\text{.}

    .. _f08ta-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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 dspgvx(itype, jobz, erange, uplo, n, ap, bp, vl, vu, il, iu, abstol):
    r"""
    ``dspgvx`` computes selected eigenvalues and, optionally, eigenvectors of a real generalized symmetric-definite eigenproblem, of the form

    .. math::
        Az = \lambda Bz\text{, }\quad ABz = \lambda z\quad \text{ or }\quad BAz = \lambda z\text{,}

    where :math:`A` and :math:`B` are symmetric, stored in packed storage, and :math:`B` is also positive definite.
    Eigenvalues and eigenvectors can be selected by specifying either a range of values or a range of indices for the desired eigenvalues.

    .. _f08tb-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08tbf.html

    .. _f08tb-py2-py-parameters:

    **Parameters**
        **itype** : int
            Specifies the problem type to be solved.

            :math:`\mathrm{itype} = 1`

                :math:`Az = \lambda Bz`.

            :math:`\mathrm{itype} = 2`

                :math:`ABz = \lambda z`.

            :math:`\mathrm{itype} = 3`

                :math:`BAz = \lambda z`.

        **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 triangles of :math:`A` and :math:`B` are stored.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangles of :math:`A` and :math:`B` are stored.

        **n** : int
            :math:`n`, the order of the matrices :math:`A` and :math:`B`.

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

        **bp** : 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:`B`, 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:`C` 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}` = 1 ... :math:`\mathrm{n}`, 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)`
            The contents of :math:`\mathrm{ap}` are destroyed.

        **bp** : float, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
            The triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`B = U^\mathrm{T}U` or :math:`B = LL^\mathrm{T}`, in the same storage format as :math:`B`.

        **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 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]`. The eigenvectors are normalized as follows:

                    if :math:`\mathrm{itype} = 1` or :math:`2`, :math:`Z^\mathrm{T}BZ = I`;

                    if :math:`\mathrm{itype} = 3`, :math:`Z^\mathrm{T}B^{-1}Z = I`;

                if an eigenvector fails to converge (:math:`\mathrm{errno}` = 1 ... :math:`\mathrm{n}`), 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}` = 1 ... :math:`\mathrm{n}`, the first :math:`\textit{errno}` elements of :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.

    .. _f08tb-py2-py-errors:

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

                Constraint: :math:`\mathrm{itype} = 1`, :math:`2` or :math:`3`.

            (`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:`\mathrm{uplo}`.

                Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.

            (`errno` :math:`-5`)
                On entry, error in parameter :math:`\mathrm{n}`.

                Constraint: :math:`\mathrm{n}\geq 0`.

            (`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 > \mathrm{n}`)
                If :math:`\textit{errno} = \mathrm{n}+\langle\mathit{\boldsymbol{value}}\rangle`, for :math:`1\leq \langle\mathit{\boldsymbol{value}}\rangle\leq \mathrm{n}`, then the leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`B` is not positive definite. The factorization of :math:`B` could not be completed and no eigenvalues or eigenvectors were computed.

    **Warns**
        **NagAlgorithmicWarning**
            (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq \mathrm{n}\right)`)
                The algorithm failed to converge; :math:`\langle\mathit{\boldsymbol{value}}\rangle` eigenvectors did not converge. Their indices are stored in array :math:`\mathrm{jfail}`.

    .. _f08tb-py2-py-notes:

    **Notes**
        ``dspgvx`` first performs a Cholesky factorization of the matrix :math:`B` as :math:`B = U^\mathrm{T}U`, when :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`B = LL^\mathrm{T}`, when :math:`\mathrm{uplo} = \texttt{'L'}`.
        The generalized problem is then reduced to a standard symmetric eigenvalue problem

        .. math::
            Cx = \lambda x\text{,}

        which is solved for the desired eigenvalues and eigenvectors; the eigenvectors are then backtransformed to give the eigenvectors of the original problem.

        For the problem :math:`Az = \lambda Bz`, the eigenvectors are normalized so that the matrix of eigenvectors, :math:`Z`, satisfies

        .. math::
            Z^\mathrm{T}AZ = \Lambda \quad \text{ and }\quad Z^\mathrm{T}BZ = I\text{,}

        where :math:`\Lambda` is the diagonal matrix whose diagonal elements are the eigenvalues.
        For the problem :math:`ABz = \lambda z` we correspondingly have

        .. math::
            Z^{-1}AZ^{-\mathrm{T}} = \Lambda \quad \text{ and }\quad Z^\mathrm{T}BZ = I\text{,}

        and for :math:`BAz = \lambda z` we have

        .. math::
            Z^\mathrm{T}AZ = \Lambda \quad \text{ and }\quad Z^\mathrm{T}B^{-1}Z = I\text{.}

    .. _f08tb-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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 dspgvd(itype, jobz, uplo, n, ap, bp):
    r"""
    ``dspgvd`` computes all the eigenvalues and, optionally, the eigenvectors of a real generalized symmetric-definite eigenproblem, of the form

    .. math::
        Az = \lambda Bz\text{, }\quad ABz = \lambda z\quad \text{ or }\quad BAz = \lambda z\text{,}

    where :math:`A` and :math:`B` are symmetric, stored in packed format, and :math:`B` is also positive definite.
    If eigenvectors are desired, it uses a divide-and-conquer algorithm.

    .. _f08tc-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08tcf.html

    .. _f08tc-py2-py-parameters:

    **Parameters**
        **itype** : int
            Specifies the problem type to be solved.

            :math:`\mathrm{itype} = 1`

                :math:`Az = \lambda Bz`.

            :math:`\mathrm{itype} = 2`

                :math:`ABz = \lambda z`.

            :math:`\mathrm{itype} = 3`

                :math:`BAz = \lambda z`.

        **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 triangles of :math:`A` and :math:`B` are stored.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangles of :math:`A` and :math:`B` are stored.

        **n** : int
            :math:`n`, the order of the matrices :math:`A` and :math:`B`.

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

        **bp** : 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:`B`, packed by columns.

    **Returns**
        **ap** : float, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
            The contents of :math:`\mathrm{ap}` are destroyed.

        **bp** : float, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
            The triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`B = U^\mathrm{T}U` or :math:`B = LL^\mathrm{T}`, in the same storage format as :math:`B`.

        **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 matrix :math:`Z` of eigenvectors. The eigenvectors are normalized as follows:

                if :math:`\mathrm{itype} = 1` or :math:`2`, :math:`Z^\mathrm{T}BZ = I`;

                if :math:`\mathrm{itype} = 3`, :math:`Z^\mathrm{T}B^{-1}Z = I`.

            If :math:`\mathrm{jobz} = \texttt{'N'}`, :math:`\mathrm{z}` is not referenced.

    .. _f08tc-py2-py-errors:

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

                Constraint: :math:`\mathrm{itype} = 1`, :math:`2` or :math:`3`.

            (`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{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:`i \leq \mathrm{n}`)
                The algorithm failed to converge; :math:`\langle\mathit{\boldsymbol{value}}\rangle` off-diagonal elements of an intermediate tridiagonal form did not converge to zero.

            (`errno` :math:`i > \mathrm{n}`)
                If :math:`\textit{errno} = \mathrm{n}+\langle\mathit{\boldsymbol{value}}\rangle`, for :math:`1\leq \langle\mathit{\boldsymbol{value}}\rangle\leq \mathrm{n}`, then the leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`B` is not positive definite. The factorization of :math:`B` could not be completed and no eigenvalues or eigenvectors were computed.

    .. _f08tc-py2-py-notes:

    **Notes**
        ``dspgvd`` first performs a Cholesky factorization of the matrix :math:`B` as :math:`B = U^\mathrm{T}U`, when :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`B = LL^\mathrm{T}`, when :math:`\mathrm{uplo} = \texttt{'L'}`.
        The generalized problem is then reduced to a standard symmetric eigenvalue problem

        .. math::
            Cx = \lambda x\text{,}

        which is solved for the eigenvalues and, optionally, the eigenvectors; the eigenvectors are then backtransformed to give the eigenvectors of the original problem.

        For the problem :math:`Az = \lambda Bz`, the eigenvectors are normalized so that the matrix of eigenvectors, :math:`z`, satisfies

        .. math::
            Z^\mathrm{T}AZ = \Lambda \quad \text{ and }\quad Z^\mathrm{T}BZ = I\text{,}

        where :math:`\Lambda` is the diagonal matrix whose diagonal elements are the eigenvalues.
        For the problem :math:`ABz = \lambda z` we correspondingly have

        .. math::
            Z^{-1}AZ^{-\mathrm{T}} = \Lambda \quad \text{ and }\quad Z^\mathrm{T}BZ = I\text{,}

        and for :math:`BAz = \lambda z` we have

        .. math::
            Z^\mathrm{T}AZ = \Lambda \quad \text{ and }\quad Z^\mathrm{T}B^{-1}Z = I\text{.}

    .. _f08tc-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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 dspgst(itype, uplo, n, ap, bp):
    r"""
    ``dspgst`` reduces a real symmetric-definite generalized eigenproblem :math:`Az = \lambda Bz`, :math:`ABz = \lambda z` or :math:`BAz = \lambda z` to the standard form :math:`Cy = \lambda y`, where :math:`A` is a real symmetric matrix and :math:`B` has been factorized by :meth:`lapacklin.dpptrf <naginterfaces.library.lapacklin.dpptrf>`, using packed storage.

    .. _f08te-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08tef.html

    .. _f08te-py2-py-parameters:

    **Parameters**
        **itype** : int
            Indicates how the standard form is computed.

            :math:`\mathrm{itype} = 1`

                    if :math:`\mathrm{uplo} = \texttt{'U'}`, :math:`C = U^{-\mathrm{T}}AU^{-1}`;

                    if :math:`\mathrm{uplo} = \texttt{'L'}`, :math:`C = L^{-1}AL^{-\mathrm{T}}`.

            :math:`\mathrm{itype} = 2` or :math:`3`

                    if :math:`\mathrm{uplo} = \texttt{'U'}`, :math:`C = UAU^\mathrm{T}`;

                    if :math:`\mathrm{uplo} = \texttt{'L'}`, :math:`C = L^\mathrm{T}AL`.

        **uplo** : str, length 1
            Indicates whether the upper or lower triangular part of :math:`A` is stored and how :math:`B` has been factorized.

            :math:`\mathrm{uplo} = \texttt{'U'}`

                The upper triangular part of :math:`A` is stored and :math:`B = U^\mathrm{T}U`.

            :math:`\mathrm{uplo} = \texttt{'L'}`

                The lower triangular part of :math:`A` is stored and :math:`B = LL^\mathrm{T}`.

        **n** : int
            :math:`n`, the order of the matrices :math:`A` and :math:`B`.

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

        **bp** : float, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
            The Cholesky factor of :math:`B` as specified by :math:`\mathrm{uplo}` and returned by :meth:`lapacklin.dpptrf <naginterfaces.library.lapacklin.dpptrf>`.

    **Returns**
        **ap** : float, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
            The upper or lower triangle of :math:`\mathrm{ap}` is overwritten by the corresponding upper or lower triangle of :math:`C` as specified by :math:`\mathrm{itype}` and :math:`\mathrm{uplo}`, using the same packed storage format as described above.

    .. _f08te-py2-py-errors:

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

                Constraint: :math:`\mathrm{itype} = 1`, :math:`2` or :math:`3`.

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

    .. _f08te-py2-py-notes:

    **Notes**
        To reduce the real symmetric-definite generalized eigenproblem :math:`Az = \lambda Bz`, :math:`ABz = \lambda z` or :math:`BAz = \lambda z` to the standard form :math:`Cy = \lambda y` using packed storage, ``dspgst`` must be preceded by a call to :meth:`lapacklin.dpptrf <naginterfaces.library.lapacklin.dpptrf>` which computes the Cholesky factorization of :math:`B`; :math:`B` must be positive definite.

        The different problem types are specified by the argument :math:`\mathrm{itype}`, as indicated in the table below.
        The table shows how :math:`C` is computed by the function, and also how the eigenvectors :math:`z` of the original problem can be recovered from the eigenvectors of the standard form.

        +----------------------+-----------------------+---------------------+-------------------------------------------+-------------------------------------------------------------+----------------------------------------+
        |:math:`\mathrm{itype}`|Problem                |:math:`\mathrm{uplo}`|:math:`B`                                  |:math:`C`                                                    |:math:`z`                               |
        +======================+=======================+=====================+===========================================+=============================================================+========================================+
        |:math:`1`             |:math:`Az = \lambda Bz`|'U' 'L'              |:math:`U^\mathrm{T}U` :math:`LL^\mathrm{T}`|:math:`U^{-\mathrm{T}}AU^{-1}` :math:`L^{-1}AL^{-\mathrm{T}}`|:math:`U^{-1}y` :math:`L^{-\mathrm{T}}y`|
        +----------------------+-----------------------+---------------------+-------------------------------------------+-------------------------------------------------------------+----------------------------------------+
        |:math:`2`             |:math:`ABz = \lambda z`|'U' 'L'              |:math:`U^\mathrm{T}U` :math:`LL^\mathrm{T}`|:math:`UAU^\mathrm{T}` :math:`L^\mathrm{T}AL`                |:math:`U^{-1}y` :math:`L^{-\mathrm{T}}y`|
        +----------------------+-----------------------+---------------------+-------------------------------------------+-------------------------------------------------------------+----------------------------------------+
        |:math:`3`             |:math:`BAz = \lambda z`|'U' 'L'              |:math:`U^\mathrm{T}U` :math:`LL^\mathrm{T}`|:math:`UAU^\mathrm{T}` :math:`L^\mathrm{T}AL`                |:math:`U^\mathrm{T}y` :math:`Ly`        |
        +----------------------+-----------------------+---------------------+-------------------------------------------+-------------------------------------------------------------+----------------------------------------+

    .. _f08te-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 zhpgv(itype, jobz, uplo, n, ap, bp):
    r"""
    ``zhpgv`` computes all the eigenvalues and, optionally, all the eigenvectors of a complex generalized Hermitian-definite eigenproblem, of the form

    .. math::
        Az = \lambda Bz\text{, }\quad ABz = \lambda z\quad \text{ or }\quad BAz = \lambda z\text{,}

    where :math:`A` and :math:`B` are Hermitian, stored in packed format, and :math:`B` is also positive definite.

    .. _f08tn-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08tnf.html

    .. _f08tn-py2-py-parameters:

    **Parameters**
        **itype** : int
            Specifies the problem type to be solved.

            :math:`\mathrm{itype} = 1`

                :math:`Az = \lambda Bz`.

            :math:`\mathrm{itype} = 2`

                :math:`ABz = \lambda z`.

            :math:`\mathrm{itype} = 3`

                :math:`BAz = \lambda z`.

        **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 triangles of :math:`A` and :math:`B` are stored.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangles of :math:`A` and :math:`B` are stored.

        **n** : int
            :math:`n`, the order of the matrices :math:`A` and :math:`B`.

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

        **bp** : 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:`B`, packed by columns.

    **Returns**
        **ap** : complex, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
            The contents of :math:`\mathrm{ap}` are destroyed.

        **bp** : complex, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
            The triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`B = U^\mathrm{H}U` or :math:`B = LL^\mathrm{H}`, in the same storage format as :math:`B`.

        **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 matrix :math:`Z` of eigenvectors. The eigenvectors are normalized as follows:

                if :math:`\mathrm{itype} = 1` or :math:`2`, :math:`Z^\mathrm{H}BZ = I`;

                if :math:`\mathrm{itype} = 3`, :math:`Z^\mathrm{H}B^{-1}Z = I`.

            If :math:`\mathrm{jobz} = \texttt{'N'}`, :math:`\mathrm{z}` is not referenced.

    .. _f08tn-py2-py-errors:

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

                Constraint: :math:`\mathrm{itype} = 1`, :math:`2` or :math:`3`.

            (`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{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:`i \leq \mathrm{n}`)
                The algorithm failed to converge; :math:`\langle\mathit{\boldsymbol{value}}\rangle` off-diagonal elements of an intermediate tridiagonal form did not converge to zero.

            (`errno` :math:`i > \mathrm{n}`)
                If :math:`\textit{errno} = \mathrm{n}+\langle\mathit{\boldsymbol{value}}\rangle`, for :math:`1\leq \langle\mathit{\boldsymbol{value}}\rangle\leq \mathrm{n}`, then the leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`B` is not positive definite. The factorization of :math:`B` could not be completed and no eigenvalues or eigenvectors were computed.

    .. _f08tn-py2-py-notes:

    **Notes**
        ``zhpgv`` first performs a Cholesky factorization of the matrix :math:`B` as :math:`B = U^\mathrm{H}U`, when :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`B = LL^\mathrm{H}`, when :math:`\mathrm{uplo} = \texttt{'L'}`.
        The generalized problem is then reduced to a standard symmetric eigenvalue problem

        .. math::
            Cx = \lambda x\text{,}

        which is solved for the eigenvalues and, optionally, the eigenvectors; the eigenvectors are then backtransformed to give the eigenvectors of the original problem.

        For the problem :math:`Az = \lambda Bz`, the eigenvectors are normalized so that the matrix of eigenvectors, :math:`Z`, satisfies

        .. math::
            Z^\mathrm{H}AZ = \Lambda \quad \text{ and }\quad Z^\mathrm{H}BZ = I\text{,}

        where :math:`\Lambda` is the diagonal matrix whose diagonal elements are the eigenvalues.
        For the problem :math:`ABz = \lambda z` we correspondingly have

        .. math::
            Z^{-1}AZ^{-\mathrm{H}} = \Lambda \quad \text{ and }\quad Z^\mathrm{H}BZ = I\text{,}

        and for :math:`BAz = \lambda z` we have

        .. math::
            Z^\mathrm{H}AZ = \Lambda \quad \text{ and }\quad Z^\mathrm{H}B^{-1}Z = I\text{.}

    .. _f08tn-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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 zhpgvx(itype, jobz, erange, uplo, n, ap, bp, vl, vu, il, iu, abstol):
    r"""
    ``zhpgvx`` computes selected eigenvalues and, optionally, eigenvectors of a complex generalized Hermitian-definite eigenproblem, of the form

    .. math::
        Az = \lambda Bz\text{, }\quad ABz = \lambda z\quad \text{ or }\quad BAz = \lambda z\text{,}

    where :math:`A` and :math:`B` are Hermitian, stored in packed format, and :math:`B` is also positive definite.
    Eigenvalues and eigenvectors can be selected by specifying either a range of values or a range of indices for the desired eigenvalues.

    .. _f08tp-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08tpf.html

    .. _f08tp-py2-py-parameters:

    **Parameters**
        **itype** : int
            Specifies the problem type to be solved.

            :math:`\mathrm{itype} = 1`

                :math:`Az = \lambda Bz`.

            :math:`\mathrm{itype} = 2`

                :math:`ABz = \lambda z`.

            :math:`\mathrm{itype} = 3`

                :math:`BAz = \lambda z`.

        **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 triangles of :math:`A` and :math:`B` are stored.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangles of :math:`A` and :math:`B` are stored.

        **n** : int
            :math:`n`, the order of the matrices :math:`A` and :math:`B`.

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

        **bp** : 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:`B`, 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:`C` 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}` = 1 ... :math:`\mathrm{n}`, 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)`
            The contents of :math:`\mathrm{ap}` are destroyed.

        **bp** : complex, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
            The triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`B = U^\mathrm{H}U` or :math:`B = LL^\mathrm{H}`, in the same storage format as :math:`B`.

        **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 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]`. The eigenvectors are normalized as follows:

                    if :math:`\mathrm{itype} = 1` or :math:`2`, :math:`Z^\mathrm{H}BZ = I`;

                    if :math:`\mathrm{itype} = 3`, :math:`Z^\mathrm{H}B^{-1}Z = I`;

                if an eigenvector fails to converge (:math:`\mathrm{errno}` = 1 ... :math:`\mathrm{n}`), 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}` = 1 ... :math:`\mathrm{n}`, the first :math:`\textit{errno}` elements of :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.

    .. _f08tp-py2-py-errors:

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

                Constraint: :math:`\mathrm{itype} = 1`, :math:`2` or :math:`3`.

            (`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:`\mathrm{uplo}`.

                Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.

            (`errno` :math:`-5`)
                On entry, error in parameter :math:`\mathrm{n}`.

                Constraint: :math:`\mathrm{n}\geq 0`.

            (`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 > \mathrm{n}`)
                If :math:`\textit{errno} = \mathrm{n}+\langle\mathit{\boldsymbol{value}}\rangle`, for :math:`1\leq \langle\mathit{\boldsymbol{value}}\rangle\leq \mathrm{n}`, then the leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`B` is not positive definite. The factorization of :math:`B` could not be completed and no eigenvalues or eigenvectors were computed.

    **Warns**
        **NagAlgorithmicWarning**
            (`errno` :math:`i \leq \mathrm{n}`)
                The algorithm failed to converge; :math:`\langle\mathit{\boldsymbol{value}}\rangle` eigenvectors failed to converge.

    .. _f08tp-py2-py-notes:

    **Notes**
        ``zhpgvx`` first performs a Cholesky factorization of the matrix :math:`B` as :math:`B = U^\mathrm{H}U`, when :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`B = LL^\mathrm{H}`, when :math:`\mathrm{uplo} = \texttt{'L'}`.
        The generalized problem is then reduced to a standard symmetric eigenvalue problem

        .. math::
            Cx = \lambda x\text{,}

        which is solved for the desired eigenvalues and eigenvectors; the eigenvectors are then backtransformed to give the eigenvectors of the original problem.

        For the problem :math:`Az = \lambda Bz`, the eigenvectors are normalized so that the matrix of eigenvectors, :math:`Z`, satisfies

        .. math::
            Z^\mathrm{H}AZ = \Lambda \quad \text{ and }\quad Z^\mathrm{H}BZ = I\text{,}

        where :math:`\Lambda` is the diagonal matrix whose diagonal elements are the eigenvalues.
        For the problem :math:`ABz = \lambda z` we correspondingly have

        .. math::
            Z^{-1}AZ^{-\mathrm{H}} = \Lambda \quad \text{ and }\quad Z^\mathrm{H}BZ = I\text{,}

        and for :math:`BAz = \lambda z` we have

        .. math::
            Z^\mathrm{H}AZ = \Lambda \quad \text{ and }\quad Z^\mathrm{H}B^{-1}Z = I\text{.}

    .. _f08tp-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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 zhpgvd(itype, jobz, uplo, n, ap, bp):
    r"""
    ``zhpgvd`` computes all the eigenvalues and, optionally, the eigenvectors of a complex generalized Hermitian-definite eigenproblem, of the form

    .. math::
        Az = \lambda Bz\text{, }\quad ABz = \lambda z\quad \text{ or }\quad BAz = \lambda z\text{,}

    where :math:`A` and :math:`B` are Hermitian, stored in packed format, and :math:`B` is also positive definite.
    If eigenvectors are desired, it uses a divide-and-conquer algorithm.

    .. _f08tq-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08tqf.html

    .. _f08tq-py2-py-parameters:

    **Parameters**
        **itype** : int
            Specifies the problem type to be solved.

            :math:`\mathrm{itype} = 1`

                :math:`Az = \lambda Bz`.

            :math:`\mathrm{itype} = 2`

                :math:`ABz = \lambda z`.

            :math:`\mathrm{itype} = 3`

                :math:`BAz = \lambda z`.

        **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 triangles of :math:`A` and :math:`B` are stored.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangles of :math:`A` and :math:`B` are stored.

        **n** : int
            :math:`n`, the order of the matrices :math:`A` and :math:`B`.

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

        **bp** : 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:`B`, packed by columns.

    **Returns**
        **ap** : complex, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
            The contents of :math:`\mathrm{ap}` are destroyed.

        **bp** : complex, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
            The triangular factor :math:`U` or :math:`L` from the Cholesky factorization :math:`B = U^\mathrm{H}U` or :math:`B = LL^\mathrm{H}`, in the same storage format as :math:`B`.

        **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 matrix :math:`Z` of eigenvectors. The eigenvectors are normalized as follows:

                if :math:`\mathrm{itype} = 1` or :math:`2`, :math:`Z^\mathrm{H}BZ = I`;

                if :math:`\mathrm{itype} = 3`, :math:`Z^\mathrm{H}B^{-1}Z = I`.

            If :math:`\mathrm{jobz} = \texttt{'N'}`, :math:`\mathrm{z}` is not referenced.

    .. _f08tq-py2-py-errors:

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

                Constraint: :math:`\mathrm{itype} = 1`, :math:`2` or :math:`3`.

            (`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{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:`i \leq \mathrm{n}`)
                The algorithm failed to converge; :math:`\langle\mathit{\boldsymbol{value}}\rangle` off-diagonal elements of an intermediate tridiagonal form did not converge to zero.

            (`errno` :math:`i > \mathrm{n}`)
                If :math:`\textit{errno} = \mathrm{n}+\langle\mathit{\boldsymbol{value}}\rangle`, for :math:`1\leq \langle\mathit{\boldsymbol{value}}\rangle\leq \mathrm{n}`, then the leading minor of order :math:`\langle\mathit{\boldsymbol{value}}\rangle` of :math:`B` is not positive definite. The factorization of :math:`B` could not be completed and no eigenvalues or eigenvectors were computed.

    .. _f08tq-py2-py-notes:

    **Notes**
        ``zhpgvd`` first performs a Cholesky factorization of the matrix :math:`B` as :math:`B = U^\mathrm{H}U`, when :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`B = LL^\mathrm{H}`, when :math:`\mathrm{uplo} = \texttt{'L'}`.
        The generalized problem is then reduced to a standard symmetric eigenvalue problem

        .. math::
            Cx = \lambda x\text{,}

        which is solved for the eigenvalues and, optionally, the eigenvectors; the eigenvectors are then backtransformed to give the eigenvectors of the original problem.

        For the problem :math:`Az = \lambda Bz`, the eigenvectors are normalized so that the matrix of eigenvectors, :math:`z`, satisfies

        .. math::
            Z^\mathrm{H}AZ = \Lambda \quad \text{ and }\quad Z^\mathrm{H}BZ = I\text{,}

        where :math:`\Lambda` is the diagonal matrix whose diagonal elements are the eigenvalues.
        For the problem :math:`ABz = \lambda z` we correspondingly have

        .. math::
            Z^{-1}AZ^{-\mathrm{H}} = \Lambda \quad \text{ and }\quad Z^\mathrm{H}BZ = I\text{,}

        and for :math:`BAz = \lambda z` we have

        .. math::
            Z^\mathrm{H}AZ = \Lambda \quad \text{ and }\quad Z^\mathrm{H}B^{-1}Z = I\text{.}

    .. _f08tq-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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 zhpgst(itype, uplo, n, ap, bp):
    r"""
    ``zhpgst`` reduces a complex Hermitian-definite generalized eigenproblem :math:`Az = \lambda Bz`, :math:`ABz = \lambda z` or :math:`BAz = \lambda z` to the standard form :math:`Cy = \lambda y`, where :math:`A` is a complex Hermitian matrix and :math:`B` has been factorized by :meth:`lapacklin.zpptrf <naginterfaces.library.lapacklin.zpptrf>`, using packed storage.

    .. _f08ts-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08tsf.html

    .. _f08ts-py2-py-parameters:

    **Parameters**
        **itype** : int
            Indicates how the standard form is computed.

            :math:`\mathrm{itype} = 1`

                    if :math:`\mathrm{uplo} = \texttt{'U'}`, :math:`C = U^{-\mathrm{H}}AU^{-1}`;

                    if :math:`\mathrm{uplo} = \texttt{'L'}`, :math:`C = L^{-1}AL^{-\mathrm{H}}`.

            :math:`\mathrm{itype} = 2` or :math:`3`

                    if :math:`\mathrm{uplo} = \texttt{'U'}`, :math:`C = UAU^\mathrm{H}`;

                    if :math:`\mathrm{uplo} = \texttt{'L'}`, :math:`C = L^\mathrm{H}AL`.

        **uplo** : str, length 1
            Indicates whether the upper or lower triangular part of :math:`A` is stored and how :math:`B` has been factorized.

            :math:`\mathrm{uplo} = \texttt{'U'}`

                The upper triangular part of :math:`A` is stored and :math:`B = U^\mathrm{H}U`.

            :math:`\mathrm{uplo} = \texttt{'L'}`

                The lower triangular part of :math:`A` is stored and :math:`B = LL^\mathrm{H}`.

        **n** : int
            :math:`n`, the order of the matrices :math:`A` and :math:`B`.

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

        **bp** : complex, array-like, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
            The Cholesky factor of :math:`B` as specified by :math:`\mathrm{uplo}` and returned by :meth:`lapacklin.zpptrf <naginterfaces.library.lapacklin.zpptrf>`.

    **Returns**
        **ap** : complex, ndarray, shape :math:`\left(\mathrm{n}\times \left(\mathrm{n}+1\right)/2\right)`
            The upper or lower triangle of :math:`\mathrm{ap}` is overwritten by the corresponding upper or lower triangle of :math:`C` as specified by :math:`\mathrm{itype}` and :math:`\mathrm{uplo}`, using the same packed storage format as described above.

    .. _f08ts-py2-py-errors:

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

                Constraint: :math:`\mathrm{itype} = 1`, :math:`2` or :math:`3`.

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

    .. _f08ts-py2-py-notes:

    **Notes**
        To reduce the complex Hermitian-definite generalized eigenproblem :math:`Az = \lambda Bz`, :math:`ABz = \lambda z` or :math:`BAz = \lambda z` to the standard form :math:`Cy = \lambda y` using packed storage, ``zhpgst`` must be preceded by a call to :meth:`lapacklin.zpptrf <naginterfaces.library.lapacklin.zpptrf>` which computes the Cholesky factorization of :math:`B`; :math:`B` must be positive definite.

        The different problem types are specified by the argument :math:`\mathrm{itype}`, as indicated in the table below.
        The table shows how :math:`C` is computed by the function, and also how the eigenvectors :math:`z` of the original problem can be recovered from the eigenvectors of the standard form.

        +----------------------+-----------------------+---------------------+-------------------------------------------+-------------------------------------------------------------+----------------------------------------+
        |:math:`\mathrm{itype}`|Problem                |:math:`\mathrm{uplo}`|:math:`B`                                  |:math:`C`                                                    |:math:`z`                               |
        +======================+=======================+=====================+===========================================+=============================================================+========================================+
        |:math:`1`             |:math:`Az = \lambda Bz`|'U' 'L'              |:math:`U^\mathrm{H}U` :math:`LL^\mathrm{H}`|:math:`U^{-\mathrm{H}}AU^{-1}` :math:`L^{-1}AL^{-\mathrm{H}}`|:math:`U^{-1}y` :math:`L^{-\mathrm{H}}y`|
        +----------------------+-----------------------+---------------------+-------------------------------------------+-------------------------------------------------------------+----------------------------------------+
        |:math:`2`             |:math:`ABz = \lambda z`|'U' 'L'              |:math:`U^\mathrm{H}U` :math:`LL^\mathrm{H}`|:math:`UAU^\mathrm{H}` :math:`L^\mathrm{H}AL`                |:math:`U^{-1}y` :math:`L^{-\mathrm{H}}y`|
        +----------------------+-----------------------+---------------------+-------------------------------------------+-------------------------------------------------------------+----------------------------------------+
        |:math:`3`             |:math:`BAz = \lambda z`|'U' 'L'              |:math:`U^\mathrm{H}U` :math:`LL^\mathrm{H}`|:math:`UAU^\mathrm{H}` :math:`L^\mathrm{H}AL`                |:math:`U^\mathrm{H}y` :math:`Ly`        |
        +----------------------+-----------------------+---------------------+-------------------------------------------+-------------------------------------------------------------+----------------------------------------+

    .. _f08ts-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 dsbgv(jobz, uplo, ka, kb, ab, bb):
    r"""
    ``dsbgv`` computes all the eigenvalues and, optionally, the eigenvectors of a real generalized symmetric-definite banded eigenproblem, of the form

    .. math::
        Az = \lambda Bz\text{,}

    where :math:`A` and :math:`B` are symmetric and banded, and :math:`B` is also positive definite.

    .. _f08ua-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08uaf.html

    .. _f08ua-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 triangles of :math:`A` and :math:`B` are stored.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangles of :math:`A` and :math:`B` are stored.

        **ka** : int
            If :math:`\mathrm{uplo} = \texttt{'U'}`, the number of superdiagonals, :math:`k_a`, of the matrix :math:`A`.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the number of subdiagonals, :math:`k_a`, of the matrix :math:`A`.

        **kb** : int
            If :math:`\mathrm{uplo} = \texttt{'U'}`, the number of superdiagonals, :math:`k_b`, of the matrix :math:`B`.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the number of subdiagonals, :math:`k_b`, of the matrix :math:`B`.

        **ab** : float, array-like, shape :math:`\left(\mathrm{ka}+1, n\right)`
            The upper or lower triangle of the :math:`n\times n` symmetric band matrix :math:`A`.

        **bb** : float, array-like, shape :math:`\left(\mathrm{kb}+1, n\right)`
            The upper or lower triangle of the :math:`n\times n` symmetric band matrix :math:`B`.

    **Returns**
        **ab** : float, ndarray, shape :math:`\left(\mathrm{ka}+1, n\right)`
            The contents of :math:`\mathrm{ab}` are overwritten.

        **bb** : float, ndarray, shape :math:`\left(\mathrm{kb}+1, n\right)`
            The factor :math:`S` from the split Cholesky factorization :math:`B = S^\mathrm{T}S`, as returned by :meth:`dpbstf`.

        **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 matrix :math:`Z` of eigenvectors, with the :math:`i`\ th column of :math:`Z` holding the eigenvector associated with :math:`\mathrm{w}[i-1]`. The eigenvectors are normalized so that :math:`Z^\mathrm{T}BZ = I`.

            If :math:`\mathrm{jobz} = \texttt{'N'}`, :math:`\mathrm{z}` is not referenced.

    .. _f08ua-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{ka}`.

                Constraint: :math:`\mathrm{ka}\geq 0`.

            (`errno` :math:`-5`)
                On entry, error in parameter :math:`\mathrm{kb}`.

                Constraint: :math:`\mathrm{ka}\geq \mathrm{kb}\geq 0`.

            (`errno` :math:`i \leq n`)
                The algorithm failed to converge; :math:`\langle\mathit{\boldsymbol{value}}\rangle` off-diagonal elements of an intermediate tridiagonal form did not converge to zero.

            (`errno` :math:`i > n`)
                If :math:`\textit{errno} = n+\langle\mathit{\boldsymbol{value}}\rangle`, for :math:`1\leq \langle\mathit{\boldsymbol{value}}\rangle\leq n`, :meth:`dpbstf` returned :math:`\textit{errno} = \langle\mathit{\boldsymbol{value}}\rangle`: :math:`B` is not positive definite. The factorization of :math:`B` could not be completed and no eigenvalues or eigenvectors were computed.

    .. _f08ua-py2-py-notes:

    **Notes**
        The generalized symmetric-definite band problem

        .. math::
            Az = \lambda Bz

        is first reduced to a standard band symmetric problem

        .. math::
            Cx = \lambda x\text{,}

        where :math:`C` is a symmetric band matrix, using Wilkinson's modification to Crawford's algorithm (see Crawford (1973) and Wilkinson (1977)).
        The symmetric eigenvalue problem is then solved for the eigenvalues and the eigenvectors, if required, which are then backtransformed to the eigenvectors of the original problem.

        The eigenvectors are normalized so that the matrix of eigenvectors, :math:`Z`, satisfies

        .. math::
            Z^\mathrm{T}AZ = \Lambda \quad \text{ and }\quad Z^\mathrm{T}BZ = I\text{,}

        where :math:`\Lambda` is the diagonal matrix whose diagonal elements are the eigenvalues.

    .. _f08ua-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug

        Crawford, C R, 1973, `Reduction of a band-symmetric generalized eigenvalue problem`, Comm. ACM (16), 41--44

        Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore

        Wilkinson, J H, 1977, `Some recent advances in numerical linear algebra`, The State of the Art in Numerical Analysis, (ed D A H Jacobs), Academic Press
    """
    raise NotImplementedError

def dsbgvx(jobz, erange, uplo, ka, kb, ab, bb, vl, vu, il, iu, abstol):
    r"""
    ``dsbgvx`` computes selected eigenvalues and, optionally, eigenvectors of a real generalized symmetric-definite banded eigenproblem, of the form

    .. math::
        Az = \lambda Bz\text{,}

    where :math:`A` and :math:`B` are symmetric and banded, and :math:`B` is also positive definite.
    Eigenvalues and eigenvectors can be selected by specifying either all eigenvalues, a range of values or a range of indices for the desired eigenvalues.

    .. _f08ub-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08ubf.html

    .. _f08ub-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 triangles of :math:`A` and :math:`B` are stored.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangles of :math:`A` and :math:`B` are stored.

        **ka** : int
            If :math:`\mathrm{uplo} = \texttt{'U'}`, the number of superdiagonals, :math:`k_a`, of the matrix :math:`A`.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the number of subdiagonals, :math:`k_a`, of the matrix :math:`A`.

        **kb** : int
            If :math:`\mathrm{uplo} = \texttt{'U'}`, the number of superdiagonals, :math:`k_b`, of the matrix :math:`B`.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the number of subdiagonals, :math:`k_b`, of the matrix :math:`B`.

        **ab** : float, array-like, shape :math:`\left(\mathrm{ka}+1, n\right)`
            The upper or lower triangle of the :math:`n\times n` symmetric band matrix :math:`A`.

        **bb** : float, array-like, shape :math:`\left(\mathrm{kb}+1, n\right)`
            The upper or lower triangle of the :math:`n\times n` symmetric positive definite band matrix :math:`B`.

        **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:`C` 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}` = 1 ... :math:`\mathrm{n}`, 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{ka}+1, n\right)`
            The contents of :math:`\mathrm{ab}` are overwritten.

        **bb** : float, ndarray, shape :math:`\left(\mathrm{kb}+1, n\right)`
            The factor :math:`S` from the split Cholesky factorization :math:`B = S^\mathrm{T}S`, as returned by :meth:`dpbstf`.

        **q** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobz} = \texttt{'V'}`, the :math:`n\times n` matrix, :math:`Q` used in the reduction of the standard form, i.e., :math:`Cx = \lambda x`, from symmetric banded 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 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 eigenvectors corresponding to the selected eigenvalues, with the :math:`i`\ th column of :math:`Z` holding the eigenvector associated with :math:`\mathrm{w}[i-1]`. The eigenvectors are normalized so that :math:`Z^\mathrm{T}BZ = I`;

                if an eigenvector fails to converge (:math:`\mathrm{errno}` = 1 ... :math:`\mathrm{n}`), 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}` = 1 ... :math:`\mathrm{n}`, the first :math:`\textit{errno}` elements of :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.

    .. _f08ub-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{ka}`.

                Constraint: :math:`\mathrm{ka}\geq 0`.

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

                Constraint: :math:`\mathrm{ka}\geq \mathrm{kb}\geq 0`.

            (`errno` :math:`-14`)
                On entry, error in parameter :math:`\mathrm{vu}`.

                Constraint: :math:`\mathrm{vl} < \mathrm{vu}`.

            (`errno` :math:`-15`)
                On entry, error in parameter :math:`\mathrm{il}`.

            (`errno` :math:`-16`)
                On entry, error in parameter :math:`\mathrm{iu}`.

            (`errno` :math:`i > n`)
                If :math:`\textit{errno} = n+\langle\mathit{\boldsymbol{value}}\rangle`, for :math:`1\leq \langle\mathit{\boldsymbol{value}}\rangle\leq n`, :meth:`dpbstf` returned :math:`\textit{errno} = \langle\mathit{\boldsymbol{value}}\rangle`: :math:`B` is not positive definite. The factorization of :math:`B` could not be completed and no eigenvalues or eigenvectors were computed.

    **Warns**
        **NagAlgorithmicWarning**
            (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq n\right)`)
                The algorithm failed to converge; :math:`\langle\mathit{\boldsymbol{value}}\rangle` eigenvectors did not converge. Their indices are stored in array :math:`\mathrm{jfail}`.

    .. _f08ub-py2-py-notes:

    **Notes**
        The generalized symmetric-definite band problem

        .. math::
            Az = \lambda Bz

        is first reduced to a standard band symmetric problem

        .. math::
            Cx = \lambda x\text{,}

        where :math:`C` is a symmetric band matrix, using Wilkinson's modification to Crawford's algorithm (see Crawford (1973) and Wilkinson (1977)).
        The symmetric eigenvalue problem is then solved for the required eigenvalues and eigenvectors, and the eigenvectors are then backtransformed to the eigenvectors of the original problem.

        The eigenvectors are normalized so that

        .. math::
            z^\mathrm{T}Az = \lambda \quad \text{ and }\quad z^\mathrm{T}Bz = 1\text{.}

    .. _f08ub-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug

        Crawford, C R, 1973, `Reduction of a band-symmetric generalized eigenvalue problem`, Comm. ACM (16), 41--44

        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

        Wilkinson, J H, 1977, `Some recent advances in numerical linear algebra`, The State of the Art in Numerical Analysis, (ed D A H Jacobs), Academic Press
    """
    raise NotImplementedError

def dsbgvd(jobz, uplo, ka, kb, ab, bb):
    r"""
    ``dsbgvd`` computes all the eigenvalues and, optionally, the eigenvectors of a real generalized symmetric-definite banded eigenproblem, of the form

    .. math::
        Az = \lambda Bz\text{,}

    where :math:`A` and :math:`B` are symmetric and banded, and :math:`B` is also positive definite.
    If eigenvectors are desired, it uses a divide-and-conquer algorithm.

    .. _f08uc-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08ucf.html

    .. _f08uc-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 triangles of :math:`A` and :math:`B` are stored.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangles of :math:`A` and :math:`B` are stored.

        **ka** : int
            If :math:`\mathrm{uplo} = \texttt{'U'}`, the number of superdiagonals, :math:`k_a`, of the matrix :math:`A`.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the number of subdiagonals, :math:`k_a`, of the matrix :math:`A`.

        **kb** : int
            If :math:`\mathrm{uplo} = \texttt{'U'}`, the number of superdiagonals, :math:`k_b`, of the matrix :math:`B`.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the number of subdiagonals, :math:`k_b`, of the matrix :math:`B`.

        **ab** : float, array-like, shape :math:`\left(\mathrm{ka}+1, n\right)`
            The upper or lower triangle of the :math:`n\times n` symmetric band matrix :math:`A`.

        **bb** : float, array-like, shape :math:`\left(\mathrm{kb}+1, n\right)`
            The upper or lower triangle of the :math:`n\times n` symmetric band matrix :math:`B`.

    **Returns**
        **ab** : float, ndarray, shape :math:`\left(\mathrm{ka}+1, n\right)`
            The contents of :math:`\mathrm{ab}` are overwritten.

        **bb** : float, ndarray, shape :math:`\left(\mathrm{kb}+1, n\right)`
            The factor :math:`S` from the split Cholesky factorization :math:`B = S^\mathrm{T}S`, as returned by :meth:`dpbstf`.

        **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 matrix :math:`Z` of eigenvectors, with the :math:`i`\ th column of :math:`Z` holding the eigenvector associated with :math:`\mathrm{w}[i-1]`. The eigenvectors are normalized so that :math:`Z^\mathrm{T}BZ = I`.

            If :math:`\mathrm{jobz} = \texttt{'N'}`, :math:`\mathrm{z}` is not referenced.

    .. _f08uc-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{ka}`.

                Constraint: :math:`\mathrm{ka}\geq 0`.

            (`errno` :math:`-5`)
                On entry, error in parameter :math:`\mathrm{kb}`.

                Constraint: :math:`\mathrm{ka}\geq \mathrm{kb}\geq 0`.

            (`errno` :math:`i \leq n`)
                The algorithm failed to converge; :math:`\langle\mathit{\boldsymbol{value}}\rangle` off-diagonal elements of an intermediate tridiagonal form did not converge to zero.

            (`errno` :math:`i > n`)
                If :math:`\textit{errno} = n+\langle\mathit{\boldsymbol{value}}\rangle`, for :math:`1\leq \langle\mathit{\boldsymbol{value}}\rangle\leq n`, :meth:`dpbstf` returned :math:`\textit{errno} = \langle\mathit{\boldsymbol{value}}\rangle`: :math:`B` is not positive definite. The factorization of :math:`B` could not be completed and no eigenvalues or eigenvectors were computed.

    .. _f08uc-py2-py-notes:

    **Notes**
        The generalized symmetric-definite band problem

        .. math::
            Az = \lambda Bz

        is first reduced to a standard band symmetric problem

        .. math::
            Cx = \lambda x\text{,}

        where :math:`C` is a symmetric band matrix, using Wilkinson's modification to Crawford's algorithm (see Crawford (1973) and Wilkinson (1977)).
        The symmetric eigenvalue problem is then solved for the eigenvalues and the eigenvectors, if required, which are then backtransformed to the eigenvectors of the original problem.

        The eigenvectors are normalized so that the matrix of eigenvectors, :math:`Z`, satisfies

        .. math::
            Z^\mathrm{T}AZ = \Lambda \quad \text{ and }\quad Z^\mathrm{T}BZ = I\text{,}

        where :math:`\Lambda` is the diagonal matrix whose diagonal elements are the eigenvalues.

    .. _f08uc-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug

        Crawford, C R, 1973, `Reduction of a band-symmetric generalized eigenvalue problem`, Comm. ACM (16), 41--44

        Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore

        Wilkinson, J H, 1977, `Some recent advances in numerical linear algebra`, The State of the Art in Numerical Analysis, (ed D A H Jacobs), Academic Press
    """
    raise NotImplementedError

def dsbgst(vect, uplo, ka, kb, ab, bb):
    r"""
    ``dsbgst`` reduces a real symmetric-definite generalized eigenproblem :math:`Az = \lambda Bz` to the standard form :math:`Cy = \lambda y`, where :math:`A` and :math:`B` are band matrices, :math:`A` is a real symmetric matrix, and :math:`B` has been factorized by :meth:`dpbstf`.

    .. _f08ue-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08uef.html

    .. _f08ue-py2-py-parameters:

    **Parameters**
        **vect** : str, length 1
            Indicates whether :math:`X` is to be returned.

            :math:`\mathrm{vect} = \texttt{'N'}`

                :math:`X` is not returned.

            :math:`\mathrm{vect} = \texttt{'V'}`

                :math:`X` is returned.

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

        **ka** : int
            If :math:`\mathrm{uplo} = \texttt{'U'}`, the number of superdiagonals, :math:`k_a`, of the matrix :math:`A`.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the number of subdiagonals, :math:`k_a`, of the matrix :math:`A`.

        **kb** : int
            If :math:`\mathrm{uplo} = \texttt{'U'}`, the number of superdiagonals, :math:`k_b`, of the matrix :math:`B`.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the number of subdiagonals, :math:`k_b`, of the matrix :math:`B`.

        **ab** : float, array-like, shape :math:`\left(\mathrm{ka}+1, n\right)`
            The upper or lower triangle of the :math:`n\times n` symmetric band matrix :math:`A`.

        **bb** : float, array-like, shape :math:`\left(\mathrm{kb}+1, n\right)`
            The banded split Cholesky factor of :math:`B` as specified by :math:`\mathrm{uplo}`, :math:`\mathrm{n}` and :math:`\mathrm{kb}` and returned by :meth:`dpbstf`.

    **Returns**
        **ab** : float, ndarray, shape :math:`\left(\mathrm{ka}+1, n\right)`
            The upper or lower triangle of :math:`\mathrm{ab}` is overwritten by the corresponding upper or lower triangle of :math:`C` as specified by :math:`\mathrm{uplo}`.

        **x** : float, ndarray, shape :math:`\left(:, :\right)`
            The :math:`n\times n` matrix :math:`X = S^{-1}Q`, if :math:`\mathrm{vect} = \texttt{'V'}`.

            If :math:`\mathrm{vect} = \texttt{'N'}`, :math:`\mathrm{x}` is not referenced.

    .. _f08ue-py2-py-errors:

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

                Constraint: :math:`\mathrm{vect} = \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{ka}`.

                Constraint: :math:`\mathrm{ka}\geq 0`.

            (`errno` :math:`-5`)
                On entry, error in parameter :math:`\mathrm{kb}`.

                Constraint: :math:`\mathrm{ka}\geq \mathrm{kb}\geq 0`.

    .. _f08ue-py2-py-notes:

    **Notes**
        To reduce the real symmetric-definite generalized eigenproblem :math:`Az = \lambda Bz` to the standard form :math:`Cy = \lambda y`, where :math:`A`, :math:`B` and :math:`C` are banded, ``dsbgst`` must be preceded by a call to :meth:`dpbstf` which computes the split Cholesky factorization of the positive definite matrix :math:`B`: :math:`B = S^\mathrm{T}S`.
        The split Cholesky factorization, compared with the ordinary Cholesky factorization, allows the work to be approximately halved.

        This function overwrites :math:`A` with :math:`C = X^\mathrm{T}AX`, where :math:`X = S^{-1}Q` and :math:`Q` is a orthogonal matrix chosen (implicitly) to preserve the bandwidth of :math:`A`.
        The function also has an option to allow the accumulation of :math:`X`, and then, if :math:`z` is an eigenvector of :math:`C`, :math:`Xz` is an eigenvector of the original system.

    .. _f08ue-py2-py-references:

    **References**
        Crawford, C R, 1973, `Reduction of a band-symmetric generalized eigenvalue problem`, Comm. ACM (16), 41--44

        Kaufman, L, 1984, `Banded eigenvalue solvers on vector machines`, ACM Trans. Math. Software (10), 73--86
    """
    raise NotImplementedError

def dpbstf(uplo, kb, bb):
    r"""
    ``dpbstf`` computes a split Cholesky factorization of a real symmetric positive definite band matrix.

    .. _f08uf-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08uff.html

    .. _f08uf-py2-py-parameters:

    **Parameters**
        **uplo** : str, length 1
            Indicates whether the upper or lower triangular part of :math:`B` is stored.

            :math:`\mathrm{uplo} = \texttt{'U'}`

                The upper triangular part of :math:`B` is stored.

            :math:`\mathrm{uplo} = \texttt{'L'}`

                The lower triangular part of :math:`B` is stored.

        **kb** : int
            If :math:`\mathrm{uplo} = \texttt{'U'}`, the number of superdiagonals, :math:`k_b`, of the matrix :math:`B`.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the number of subdiagonals, :math:`k_b`, of the matrix :math:`B`.

        **bb** : float, array-like, shape :math:`\left(\mathrm{kb}+1, n\right)`
            The :math:`n\times n` symmetric positive definite band matrix :math:`B`.

    **Returns**
        **bb** : float, ndarray, shape :math:`\left(\mathrm{kb}+1, n\right)`
            :math:`B` is overwritten by the elements of its split Cholesky factor :math:`S`.

    .. _f08uf-py2-py-errors:

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

                Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.

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

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

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

                Constraint: :math:`\mathrm{kb}\geq 0`.

            (`errno` :math:`i > 0`)
                The factorization could not be completed, because the updated element :math:`b\left(\langle\mathit{\boldsymbol{value}}\rangle, \langle\mathit{\boldsymbol{value}}\rangle\right)` would be the square root of a negative number. Hence :math:`B` is not positive definite. This may indicate an error in forming the matrix :math:`B`.

    .. _f08uf-py2-py-notes:

    **Notes**
        ``dpbstf`` computes a split Cholesky factorization of a real symmetric positive definite band matrix :math:`B`.
        It is designed to be used in conjunction with :meth:`dsbgst`.

        The factorization has the form :math:`B = S^\mathrm{T}S`, where :math:`S` is a band matrix of the same bandwidth as :math:`B` and the following structure: :math:`S` is upper triangular in the first :math:`\left(n+k\right)/2` rows, and transposed --- hence, lower triangular --- in the remaining rows.
        For example, if :math:`n = 9` and :math:`k = 2`, then

        .. math::
            S = \begin{pmatrix}s_{11}&s_{12}&s_{13}&&&&&&\\&s_{22}&s_{23}&s_{24}&&&&&\\&&s_{33}&s_{34}&s_{35}&&&&\\&&&s_{44}&s_{45}&&&&\\&&&&s_{55}&&&&\\&&&s_{64}&s_{65}&s_{66}&&&\\&&&&s_{75}&s_{76}&s_{77}&&\\&&&&&s_{86}&s_{87}&s_{88}&\\&&&&&&s_{97}&s_{98}&s_{99}\end{pmatrix}\text{.}
    """
    raise NotImplementedError

def zhbgv(jobz, uplo, n, ka, kb, ab, bb):
    r"""
    ``zhbgv`` computes all the eigenvalues and, optionally, the eigenvectors of a complex generalized Hermitian-definite banded eigenproblem, of the form

    .. math::
        Az = \lambda Bz\text{,}

    where :math:`A` and :math:`B` are Hermitian and banded, and :math:`B` is also positive definite.

    .. _f08un-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08unf.html

    .. _f08un-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 triangles of :math:`A` and :math:`B` are stored.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangles of :math:`A` and :math:`B` are stored.

        **n** : int
            :math:`n`, the order of the matrices :math:`A` and :math:`B`.

        **ka** : int
            If :math:`\mathrm{uplo} = \texttt{'U'}`, the number of superdiagonals, :math:`k_a`, of the matrix :math:`A`.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the number of subdiagonals, :math:`k_a`, of the matrix :math:`A`.

        **kb** : int
            If :math:`\mathrm{uplo} = \texttt{'U'}`, the number of superdiagonals, :math:`k_b`, of the matrix :math:`B`.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the number of subdiagonals, :math:`k_b`, of the matrix :math:`B`.

        **ab** : complex, array-like, shape :math:`\left(\mathrm{ka}+1, \mathrm{n}\right)`
            The upper or lower triangle of the :math:`n\times n` Hermitian band matrix :math:`A`.

        **bb** : complex, array-like, shape :math:`\left(\mathrm{kb}+1, \mathrm{n}\right)`
            The upper or lower triangle of the :math:`n\times n` Hermitian band matrix :math:`B`.

    **Returns**
        **ab** : complex, ndarray, shape :math:`\left(\mathrm{ka}+1, \mathrm{n}\right)`
            The contents of :math:`\mathrm{ab}` are overwritten.

        **bb** : complex, ndarray, shape :math:`\left(\mathrm{kb}+1, \mathrm{n}\right)`
            The factor :math:`S` from the split Cholesky factorization :math:`B = S^\mathrm{H}S`, as returned by :meth:`zpbstf`.

        **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 matrix :math:`Z` of eigenvectors, with the :math:`i`\ th column of :math:`Z` holding the eigenvector associated with :math:`\mathrm{w}[i-1]`. The eigenvectors are normalized so that :math:`Z^\mathrm{H}BZ = I`.

            If :math:`\mathrm{jobz} = \texttt{'N'}`, :math:`\mathrm{z}` is not referenced.

    .. _f08un-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{ka}`.

                Constraint: :math:`\mathrm{ka}\geq 0`.

            (`errno` :math:`-5`)
                On entry, error in parameter :math:`\mathrm{kb}`.

                Constraint: :math:`\mathrm{ka}\geq \mathrm{kb}\geq 0`.

            (`errno` :math:`i \leq \mathrm{n}`)
                The algorithm failed to converge; :math:`\langle\mathit{\boldsymbol{value}}\rangle` off-diagonal elements of an intermediate tridiagonal form did not converge to zero.

            (`errno` :math:`i > \mathrm{n}`)
                If :math:`\textit{errno} = \mathrm{n}+\langle\mathit{\boldsymbol{value}}\rangle`, for :math:`1\leq \langle\mathit{\boldsymbol{value}}\rangle\leq \mathrm{n}`, :meth:`zpbstf` returned :math:`\textit{errno} = \langle\mathit{\boldsymbol{value}}\rangle`: :math:`B` is not positive definite. The factorization of :math:`B` could not be completed and no eigenvalues or eigenvectors were computed.

    .. _f08un-py2-py-notes:

    **Notes**
        The generalized Hermitian-definite band problem

        .. math::
            Az = \lambda Bz

        is first reduced to a standard band Hermitian problem

        .. math::
            Cx = \lambda x\text{,}

        where :math:`C` is a Hermitian band matrix, using Wilkinson's modification to Crawford's algorithm (see Crawford (1973) and Wilkinson (1977)).
        The Hermitian eigenvalue problem is then solved for the eigenvalues and the eigenvectors, if required, which are then backtransformed to the eigenvectors of the original problem.

        The eigenvectors are normalized so that the matrix of eigenvectors, :math:`Z`, satisfies

        .. math::
            Z^\mathrm{H}AZ = \Lambda \quad \text{ and }\quad Z^\mathrm{H}BZ = I\text{,}

        where :math:`\Lambda` is the diagonal matrix whose diagonal elements are the eigenvalues.

    .. _f08un-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug

        Crawford, C R, 1973, `Reduction of a band-symmetric generalized eigenvalue problem`, Comm. ACM (16), 41--44

        Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore

        Wilkinson, J H, 1977, `Some recent advances in numerical linear algebra`, The State of the Art in Numerical Analysis, (ed D A H Jacobs), Academic Press
    """
    raise NotImplementedError

def zhbgvx(jobz, erange, uplo, n, ka, kb, ab, bb, vl, vu, il, iu, abstol):
    r"""
    ``zhbgvx`` computes selected the eigenvalues and, optionally, the eigenvectors of a complex generalized Hermitian-definite banded eigenproblem, of the form

    .. math::
        Az = \lambda Bz\text{,}

    where :math:`A` and :math:`B` are Hermitian and banded, and :math:`B` is also positive definite.
    Eigenvalues and eigenvectors can be selected by specifying either all eigenvalues, a range of values or a range of indices for the desired eigenvalues.

    .. _f08up-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08upf.html

    .. _f08up-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 triangles of :math:`A` and :math:`B` are stored.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangles of :math:`A` and :math:`B` are stored.

        **n** : int
            :math:`n`, the order of the matrices :math:`A` and :math:`B`.

        **ka** : int
            If :math:`\mathrm{uplo} = \texttt{'U'}`, the number of superdiagonals, :math:`k_a`, of the matrix :math:`A`.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the number of subdiagonals, :math:`k_a`, of the matrix :math:`A`.

        **kb** : int
            If :math:`\mathrm{uplo} = \texttt{'U'}`, the number of superdiagonals, :math:`k_b`, of the matrix :math:`B`.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the number of subdiagonals, :math:`k_b`, of the matrix :math:`B`.

        **ab** : complex, array-like, shape :math:`\left(\mathrm{ka}+1, \mathrm{n}\right)`
            The upper or lower triangle of the :math:`n\times n` Hermitian band matrix :math:`A`.

        **bb** : complex, array-like, shape :math:`\left(\mathrm{kb}+1, \mathrm{n}\right)`
            The upper or lower triangle of the :math:`n\times n` Hermitian positive definite band matrix :math:`B`.

        **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:`C` 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}` = 1 ... :math:`\mathrm{n}`, 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{ka}+1, \mathrm{n}\right)`
            The contents of :math:`\mathrm{ab}` are overwritten.

        **bb** : complex, ndarray, shape :math:`\left(\mathrm{kb}+1, \mathrm{n}\right)`
            The factor :math:`S` from the split Cholesky factorization :math:`B = S^\mathrm{H}S`, as returned by :meth:`zpbstf`.

        **q** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobz} = \texttt{'V'}`, the :math:`n\times n` matrix, :math:`Q` used in the reduction of the standard form, i.e., :math:`Cx = \lambda x`, from symmetric banded 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 \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 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 eigenvectors corresponding to the selected eigenvalues, with the :math:`i`\ th column of :math:`Z` holding the eigenvector associated with :math:`\mathrm{w}[i-1]`. The eigenvectors are normalized so that :math:`Z^\mathrm{H}BZ = I`;

                if an eigenvector fails to converge (:math:`\mathrm{errno}` = 1 ... :math:`\mathrm{n}`), 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}` = 1 ... :math:`\mathrm{n}`, the first :math:`\textit{errno}` elements of :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.

    .. _f08up-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:`-5`)
                On entry, error in parameter :math:`\mathrm{ka}`.

                Constraint: :math:`\mathrm{ka}\geq 0`.

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

                Constraint: :math:`\mathrm{ka}\geq \mathrm{kb}\geq 0`.

            (`errno` :math:`-14`)
                On entry, error in parameter :math:`\mathrm{vu}`.

                Constraint: :math:`\mathrm{vl} < \mathrm{vu}`.

            (`errno` :math:`-15`)
                On entry, error in parameter :math:`\mathrm{il}`.

            (`errno` :math:`-16`)
                On entry, error in parameter :math:`\mathrm{iu}`.

            (`errno` :math:`i > \mathrm{n}`)
                If :math:`\textit{errno} = \mathrm{n}+\langle\mathit{\boldsymbol{value}}\rangle`, for :math:`1\leq \langle\mathit{\boldsymbol{value}}\rangle\leq \mathrm{n}`, :meth:`zpbstf` returned :math:`\textit{errno} = \langle\mathit{\boldsymbol{value}}\rangle`: :math:`B` is not positive definite. The factorization of :math:`B` could not be completed and no eigenvalues or eigenvectors were computed.

    **Warns**
        **NagAlgorithmicWarning**
            (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq \mathrm{n}\right)`)
                The algorithm failed to converge; :math:`\langle\mathit{\boldsymbol{value}}\rangle` eigenvectors did not converge. Their indices are stored in array :math:`\mathrm{jfail}`.

    .. _f08up-py2-py-notes:

    **Notes**
        The generalized Hermitian-definite band problem

        .. math::
            Az = \lambda Bz

        is first reduced to a standard band Hermitian problem

        .. math::
            Cx = \lambda x\text{,}

        where :math:`C` is a Hermitian band matrix, using Wilkinson's modification to Crawford's algorithm (see Crawford (1973) and Wilkinson (1977)).
        The Hermitian eigenvalue problem is then solved for the required eigenvalues and eigenvectors, and the eigenvectors are then backtransformed to the eigenvectors of the original problem.

        The eigenvectors are normalized so that

        .. math::
            z^\mathrm{H}Az = \lambda \quad \text{ and }\quad z^\mathrm{H}Bz = 1\text{.}

    .. _f08up-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug

        Crawford, C R, 1973, `Reduction of a band-symmetric generalized eigenvalue problem`, Comm. ACM (16), 41--44

        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

        Wilkinson, J H, 1977, `Some recent advances in numerical linear algebra`, The State of the Art in Numerical Analysis, (ed D A H Jacobs), Academic Press
    """
    raise NotImplementedError

def zhbgvd(jobz, uplo, n, ka, kb, ab, bb):
    r"""
    ``zhbgvd`` computes all the eigenvalues and, optionally, the eigenvectors of a complex generalized Hermitian-definite banded eigenproblem, of the form

    .. math::
        Az = \lambda Bz\text{,}

    where :math:`A` and :math:`B` are Hermitian and banded, and :math:`B` is also positive definite.
    If eigenvectors are desired, it uses a divide-and-conquer algorithm.

    .. _f08uq-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08uqf.html

    .. _f08uq-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 triangles of :math:`A` and :math:`B` are stored.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the lower triangles of :math:`A` and :math:`B` are stored.

        **n** : int
            :math:`n`, the order of the matrices :math:`A` and :math:`B`.

        **ka** : int
            If :math:`\mathrm{uplo} = \texttt{'U'}`, the number of superdiagonals, :math:`k_a`, of the matrix :math:`A`.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the number of subdiagonals, :math:`k_a`, of the matrix :math:`A`.

        **kb** : int
            If :math:`\mathrm{uplo} = \texttt{'U'}`, the number of superdiagonals, :math:`k_b`, of the matrix :math:`B`.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the number of subdiagonals, :math:`k_b`, of the matrix :math:`B`.

        **ab** : complex, array-like, shape :math:`\left(\mathrm{ka}+1, \mathrm{n}\right)`
            The upper or lower triangle of the :math:`n\times n` Hermitian band matrix :math:`A`.

        **bb** : complex, array-like, shape :math:`\left(\mathrm{kb}+1, \mathrm{n}\right)`
            The upper or lower triangle of the :math:`n\times n` Hermitian band matrix :math:`B`.

    **Returns**
        **ab** : complex, ndarray, shape :math:`\left(\mathrm{ka}+1, \mathrm{n}\right)`
            The contents of :math:`\mathrm{ab}` are overwritten.

        **bb** : complex, ndarray, shape :math:`\left(\mathrm{kb}+1, \mathrm{n}\right)`
            The factor :math:`S` from the split Cholesky factorization :math:`B = S^\mathrm{H}S`, as returned by :meth:`zpbstf`.

        **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 matrix :math:`Z` of eigenvectors, with the :math:`i`\ th column of :math:`Z` holding the eigenvector associated with :math:`\mathrm{w}[i-1]`. The eigenvectors are normalized so that :math:`Z^\mathrm{H}BZ = I`.

            If :math:`\mathrm{jobz} = \texttt{'N'}`, :math:`\mathrm{z}` is not referenced.

    .. _f08uq-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{ka}`.

                Constraint: :math:`\mathrm{ka}\geq 0`.

            (`errno` :math:`-5`)
                On entry, error in parameter :math:`\mathrm{kb}`.

                Constraint: :math:`\mathrm{ka}\geq \mathrm{kb}\geq 0`.

            (`errno` :math:`i \leq \mathrm{n}`)
                The algorithm failed to converge; :math:`\langle\mathit{\boldsymbol{value}}\rangle` off-diagonal elements of an intermediate tridiagonal form did not converge to zero.

            (`errno` :math:`i > \mathrm{n}`)
                If :math:`\textit{errno} = \mathrm{n}+\langle\mathit{\boldsymbol{value}}\rangle`, for :math:`1\leq \langle\mathit{\boldsymbol{value}}\rangle\leq \mathrm{n}`, :meth:`zpbstf` returned :math:`\textit{errno} = \langle\mathit{\boldsymbol{value}}\rangle`: :math:`B` is not positive definite. The factorization of :math:`B` could not be completed and no eigenvalues or eigenvectors were computed.

    .. _f08uq-py2-py-notes:

    **Notes**
        The generalized Hermitian-definite band problem

        .. math::
            Az = \lambda Bz

        is first reduced to a standard band Hermitian problem

        .. math::
            Cx = \lambda x\text{,}

        where :math:`C` is a Hermitian band matrix, using Wilkinson's modification to Crawford's algorithm (see Crawford (1973) and Wilkinson (1977)).
        The Hermitian eigenvalue problem is then solved for the eigenvalues and the eigenvectors, if required, which are then backtransformed to the eigenvectors of the original problem.

        The eigenvectors are normalized so that the matrix of eigenvectors, :math:`Z`, satisfies

        .. math::
            Z^\mathrm{H}AZ = \Lambda \quad \text{ and }\quad Z^\mathrm{H}BZ = I\text{,}

        where :math:`\Lambda` is the diagonal matrix whose diagonal elements are the eigenvalues.

    .. _f08uq-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug

        Crawford, C R, 1973, `Reduction of a band-symmetric generalized eigenvalue problem`, Comm. ACM (16), 41--44

        Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore

        Wilkinson, J H, 1977, `Some recent advances in numerical linear algebra`, The State of the Art in Numerical Analysis, (ed D A H Jacobs), Academic Press
    """
    raise NotImplementedError

def zhbgst(vect, uplo, n, ka, kb, ab, bb):
    r"""
    ``zhbgst`` reduces a complex Hermitian-definite generalized eigenproblem :math:`Az = \lambda Bz` to the standard form :math:`Cy = \lambda y`, where :math:`A` and :math:`B` are band matrices, :math:`A` is a complex Hermitian matrix, and :math:`B` has been factorized by :meth:`zpbstf`.

    .. _f08us-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08usf.html

    .. _f08us-py2-py-parameters:

    **Parameters**
        **vect** : str, length 1
            Indicates whether :math:`X` is to be returned.

            :math:`\mathrm{vect} = \texttt{'N'}`

                :math:`X` is not returned.

            :math:`\mathrm{vect} = \texttt{'V'}`

                :math:`X` is returned.

        **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 matrices :math:`A` and :math:`B`.

        **ka** : int
            If :math:`\mathrm{uplo} = \texttt{'U'}`, the number of superdiagonals, :math:`k_a`, of the matrix :math:`A`.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the number of subdiagonals, :math:`k_a`, of the matrix :math:`A`.

        **kb** : int
            If :math:`\mathrm{uplo} = \texttt{'U'}`, the number of superdiagonals, :math:`k_b`, of the matrix :math:`B`.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the number of subdiagonals, :math:`k_b`, of the matrix :math:`B`.

        **ab** : complex, array-like, shape :math:`\left(\mathrm{ka}+1, \mathrm{n}\right)`
            The upper or lower triangle of the :math:`n\times n` Hermitian band matrix :math:`A`.

        **bb** : complex, array-like, shape :math:`\left(\mathrm{kb}+1, \mathrm{n}\right)`
            The banded split Cholesky factor of :math:`B` as specified by :math:`\mathrm{uplo}`, :math:`\mathrm{n}` and :math:`\mathrm{kb}` and returned by :meth:`zpbstf`.

    **Returns**
        **ab** : complex, ndarray, shape :math:`\left(\mathrm{ka}+1, \mathrm{n}\right)`
            The upper or lower triangle of :math:`\mathrm{ab}` is overwritten by the corresponding upper or lower triangle of :math:`C` as specified by :math:`\mathrm{uplo}`.

        **x** : complex, ndarray, shape :math:`\left(:, :\right)`
            The :math:`n\times n` matrix :math:`X = S^{-1}Q`, if :math:`\mathrm{vect} = \texttt{'V'}`.

            If :math:`\mathrm{vect} = \texttt{'N'}`, :math:`\mathrm{x}` is not referenced.

    .. _f08us-py2-py-errors:

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

                Constraint: :math:`\mathrm{vect} = \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{ka}`.

                Constraint: :math:`\mathrm{ka}\geq 0`.

            (`errno` :math:`-5`)
                On entry, error in parameter :math:`\mathrm{kb}`.

                Constraint: :math:`\mathrm{ka}\geq \mathrm{kb}\geq 0`.

    .. _f08us-py2-py-notes:

    **Notes**
        To reduce the complex Hermitian-definite generalized eigenproblem :math:`Az = \lambda Bz` to the standard form :math:`Cy = \lambda y`, where :math:`A`, :math:`B` and :math:`C` are banded, ``zhbgst`` must be preceded by a call to :meth:`zpbstf` which computes the split Cholesky factorization of the positive definite matrix :math:`B`: :math:`B = S^\mathrm{H}S`.
        The split Cholesky factorization, compared with the ordinary Cholesky factorization, allows the work to be approximately halved.

        This function overwrites :math:`A` with :math:`C = X^\mathrm{H}AX`, where :math:`X = S^{-1}Q` and :math:`Q` is a unitary matrix chosen (implicitly) to preserve the bandwidth of :math:`A`.
        The function also has an option to allow the accumulation of :math:`X`, and then, if :math:`z` is an eigenvector of :math:`C`, :math:`Xz` is an eigenvector of the original system.

    .. _f08us-py2-py-references:

    **References**
        Crawford, C R, 1973, `Reduction of a band-symmetric generalized eigenvalue problem`, Comm. ACM (16), 41--44

        Kaufman, L, 1984, `Banded eigenvalue solvers on vector machines`, ACM Trans. Math. Software (10), 73--86
    """
    raise NotImplementedError

def zpbstf(uplo, kb, bb):
    r"""
    ``zpbstf`` computes a split Cholesky factorization of a complex Hermitian positive definite band matrix.

    .. _f08ut-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08utf.html

    .. _f08ut-py2-py-parameters:

    **Parameters**
        **uplo** : str, length 1
            Indicates whether the upper or lower triangular part of :math:`B` is stored.

            :math:`\mathrm{uplo} = \texttt{'U'}`

                The upper triangular part of :math:`B` is stored.

            :math:`\mathrm{uplo} = \texttt{'L'}`

                The lower triangular part of :math:`B` is stored.

        **kb** : int
            If :math:`\mathrm{uplo} = \texttt{'U'}`, the number of superdiagonals, :math:`k_b`, of the matrix :math:`B`.

            If :math:`\mathrm{uplo} = \texttt{'L'}`, the number of subdiagonals, :math:`k_b`, of the matrix :math:`B`.

        **bb** : complex, array-like, shape :math:`\left(\mathrm{kb}+1, n\right)`
            The :math:`n\times n` Hermitian positive definite band matrix :math:`B`.

    **Returns**
        **bb** : complex, ndarray, shape :math:`\left(\mathrm{kb}+1, n\right)`
            :math:`B` is overwritten by the elements of its split Cholesky factor :math:`S`.

    .. _f08ut-py2-py-errors:

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

                Constraint: :math:`\mathrm{uplo} = \texttt{'U'}` or :math:`\texttt{'L'}`.

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

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

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

                Constraint: :math:`\mathrm{kb}\geq 0`.

            (`errno` :math:`i > 0`)
                The factorization could not be completed, because the updated element :math:`b\left(\langle\mathit{\boldsymbol{value}}\rangle, \langle\mathit{\boldsymbol{value}}\rangle\right)` would be the square root of a negative number. Hence :math:`B` is not positive definite. This may indicate an error in forming the matrix :math:`B`.

    .. _f08ut-py2-py-notes:

    **Notes**
        ``zpbstf`` computes a split Cholesky factorization of a complex Hermitian positive definite band matrix :math:`B`.
        It is designed to be used in conjunction with :meth:`zhbgst`.

        The factorization has the form :math:`B = S^\mathrm{H}S`, where :math:`S` is a band matrix of the same bandwidth as :math:`B` and the following structure: :math:`S` is upper triangular in the first :math:`\left(n+k\right)/2` rows, and transposed --- hence, lower triangular --- in the remaining rows.
        For example, if :math:`n = 9` and :math:`k = 2`, then

        .. math::
            S = \begin{pmatrix}s_{11}&s_{12}&s_{13}&&&&&&\\&s_{22}&s_{23}&s_{24}&&&&&\\&&s_{33}&s_{34}&s_{35}&&&&\\&&&s_{44}&s_{45}&&&&\\&&&&s_{55}&&&&\\&&&s_{64}&s_{65}&s_{66}&&&\\&&&&s_{75}&s_{76}&s_{77}&&\\&&&&&s_{86}&s_{87}&s_{88}&\\&&&&&&s_{97}&s_{98}&s_{99}\end{pmatrix}\text{.}
    """
    raise NotImplementedError

def dggsvd(jobu, jobv, jobq, a, b):
    r"""
    ``dggsvd`` computes the generalized singular value decomposition (GSVD) of an :math:`m\times n` real matrix :math:`A` and a :math:`p\times n` real matrix :math:`B`. ``dggsvd`` is marked as `deprecated` by LAPACK; the replacement routine is :meth:`dggsvd3` which makes better use of Level 3 BLAS.

    .. deprecated:: 27.0.0.0
        ``dggsvd`` is deprecated.
        Please use :meth:`dggsvd3` instead.
        See also the :ref:`Replacement Calls <replace>` document.

    .. _f08va-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08vaf.html

    .. _f08va-py2-py-parameters:

    **Parameters**
        **jobu** : str, length 1
            If :math:`\mathrm{jobu} = \texttt{'U'}`, the orthogonal matrix :math:`U` is computed.

            If :math:`\mathrm{jobu} = \texttt{'N'}`, :math:`U` is not computed.

        **jobv** : str, length 1
            If :math:`\mathrm{jobv} = \texttt{'V'}`, the orthogonal matrix :math:`V` is computed.

            If :math:`\mathrm{jobv} = \texttt{'N'}`, :math:`V` is not computed.

        **jobq** : str, length 1
            If :math:`\mathrm{jobq} = \texttt{'Q'}`, the orthogonal matrix :math:`Q` is computed.

            If :math:`\mathrm{jobq} = \texttt{'N'}`, :math:`Q` is not computed.

        **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(p, n\right)`
            The :math:`p\times n` matrix :math:`B`.

    **Returns**
        **k** : int
            :math:`\mathrm{k}` and :math:`\mathrm{l}` specify the dimension of the subblocks :math:`k` and :math:`l` as described in :ref:`Notes <f08va-py2-py-notes>`; :math:`\left(k+l\right)` is the effective numerical rank of (A;B).

        **l** : int
            :math:`\mathrm{k}` and :math:`\mathrm{l}` specify the dimension of the subblocks :math:`k` and :math:`l` as described in :ref:`Notes <f08va-py2-py-notes>`; :math:`\left(k+l\right)` is the effective numerical rank of (A;B).

        **a** : float, ndarray, shape :math:`\left(m, n\right)`
            Contains the triangular matrix :math:`R`, or part of :math:`R`. See :ref:`Notes <f08va-py2-py-notes>` for details.

        **b** : float, ndarray, shape :math:`\left(p, n\right)`
            Contains the triangular matrix :math:`R` if :math:`m-k-l < 0`. See :ref:`Notes <f08va-py2-py-notes>` for details.

        **alpha** : float, ndarray, shape :math:`\left(n\right)`
            See the description of :math:`\mathrm{beta}`.

        **beta** : float, ndarray, shape :math:`\left(n\right)`
            :math:`\mathrm{alpha}` and :math:`\mathrm{beta}` contain the generalized singular value pairs of :math:`A` and :math:`B`, :math:`\alpha_i` and :math:`\beta_i`;

                :math:`\mathrm{alpha}[0:\mathrm{k}] = 1`,

                :math:`\mathrm{beta}[0:\mathrm{k}] = 0`,

            and if :math:`m-k-l\geq 0`,

                :math:`\mathrm{alpha}[\mathrm{k}:\mathrm{k}+\mathrm{l}] = C`,

                :math:`\mathrm{beta}[\mathrm{k}:\mathrm{k}+\mathrm{l}] = S`,

            or if :math:`m-k-l < 0`,

                :math:`\mathrm{alpha}[\mathrm{k}:m] = C`,

                :math:`\mathrm{alpha}[m:\mathrm{k}+\mathrm{l}] = 0`,

                :math:`\mathrm{beta}[\mathrm{k}:m] = S`,

                :math:`\mathrm{beta}[m:\mathrm{k}+\mathrm{l}] = 1`, and

                :math:`\mathrm{alpha}[\mathrm{k}+\mathrm{l}:n] = 0`,

                :math:`\mathrm{beta}[\mathrm{k}+\mathrm{l}:n] = 0`.

            The notation :math:`\mathrm{alpha}[\mathrm{k}-1:n]` above refers to consecutive elements :math:`\mathrm{alpha}[\textit{i}-1]`, for :math:`\textit{i} = \mathrm{k},\ldots,n`.

        **u** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobu} = \texttt{'U'}`, :math:`\mathrm{u}` contains the :math:`m\times m` orthogonal matrix :math:`U`.

            If :math:`\mathrm{jobu} = \texttt{'N'}`, :math:`\mathrm{u}` is not referenced.

        **v** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobv} = \texttt{'V'}`, :math:`\mathrm{v}` contains the :math:`p\times p` orthogonal matrix :math:`V`.

            If :math:`\mathrm{jobv} = \texttt{'N'}`, :math:`\mathrm{v}` is not referenced.

        **q** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobq} = \texttt{'Q'}`, :math:`\mathrm{q}` contains the :math:`n\times n` orthogonal matrix :math:`Q`.

            If :math:`\mathrm{jobq} = \texttt{'N'}`, :math:`\mathrm{q}` is not referenced.

        **iwork** : int, ndarray, shape :math:`\left(n\right)`
            Stores the sorting information. More precisely, the following loop will sort :math:`\mathrm{alpha}`

            ::

              for i in range(k+1, min(m,k+l)+1):
                swap alpha[i-1] and alpha[iwork[i-1]-1]

            such that :math:`\mathrm{alpha}[0]\geq \mathrm{alpha}[1]\geq \cdots \geq \mathrm{alpha}[n-1]`.

    .. _f08va-py2-py-errors:

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

                Constraint: :math:`\mathrm{jobu} = \texttt{'U'}` or :math:`\texttt{'N'}`.

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

                Constraint: :math:`\mathrm{jobv} = \texttt{'V'}` or :math:`\texttt{'N'}`.

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

                Constraint: :math:`\mathrm{jobq} = \texttt{'Q'}` 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:`n\geq 0`.

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

                Constraint: :math:`p\geq 0`.

            (`errno` :math:`1`)
                The Jacobi-type procedure failed to converge.

    .. _f08va-py2-py-notes:

    **Notes**
        The generalized singular value decomposition is given by

        .. math::
            U^\mathrm{T}AQ = D_1\begin{pmatrix}0&R\end{pmatrix}\text{, }\quad V^\mathrm{T}BQ = D_2\begin{pmatrix}0&R\end{pmatrix}\text{,}

        where :math:`U`, :math:`V` and :math:`Q` are orthogonal matrices.
        Let :math:`\left(k+l\right)` be the effective numerical rank of the matrix (A;B), then :math:`R` is a :math:`\left(k+l\right)\times \left(k+l\right)` nonsingular upper triangular matrix, :math:`D_1` and :math:`D_2` are :math:`m\times \left(k+l\right)` and :math:`p\times \left(k+l\right)` 'diagonal' matrices structured as follows:

        if :math:`m-k-l\geq 0`,

        .. math::
            D_1 = \begin{matrix}{}\\k\\l\\m-k-l\end{matrix}\begin{pmatrix}k&l\\I&0\\0&C\\0&0\end{pmatrix}

        .. math::
            D_2 = \begin{matrix}{}\\l\\p-l\end{matrix}\begin{pmatrix}k&l\\0&S\\0&0\end{pmatrix}

        .. math::
            \begin{pmatrix}0&R\end{pmatrix} = \begin{matrix}{}\\k\\l\end{matrix}\begin{pmatrix}n-k-l&k&l\\0&R_{11}&R_{12}\\0&0&R_{22}\end{pmatrix}

        where

        .. math::
            C = \mathrm{diag}\left(\alpha_{{k+1}}, \ldots, \alpha_{{k+l}}\right)\text{,}

        .. math::
            S = \mathrm{diag}\left(\beta_{{k+1}}, \ldots, \beta_{{k+l}}\right)\text{,}

        and

        .. math::
            C^2+S^2 = I\text{.}

        :math:`R` is stored as a submatrix of :math:`A` with elements :math:`R_{{ij}}` stored as :math:`A_{{i,n-k-l+j}}` on exit.

        If :math:`m-k-l < 0`,

        .. math::
            D_1 = \begin{matrix}{}\\k\\m-k\end{matrix}\begin{pmatrix}k&m-k&k+l-m\\I&0&0\\0&C&0\end{pmatrix}

        .. math::
            D_2 = \begin{matrix}{}\\m-k\\k+l-m\\p-l\end{matrix}\begin{pmatrix}k&m-k&k+l-m\\0&S&0\\0&0&I\\0&0&0\end{pmatrix}

        .. math::
            \begin{pmatrix}0&R\end{pmatrix} = \begin{matrix}{}\\k\\m-k\\k+l-m\end{matrix}\begin{pmatrix}n-k-l&k&m-k&k+l-m\\0&R_{11}&R_{12}&R_{13}\\0&0&R_{22}&R_{23}\\0&0&0&R_{33}\end{pmatrix}

        where

        .. math::
            C = \mathrm{diag}\left(\alpha_{{k+1}}, \ldots, \alpha_m\right)\text{,}

        .. math::
            S = \mathrm{diag}\left(\beta_{{k+1}}, \ldots, \beta_m\right)\text{,}

        and

        .. math::
            C^2+S^2 = I\text{.}

        :math:`\begin{pmatrix}R_{11}&R_{12}&R_{13}\\0&R_{22}&R_{23}\end{pmatrix}` is stored as a submatrix of :math:`A` with :math:`R_{{ij}}` stored as :math:`A_{{i,n-k-l+j}}`, and :math:`R_{33}` is stored as a submatrix of :math:`B` with :math:`\left(R_{33}\right)_{{ij}}` stored as :math:`B_{{m-k+i,n+m-k-l+j}}`.

        The function computes :math:`C`, :math:`S`, :math:`R` and, optionally, the orthogonal transformation matrices :math:`U`, :math:`V` and :math:`Q`.

        In particular, if :math:`B` is an :math:`n\times n` nonsingular matrix, then the GSVD of :math:`A` and :math:`B` implicitly gives the SVD of :math:`AB^{-1}`:

        .. math::
            AB^{-1} = U\left(D_1D_2^{-1}\right)V^\mathrm{T}\text{.}

        If (A;B) has orthonormal columns, then the GSVD of :math:`A` and :math:`B` is also equal to the CS decomposition of :math:`A` and :math:`B`.
        Furthermore, the GSVD can be used to derive the solution of the eigenvalue problem:

        .. math::
            A^\mathrm{T}Ax = \lambda B^\mathrm{T}Bx\text{.}

        In some literature, the GSVD of :math:`A` and :math:`B` is presented in the form

        .. math::
            U^\mathrm{T}AX = \begin{pmatrix}0&D_1\end{pmatrix}\text{, }\quad V^\mathrm{T}BX = \begin{pmatrix}0&D_2\end{pmatrix}\text{,}

        where :math:`U` and :math:`V` are orthogonal and :math:`X` is nonsingular, and :math:`D_1` and :math:`D_2` are 'diagonal'.
        The former GSVD form can be converted to the latter form by taking the nonsingular matrix :math:`X` as

        .. math::
            X = Q\begin{pmatrix}I&0\\0&R^{-1}\end{pmatrix}\text{.}

    .. _f08va-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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 dggsvd3(jobu, jobv, jobq, a, b):
    r"""
    ``dggsvd3`` computes the generalized singular value decomposition (GSVD) of an :math:`m\times n` real matrix :math:`A` and a :math:`p\times n` real matrix :math:`B`.

    .. _f08vc-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08vcf.html

    .. _f08vc-py2-py-parameters:

    **Parameters**
        **jobu** : str, length 1
            If :math:`\mathrm{jobu} = \texttt{'U'}`, the orthogonal matrix :math:`U` is computed.

            If :math:`\mathrm{jobu} = \texttt{'N'}`, :math:`U` is not computed.

        **jobv** : str, length 1
            If :math:`\mathrm{jobv} = \texttt{'V'}`, the orthogonal matrix :math:`V` is computed.

            If :math:`\mathrm{jobv} = \texttt{'N'}`, :math:`V` is not computed.

        **jobq** : str, length 1
            If :math:`\mathrm{jobq} = \texttt{'Q'}`, the orthogonal matrix :math:`Q` is computed.

            If :math:`\mathrm{jobq} = \texttt{'N'}`, :math:`Q` is not computed.

        **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(p, n\right)`
            The :math:`p\times n` matrix :math:`B`.

    **Returns**
        **k** : int
            :math:`\mathrm{k}` and :math:`\mathrm{l}` specify the dimension of the subblocks :math:`k` and :math:`l` as described in :ref:`Notes <f08vc-py2-py-notes>`; :math:`\left(k+l\right)` is the effective numerical rank of (A;B).

        **l** : int
            :math:`\mathrm{k}` and :math:`\mathrm{l}` specify the dimension of the subblocks :math:`k` and :math:`l` as described in :ref:`Notes <f08vc-py2-py-notes>`; :math:`\left(k+l\right)` is the effective numerical rank of (A;B).

        **a** : float, ndarray, shape :math:`\left(m, n\right)`
            Contains the triangular matrix :math:`R`, or part of :math:`R`. See :ref:`Notes <f08vc-py2-py-notes>` for details.

        **b** : float, ndarray, shape :math:`\left(p, n\right)`
            Contains the triangular matrix :math:`R` if :math:`m-k-l < 0`. See :ref:`Notes <f08vc-py2-py-notes>` for details.

        **alpha** : float, ndarray, shape :math:`\left(n\right)`
            See the description of :math:`\mathrm{beta}`.

        **beta** : float, ndarray, shape :math:`\left(n\right)`
            :math:`\mathrm{alpha}` and :math:`\mathrm{beta}` contain the generalized singular value pairs of :math:`A` and :math:`B`, :math:`\alpha_i` and :math:`\beta_i`;

                :math:`\mathrm{alpha}[0:\mathrm{k}] = 1`,

                :math:`\mathrm{beta}[0:\mathrm{k}] = 0`,

            and if :math:`m-k-l\geq 0`,

                :math:`\mathrm{alpha}[\mathrm{k}:\mathrm{k}+\mathrm{l}] = C`,

                :math:`\mathrm{beta}[\mathrm{k}:\mathrm{k}+\mathrm{l}] = S`,

            or if :math:`m-k-l < 0`,

                :math:`\mathrm{alpha}[\mathrm{k}:m] = C`,

                :math:`\mathrm{alpha}[m:\mathrm{k}+\mathrm{l}] = 0`,

                :math:`\mathrm{beta}[\mathrm{k}:m] = S`,

                :math:`\mathrm{beta}[m:\mathrm{k}+\mathrm{l}] = 1`, and

                :math:`\mathrm{alpha}[\mathrm{k}+\mathrm{l}:n] = 0`,

                :math:`\mathrm{beta}[\mathrm{k}+\mathrm{l}:n] = 0`.

            The notation :math:`\mathrm{alpha}[\mathrm{k}-1:n]` above refers to consecutive elements :math:`\mathrm{alpha}[\textit{i}-1]`, for :math:`\textit{i} = \mathrm{k},\ldots,n`.

        **u** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobu} = \texttt{'U'}`, :math:`\mathrm{u}` contains the :math:`m\times m` orthogonal matrix :math:`U`.

            If :math:`\mathrm{jobu} = \texttt{'N'}`, :math:`\mathrm{u}` is not referenced.

        **v** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobv} = \texttt{'V'}`, :math:`\mathrm{v}` contains the :math:`p\times p` orthogonal matrix :math:`V`.

            If :math:`\mathrm{jobv} = \texttt{'N'}`, :math:`\mathrm{v}` is not referenced.

        **q** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobq} = \texttt{'Q'}`, :math:`\mathrm{q}` contains the :math:`n\times n` orthogonal matrix :math:`Q`.

            If :math:`\mathrm{jobq} = \texttt{'N'}`, :math:`\mathrm{q}` is not referenced.

        **iwork** : int, ndarray, shape :math:`\left(n\right)`
            Stores the sorting information. More precisely, if :math:`I` is the ordered set of indices of :math:`\mathrm{alpha}` containing :math:`C` (denote as :math:`\mathrm{alpha}[I]`, see :math:`\mathrm{beta}`), then the corresponding elements :math:`\mathrm{iwork}[I]-1` contain the swap pivots, :math:`J`, that sorts :math:`I` such that :math:`\mathrm{alpha}[I]` is in descending numerical order.

            The following pseudocode sorts the set :math:`I`:

            :math:`\begin{array}{l}\text{for }i \in I\\\hspace{2em} j = J_i\\\hspace{2em} \text{swap }I_i\text{ and }I_j\\\text{end}\end{array}`

    .. _f08vc-py2-py-errors:

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

                Constraint: :math:`\mathrm{jobu} = \texttt{'U'}` or :math:`\texttt{'N'}`.

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

                Constraint: :math:`\mathrm{jobv} = \texttt{'V'}` or :math:`\texttt{'N'}`.

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

                Constraint: :math:`\mathrm{jobq} = \texttt{'Q'}` 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:`n\geq 0`.

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

                Constraint: :math:`p\geq 0`.

            (`errno` :math:`1`)
                The Jacobi-type procedure failed to converge.

    .. _f08vc-py2-py-notes:

    **Notes**
        Given an :math:`m\times n` real matrix :math:`A` and a :math:`p\times n` real matrix :math:`B`, the generalized singular value decomposition is given by

        .. math::
            U^\mathrm{T}AQ = D_1\begin{pmatrix}0&R\end{pmatrix}\text{, }\quad V^\mathrm{T}BQ = D_2\begin{pmatrix}0&R\end{pmatrix}\text{,}

        where :math:`U`, :math:`V` and :math:`Q` are orthogonal matrices.
        Let :math:`l` be the effective numerical rank of :math:`B` and :math:`\left(k+l\right)` be the effective numerical rank of the matrix (A;B), then the first :math:`k` generalized singular values are infinite and the remaining :math:`l` are finite. :math:`R` is a :math:`\left(k+l\right)\times \left(k+l\right)` nonsingular upper triangular matrix, :math:`D_1` and :math:`D_2` are :math:`m\times \left(k+l\right)` and :math:`p\times \left(k+l\right)` 'diagonal' matrices structured as follows:

        if :math:`m-k-l\geq 0`,

        .. math::
            D_1 = \begin{matrix}{}\\k\\l\\m-k-l\end{matrix}\begin{pmatrix}k&l\\I&0\\0&C\\0&0\end{pmatrix}

        .. math::
            D_2 = \begin{matrix}{}\\l\\p-l\end{matrix}\begin{pmatrix}k&l\\0&S\\0&0\end{pmatrix}

        .. math::
            \begin{pmatrix}0&R\end{pmatrix} = \begin{matrix}{}\\k\\l\end{matrix}\begin{pmatrix}n-k-l&k&l\\0&R_{11}&R_{12}\\0&0&R_{22}\end{pmatrix}

        where

        .. math::
            C = \mathrm{diag}\left(\alpha_{{k+1}}, \ldots, \alpha_{{k+l}}\right)\text{,}

        .. math::
            S = \mathrm{diag}\left(\beta_{{k+1}}, \ldots, \beta_{{k+l}}\right)\text{,}

        and

        .. math::
            C^2+S^2 = I\text{.}

        :math:`R` is stored as a submatrix of :math:`A` with elements :math:`R_{{ij}}` stored as :math:`A_{{i,n-k-l+j}}` on exit.

        If :math:`m-k-l < 0`,

        .. math::
            D_1 = \begin{matrix}{}\\k\\m-k\end{matrix}\begin{pmatrix}k&m-k&k+l-m\\I&0&0\\0&C&0\end{pmatrix}

        .. math::
            D_2 = \begin{matrix}{}\\m-k\\k+l-m\\p-l\end{matrix}\begin{pmatrix}k&m-k&k+l-m\\0&S&0\\0&0&I\\0&0&0\end{pmatrix}

        .. math::
            \begin{pmatrix}0&R\end{pmatrix} = \begin{matrix}{}\\k\\m-k\\k+l-m\end{matrix}\begin{pmatrix}n-k-l&k&m-k&k+l-m\\0&R_{11}&R_{12}&R_{13}\\0&0&R_{22}&R_{23}\\0&0&0&R_{33}\end{pmatrix}

        where

        .. math::
            C = \mathrm{diag}\left(\alpha_{{k+1}}, \ldots, \alpha_m\right)\text{,}

        .. math::
            S = \mathrm{diag}\left(\beta_{{k+1}}, \ldots, \beta_m\right)\text{,}

        and

        .. math::
            C^2+S^2 = I\text{.}

        :math:`\begin{pmatrix}R_{11}&R_{12}&R_{13}\\0&R_{22}&R_{23}\end{pmatrix}` is stored as a submatrix of :math:`A` with :math:`R_{{ij}}` stored as :math:`A_{{i,n-k-l+j}}`, and :math:`R_{33}` is stored as a submatrix of :math:`B` with :math:`\left(R_{33}\right)_{{ij}}` stored as :math:`B_{{m-k+i,n+m-k-l+j}}`.

        The function computes :math:`C`, :math:`S`, :math:`R` and, optionally, the orthogonal transformation matrices :math:`U`, :math:`V` and :math:`Q`.

        In particular, if :math:`B` is an :math:`n\times n` nonsingular matrix, then the GSVD of :math:`A` and :math:`B` implicitly gives the SVD of :math:`AB^{-1}`:

        .. math::
            AB^{-1} = U\left(D_1D_2^{-1}\right)V^\mathrm{T}\text{.}

        If (A;B) has orthonormal columns, then the GSVD of :math:`A` and :math:`B` is also equal to the CS decomposition of :math:`A` and :math:`B`.
        Furthermore, the GSVD can be used to derive the solution of the eigenvalue problem:

        .. math::
            A^\mathrm{T}Ax = \lambda B^\mathrm{T}Bx\text{.}

        In some literature, the GSVD of :math:`A` and :math:`B` is presented in the form

        .. math::
            U^\mathrm{T}AX = \begin{pmatrix}0&D_1\end{pmatrix}\text{, }\quad V^\mathrm{T}BX = \begin{pmatrix}0&D_2\end{pmatrix}\text{,}

        where :math:`U` and :math:`V` are orthogonal and :math:`X` is nonsingular, and :math:`D_1` and :math:`D_2` are 'diagonal'.
        The former GSVD form can be converted to the latter form by setting

        .. math::
            X = Q\begin{pmatrix}I&0\\0&R^{-1}\end{pmatrix}\text{.}

        A two stage process is used to compute the GSVD of the matrix pair :math:`\left(A, B\right)`.
        The pair is first reduced to upper triangular form by orthogonal transformations using :meth:`dggsvp3`.
        The GSVD of the resulting upper triangular matrix pair is then performed by :meth:`dtgsja` which uses a variant of the Kogbetliantz algorithm (a cyclic Jacobi method).

    .. _f08vc-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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, 2012, `Matrix Computations`, (4th Edition), Johns Hopkins University Press, Baltimore
    """
    raise NotImplementedError

def dggsvp(jobu, jobv, jobq, a, b, tola, tolb):
    r"""
    ``dggsvp`` uses orthogonal transformations to simultaneously reduce the :math:`m\times n` matrix :math:`A` and the :math:`p\times n` matrix :math:`B` to upper triangular form.
    This factorization is usually used as a preprocessing step for computing the generalized singular value decomposition (GSVD). ``dggsvp`` is marked as `deprecated` by LAPACK; the replacement routine is :meth:`dggsvp3` which makes better use of Level 3 BLAS.

    .. deprecated:: 27.0.0.0
        ``dggsvp`` is deprecated.
        Please use :meth:`dggsvp3` instead.
        See also the :ref:`Replacement Calls <replace>` document.

    .. _f08ve-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08vef.html

    .. _f08ve-py2-py-parameters:

    **Parameters**
        **jobu** : str, length 1
            If :math:`\mathrm{jobu} = \texttt{'U'}`, the orthogonal matrix :math:`U` is computed.

            If :math:`\mathrm{jobu} = \texttt{'N'}`, :math:`U` is not computed.

        **jobv** : str, length 1
            If :math:`\mathrm{jobv} = \texttt{'V'}`, the orthogonal matrix :math:`V` is computed.

            If :math:`\mathrm{jobv} = \texttt{'N'}`, :math:`V` is not computed.

        **jobq** : str, length 1
            If :math:`\mathrm{jobq} = \texttt{'Q'}`, the orthogonal matrix :math:`Q` is computed.

            If :math:`\mathrm{jobq} = \texttt{'N'}`, :math:`Q` is not computed.

        **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(p, n\right)`
            The :math:`p\times n` matrix :math:`B`.

        **tola** : float
            :math:`\mathrm{tola}` and :math:`\mathrm{tolb}` are the thresholds to determine the effective numerical rank of matrix :math:`B` and a subblock of :math:`A`. Generally, they are set to

            .. math::
                \begin{array}{c}\mathrm{tola} = \mathrm{max}\left(m, n\right)\left\lVert A\right\rVert \epsilon \text{,}\\\mathrm{tolb} = \mathrm{max}\left(p, n\right)\left\lVert B\right\rVert \epsilon \text{,}\end{array}

            where :math:`\epsilon` is the machine precision.

            The size of :math:`\mathrm{tola}` and :math:`\mathrm{tolb}` may affect the size of backward errors of the decomposition.

        **tolb** : float
            :math:`\mathrm{tola}` and :math:`\mathrm{tolb}` are the thresholds to determine the effective numerical rank of matrix :math:`B` and a subblock of :math:`A`. Generally, they are set to

            .. math::
                \begin{array}{c}\mathrm{tola} = \mathrm{max}\left(m, n\right)\left\lVert A\right\rVert \epsilon \text{,}\\\mathrm{tolb} = \mathrm{max}\left(p, n\right)\left\lVert B\right\rVert \epsilon \text{,}\end{array}

            where :math:`\epsilon` is the machine precision.

            The size of :math:`\mathrm{tola}` and :math:`\mathrm{tolb}` may affect the size of backward errors of the decomposition.

    **Returns**
        **a** : float, ndarray, shape :math:`\left(m, n\right)`
            Contains the triangular (or trapezoidal) matrix described in :ref:`Notes <f08ve-py2-py-notes>`.

        **b** : float, ndarray, shape :math:`\left(p, n\right)`
            Contains the triangular matrix described in :ref:`Notes <f08ve-py2-py-notes>`.

        **k** : int
            :math:`\mathrm{k}` and :math:`\mathrm{l}` specify the dimension of the subblocks :math:`k` and :math:`l` as described in :ref:`Notes <f08ve-py2-py-notes>`; :math:`\left(k+l\right)` is the effective numerical rank of :math:`\begin{pmatrix}\mathrm{a}^\mathrm{T}&\mathrm{b}^\mathrm{T}\end{pmatrix}^\mathrm{T}`.

        **l** : int
            :math:`\mathrm{k}` and :math:`\mathrm{l}` specify the dimension of the subblocks :math:`k` and :math:`l` as described in :ref:`Notes <f08ve-py2-py-notes>`; :math:`\left(k+l\right)` is the effective numerical rank of :math:`\begin{pmatrix}\mathrm{a}^\mathrm{T}&\mathrm{b}^\mathrm{T}\end{pmatrix}^\mathrm{T}`.

        **u** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobu} = \texttt{'U'}`, :math:`\mathrm{u}` contains the orthogonal matrix :math:`U`.

            If :math:`\mathrm{jobu} = \texttt{'N'}`, :math:`\mathrm{u}` is not referenced.

        **v** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobv} = \texttt{'V'}`, :math:`\mathrm{v}` contains the orthogonal matrix :math:`V`.

            If :math:`\mathrm{jobv} = \texttt{'N'}`, :math:`\mathrm{v}` is not referenced.

        **q** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobq} = \texttt{'Q'}`, :math:`\mathrm{q}` contains the orthogonal matrix :math:`Q`.

            If :math:`\mathrm{jobq} = \texttt{'N'}`, :math:`\mathrm{q}` is not referenced.

    .. _f08ve-py2-py-errors:

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

                Constraint: :math:`\mathrm{jobu} = \texttt{'U'}` or :math:`\texttt{'N'}`.

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

                Constraint: :math:`\mathrm{jobv} = \texttt{'V'}` or :math:`\texttt{'N'}`.

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

                Constraint: :math:`\mathrm{jobq} = \texttt{'Q'}` 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{p}`.

                Constraint: :math:`p\geq 0`.

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

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

    .. _f08ve-py2-py-notes:

    **Notes**
        ``dggsvp`` computes orthogonal matrices :math:`U`, :math:`V` and :math:`Q` such that

        .. math::
            \begin{array}{l} U^\mathrm{T}AQ = \left\{\begin{array}{r} \begin{matrix}{}\\k\\l\\m-k-l\end{matrix}\begin{pmatrix}n-k-l&k&l\\0&A_{12}&A_{13}\\0&0&A_{23}\\0&0&0\end{pmatrix} \text{, if }m-k-l\geq 0\text{;} \\ \begin{matrix}{}\\k\\m-k\end{matrix}\begin{pmatrix}n-k-l&k&l\\0&A_{12}&A_{13}\\0&0&A_{23}\end{pmatrix} \text{, if }m-k-l < 0\text{;} \end{array}\right. \\ V^\mathrm{T}BQ = \begin{matrix}{}\\l\\p-l\end{matrix}\begin{pmatrix}n-k-l&k&l\\0&0&B_{13}\\0&0&0\end{pmatrix} \end{array}

        where the :math:`k\times k` matrix :math:`A_{12}` and :math:`l\times l` matrix :math:`B_{13}` are nonsingular upper triangular; :math:`A_{23}` is :math:`l\times l` upper triangular if :math:`m-k-l\geq 0` and is :math:`\left(m-k\right)\times l` upper trapezoidal otherwise. :math:`\left(k+l\right)` is the effective numerical rank of the :math:`\left(m+p\right)\times n` matrix :math:`\begin{pmatrix}A^\mathrm{T}&B^\mathrm{T}\end{pmatrix}^\mathrm{T}`.

        This decomposition is usually used as the preprocessing step for computing the Generalized Singular Value Decomposition (GSVD), see function :meth:`dggsvd`.

    .. _f08ve-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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 dggsvp3(jobu, jobv, jobq, a, b, tola, tolb):
    r"""
    ``dggsvp3`` uses orthogonal transformations to simultaneously reduce the :math:`m\times n` matrix :math:`A` and the :math:`p\times n` matrix :math:`B` to upper triangular form.
    This factorization is usually used as a preprocessing step for computing the generalized singular value decomposition (GSVD).
    For sufficiently large problems, a blocked algorithm is used to make best use of Level 3 BLAS.

    .. _f08vg-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08vgf.html

    .. _f08vg-py2-py-parameters:

    **Parameters**
        **jobu** : str, length 1
            If :math:`\mathrm{jobu} = \texttt{'U'}`, the orthogonal matrix :math:`U` is computed.

            If :math:`\mathrm{jobu} = \texttt{'N'}`, :math:`U` is not computed.

        **jobv** : str, length 1
            If :math:`\mathrm{jobv} = \texttt{'V'}`, the orthogonal matrix :math:`V` is computed.

            If :math:`\mathrm{jobv} = \texttt{'N'}`, :math:`V` is not computed.

        **jobq** : str, length 1
            If :math:`\mathrm{jobq} = \texttt{'Q'}`, the orthogonal matrix :math:`Q` is computed.

            If :math:`\mathrm{jobq} = \texttt{'N'}`, :math:`Q` is not computed.

        **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(p, n\right)`
            The :math:`p\times n` matrix :math:`B`.

        **tola** : float
            :math:`\mathrm{tola}` and :math:`\mathrm{tolb}` are the thresholds to determine the effective numerical rank of matrix :math:`B` and a subblock of :math:`A`. Generally, they are set to

            .. math::
                \begin{array}{c}\mathrm{tola} = \mathrm{max}\left(m, n\right)\left\lVert A\right\rVert \epsilon \text{,}\\\mathrm{tolb} = \mathrm{max}\left(p, n\right)\left\lVert B\right\rVert \epsilon \text{,}\end{array}

            where :math:`\epsilon` is the machine precision.

            The size of :math:`\mathrm{tola}` and :math:`\mathrm{tolb}` may affect the size of backward errors of the decomposition.

        **tolb** : float
            :math:`\mathrm{tola}` and :math:`\mathrm{tolb}` are the thresholds to determine the effective numerical rank of matrix :math:`B` and a subblock of :math:`A`. Generally, they are set to

            .. math::
                \begin{array}{c}\mathrm{tola} = \mathrm{max}\left(m, n\right)\left\lVert A\right\rVert \epsilon \text{,}\\\mathrm{tolb} = \mathrm{max}\left(p, n\right)\left\lVert B\right\rVert \epsilon \text{,}\end{array}

            where :math:`\epsilon` is the machine precision.

            The size of :math:`\mathrm{tola}` and :math:`\mathrm{tolb}` may affect the size of backward errors of the decomposition.

    **Returns**
        **a** : float, ndarray, shape :math:`\left(m, n\right)`
            Contains the triangular (or trapezoidal) matrix described in :ref:`Notes <f08vg-py2-py-notes>`.

        **b** : float, ndarray, shape :math:`\left(p, n\right)`
            Contains the triangular matrix described in :ref:`Notes <f08vg-py2-py-notes>`.

        **k** : int
            :math:`\mathrm{k}` and :math:`\mathrm{l}` specify the dimension of the subblocks :math:`k` and :math:`l` as described in :ref:`Notes <f08vg-py2-py-notes>`; :math:`\left(k+l\right)` is the effective numerical rank of :math:`\begin{pmatrix}\mathrm{a}^\mathrm{T}&\mathrm{b}^\mathrm{T}\end{pmatrix}^\mathrm{T}`.

        **l** : int
            :math:`\mathrm{k}` and :math:`\mathrm{l}` specify the dimension of the subblocks :math:`k` and :math:`l` as described in :ref:`Notes <f08vg-py2-py-notes>`; :math:`\left(k+l\right)` is the effective numerical rank of :math:`\begin{pmatrix}\mathrm{a}^\mathrm{T}&\mathrm{b}^\mathrm{T}\end{pmatrix}^\mathrm{T}`.

        **u** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobu} = \texttt{'U'}`, :math:`\mathrm{u}` contains the orthogonal matrix :math:`U`.

            If :math:`\mathrm{jobu} = \texttt{'N'}`, :math:`\mathrm{u}` is not referenced.

        **v** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobv} = \texttt{'V'}`, :math:`\mathrm{v}` contains the orthogonal matrix :math:`V`.

            If :math:`\mathrm{jobv} = \texttt{'N'}`, :math:`\mathrm{v}` is not referenced.

        **q** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobq} = \texttt{'Q'}`, :math:`\mathrm{q}` contains the orthogonal matrix :math:`Q`.

            If :math:`\mathrm{jobq} = \texttt{'N'}`, :math:`\mathrm{q}` is not referenced.

    .. _f08vg-py2-py-errors:

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

                Constraint: :math:`\mathrm{jobu} = \texttt{'U'}` or :math:`\texttt{'N'}`.

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

                Constraint: :math:`\mathrm{jobv} = \texttt{'V'}` or :math:`\texttt{'N'}`.

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

                Constraint: :math:`\mathrm{jobq} = \texttt{'Q'}` 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{p}`.

                Constraint: :math:`p\geq 0`.

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

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

    .. _f08vg-py2-py-notes:

    **Notes**
        ``dggsvp3`` computes orthogonal matrices :math:`U`, :math:`V` and :math:`Q` such that

        .. math::
            \begin{array}{l} U^\mathrm{T}AQ = \left\{\begin{array}{r} \begin{matrix}{}\\k\\l\\m-k-l\end{matrix}\begin{pmatrix}n-k-l&k&l\\0&A_{12}&A_{13}\\0&0&A_{23}\\0&0&0\end{pmatrix} \text{, if }m-k-l\geq 0\text{;} \\ \begin{matrix}{}\\k\\m-k\end{matrix}\begin{pmatrix}n-k-l&k&l\\0&A_{12}&A_{13}\\0&0&A_{23}\end{pmatrix} \text{, if }m-k-l < 0\text{;} \end{array}\right. \\ V^\mathrm{T}BQ = \begin{matrix}{}\\l\\p-l\end{matrix}\begin{pmatrix}n-k-l&k&l\\0&0&B_{13}\\0&0&0\end{pmatrix} \end{array}

        where the :math:`k\times k` matrix :math:`A_{12}` and :math:`l\times l` matrix :math:`B_{13}` are nonsingular upper triangular; :math:`A_{23}` is :math:`l\times l` upper triangular if :math:`m-k-l\geq 0` and is :math:`\left(m-k\right)\times l` upper trapezoidal otherwise. :math:`\left(k+l\right)` is the effective numerical rank of the :math:`\left(m+p\right)\times n` matrix :math:`\begin{pmatrix}A^\mathrm{T}&B^\mathrm{T}\end{pmatrix}^\mathrm{T}`.

        This decomposition is usually used as the preprocessing step for computing the Generalized Singular Value Decomposition (GSVD), see function :meth:`dtgsja`; the two steps are combined in :meth:`dggsvd3`.

    .. _f08vg-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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, 2012, `Matrix Computations`, (4th Edition), Johns Hopkins University Press, Baltimore
    """
    raise NotImplementedError

def zggsvd(jobu, jobv, jobq, a, b):
    r"""
    ``zggsvd`` computes the generalized singular value decomposition (GSVD) of an :math:`m\times n` complex matrix :math:`A` and a :math:`p\times n` complex matrix :math:`B`. ``zggsvd`` is marked as `deprecated` by LAPACK; the replacement routine is :meth:`zggsvd3` which makes better use of Level 3 BLAS.

    .. deprecated:: 27.0.0.0
        ``zggsvd`` is deprecated.
        Please use :meth:`zggsvd3` instead.
        See also the :ref:`Replacement Calls <replace>` document.

    .. _f08vn-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08vnf.html

    .. _f08vn-py2-py-parameters:

    **Parameters**
        **jobu** : str, length 1
            If :math:`\mathrm{jobu} = \texttt{'U'}`, the unitary matrix :math:`U` is computed.

            If :math:`\mathrm{jobu} = \texttt{'N'}`, :math:`U` is not computed.

        **jobv** : str, length 1
            If :math:`\mathrm{jobv} = \texttt{'V'}`, the unitary matrix :math:`V` is computed.

            If :math:`\mathrm{jobv} = \texttt{'N'}`, :math:`V` is not computed.

        **jobq** : str, length 1
            If :math:`\mathrm{jobq} = \texttt{'Q'}`, the unitary matrix :math:`Q` is computed.

            If :math:`\mathrm{jobq} = \texttt{'N'}`, :math:`Q` is not computed.

        **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(p, n\right)`
            The :math:`p\times n` matrix :math:`B`.

    **Returns**
        **k** : int
            :math:`\mathrm{k}` and :math:`\mathrm{l}` specify the dimension of the subblocks :math:`k` and :math:`l` as described in :ref:`Notes <f08vn-py2-py-notes>`; :math:`\left(k+l\right)` is the effective numerical rank of (A;B).

        **l** : int
            :math:`\mathrm{k}` and :math:`\mathrm{l}` specify the dimension of the subblocks :math:`k` and :math:`l` as described in :ref:`Notes <f08vn-py2-py-notes>`; :math:`\left(k+l\right)` is the effective numerical rank of (A;B).

        **a** : complex, ndarray, shape :math:`\left(m, n\right)`
            Contains the triangular matrix :math:`R`, or part of :math:`R`. See :ref:`Notes <f08vn-py2-py-notes>` for details.

        **b** : complex, ndarray, shape :math:`\left(p, n\right)`
            Contains the triangular matrix :math:`R` if :math:`m-k-l < 0`. See :ref:`Notes <f08vn-py2-py-notes>` for details.

        **alpha** : float, ndarray, shape :math:`\left(n\right)`
            See the description of :math:`\mathrm{beta}`.

        **beta** : float, ndarray, shape :math:`\left(n\right)`
            :math:`\mathrm{alpha}` and :math:`\mathrm{beta}` contain the generalized singular value pairs of :math:`A` and :math:`B`, :math:`\alpha_i` and :math:`\beta_i`;

                :math:`\mathrm{alpha}[0:\mathrm{k}] = 1`,

                :math:`\mathrm{beta}[0:\mathrm{k}] = 0`,

            and if :math:`m-k-l\geq 0`,

                :math:`\mathrm{alpha}[\mathrm{k}:\mathrm{k}+\mathrm{l}] = C`,

                :math:`\mathrm{beta}[\mathrm{k}:\mathrm{k}+\mathrm{l}] = S`,

            or if :math:`m-k-l < 0`,

                :math:`\mathrm{alpha}[\mathrm{k}:m] = C`,

                :math:`\mathrm{alpha}[m:\mathrm{k}+\mathrm{l}] = 0`,

                :math:`\mathrm{beta}[\mathrm{k}:m] = S`,

                :math:`\mathrm{beta}[m:\mathrm{k}+\mathrm{l}] = 1`, and

                :math:`\mathrm{alpha}[\mathrm{k}+\mathrm{l}:n] = 0`,

                :math:`\mathrm{beta}[\mathrm{k}+\mathrm{l}:n] = 0`.

            The notation :math:`\mathrm{alpha}[\mathrm{k}-1:n]` above refers to consecutive elements :math:`\mathrm{alpha}[\textit{i}-1]`, for :math:`\textit{i} = \mathrm{k},\ldots,n`.

        **u** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobu} = \texttt{'U'}`, :math:`\mathrm{u}` contains the :math:`m\times m` unitary matrix :math:`U`.

            If :math:`\mathrm{jobu} = \texttt{'N'}`, :math:`\mathrm{u}` is not referenced.

        **v** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobv} = \texttt{'V'}`, :math:`\mathrm{v}` contains the :math:`p\times p` unitary matrix :math:`V`.

            If :math:`\mathrm{jobv} = \texttt{'N'}`, :math:`\mathrm{v}` is not referenced.

        **q** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobq} = \texttt{'Q'}`, :math:`\mathrm{q}` contains the :math:`n\times n` unitary matrix :math:`Q`.

            If :math:`\mathrm{jobq} = \texttt{'N'}`, :math:`\mathrm{q}` is not referenced.

        **iwork** : int, ndarray, shape :math:`\left(n\right)`
            Stores the sorting information. More precisely, the following loop will sort :math:`\mathrm{alpha}`

            ::

              for i in range(k+1, min(m,k+l)+1):
                swap alpha[i-1] and alpha[iwork[i-1]-1]

            such that :math:`\mathrm{alpha}[0]\geq \mathrm{alpha}[1]\geq \cdots \geq \mathrm{alpha}[n-1]`.

    .. _f08vn-py2-py-errors:

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

                Constraint: :math:`\mathrm{jobu} = \texttt{'U'}` or :math:`\texttt{'N'}`.

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

                Constraint: :math:`\mathrm{jobv} = \texttt{'V'}` or :math:`\texttt{'N'}`.

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

                Constraint: :math:`\mathrm{jobq} = \texttt{'Q'}` 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:`n\geq 0`.

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

                Constraint: :math:`p\geq 0`.

            (`errno` :math:`1`)
                The Jacobi-type procedure failed to converge.

    .. _f08vn-py2-py-notes:

    **Notes**
        The generalized singular value decomposition is given by

        .. math::
            U^\mathrm{H}AQ = D_1\begin{pmatrix}0&R\end{pmatrix}\text{, }\quad V^\mathrm{H}BQ = D_2\begin{pmatrix}0&R\end{pmatrix}\text{,}

        where :math:`U`, :math:`V` and :math:`Q` are unitary matrices.
        Let :math:`\left(k+l\right)` be the effective numerical rank of the matrix (A;B), then :math:`R` is a :math:`\left(k+l\right)\times \left(k+l\right)` nonsingular upper triangular matrix, :math:`D_1` and :math:`D_2` are :math:`m\times \left(k+l\right)` and :math:`p\times \left(k+l\right)` 'diagonal' matrices structured as follows:

        if :math:`m-k-l\geq 0`,

        .. math::
            D_1 = \begin{matrix}{}\\k\\l\\m-k-l\end{matrix}\begin{pmatrix}k&l\\I&0\\0&C\\0&0\end{pmatrix}

        .. math::
            D_2 = \begin{matrix}{}\\l\\p-l\end{matrix}\begin{pmatrix}k&l\\0&S\\0&0\end{pmatrix}

        .. math::
            \begin{pmatrix}0&R\end{pmatrix} = \begin{matrix}{}\\k\\l\end{matrix}\begin{pmatrix}n-k-l&k&l\\0&R_{11}&R_{12}\\0&0&R_{22}\end{pmatrix}

        where

        .. math::
            C = \mathrm{diag}\left(\alpha_{{k+1}}, \ldots, \alpha_{{k+l}}\right)\text{,}

        .. math::
            S = \mathrm{diag}\left(\beta_{{k+1}}, \ldots, \beta_{{k+l}}\right)\text{,}

        and

        .. math::
            C^2+S^2 = I\text{.}

        :math:`R` is stored as a submatrix of :math:`A` with elements :math:`R_{{ij}}` stored as :math:`A_{{i,n-k-l+j}}` on exit.

        If :math:`m-k-l < 0`,

        .. math::
            D_1 = \begin{matrix}{}\\k\\m-k\end{matrix}\begin{pmatrix}k&m-k&k+l-m\\I&0&0\\0&C&0\end{pmatrix}

        .. math::
            D_2 = \begin{matrix}{}\\m-k\\k+l-m\\p-l\end{matrix}\begin{pmatrix}k&m-k&k+l-m\\0&S&0\\0&0&I\\0&0&0\end{pmatrix}

        .. math::
            \begin{pmatrix}0&R\end{pmatrix} = \begin{matrix}{}\\k\\m-k\\k+l-m\end{matrix}\begin{pmatrix}n-k-l&k&m-k&k+l-m\\0&R_{11}&R_{12}&R_{13}\\0&0&R_{22}&R_{23}\\0&0&0&R_{33}\end{pmatrix}

        where

        .. math::
            C = \mathrm{diag}\left(\alpha_{{k+1}}, \ldots, \alpha_m\right)\text{,}

        .. math::
            S = \mathrm{diag}\left(\beta_{{k+1}}, \ldots, \beta_m\right)\text{,}

        and

        .. math::
            C^2+S^2 = I\text{.}

        :math:`\begin{pmatrix}R_{11}&R_{12}&R_{13}\\0&R_{22}&R_{23}\end{pmatrix}` is stored as a submatrix of :math:`A` with :math:`R_{{ij}}` stored as :math:`A_{{i,n-k-l+j}}`, and :math:`R_{33}` is stored as a submatrix of :math:`B` with :math:`\left(R_{33}\right)_{{ij}}` stored as :math:`B_{{m-k+i,n+m-k-l+j}}`.

        The function computes :math:`C`, :math:`S`, :math:`R` and, optionally, the unitary transformation matrices :math:`U`, :math:`V` and :math:`Q`.

        In particular, if :math:`B` is an :math:`n\times n` nonsingular matrix, then the GSVD of :math:`A` and :math:`B` implicitly gives the SVD of :math:`A\times B^{-1}`:

        .. math::
            AB^{-1} = U\left(D_1D_2^{-1}\right)V^\mathrm{H}\text{.}

        If (A;B) has orthonormal columns, then the GSVD of :math:`A` and :math:`B` is also equal to the CS decomposition of :math:`A` and :math:`B`.
        Furthermore, the GSVD can be used to derive the solution of the eigenvalue problem:

        .. math::
            A^\mathrm{H}Ax = \lambda B^\mathrm{H}Bx\text{.}

        In some literature, the GSVD of :math:`A` and :math:`B` is presented in the form

        .. math::
            U^\mathrm{H}AX = \begin{pmatrix}0&D_1\end{pmatrix}\text{, }\quad V^\mathrm{H}BX = \begin{pmatrix}0&D_2\end{pmatrix}\text{,}

        where :math:`U` and :math:`V` are orthogonal and :math:`X` is nonsingular, and :math:`D_1` and :math:`D_2` are 'diagonal'.
        The former GSVD form can be converted to the latter form by taking the nonsingular matrix :math:`X` as

        .. math::
            X = Q\begin{pmatrix}I&0\\0&R^{-1}\end{pmatrix}\text{.}

    .. _f08vn-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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 zggsvd3(jobu, jobv, jobq, a, b):
    r"""
    ``zggsvd3`` computes the generalized singular value decomposition (GSVD) of an :math:`m\times n` complex matrix :math:`A` and a :math:`p\times n` complex matrix :math:`B`.

    .. _f08vq-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08vqf.html

    .. _f08vq-py2-py-parameters:

    **Parameters**
        **jobu** : str, length 1
            If :math:`\mathrm{jobu} = \texttt{'U'}`, the unitary matrix :math:`U` is computed.

            If :math:`\mathrm{jobu} = \texttt{'N'}`, :math:`U` is not computed.

        **jobv** : str, length 1
            If :math:`\mathrm{jobv} = \texttt{'V'}`, the unitary matrix :math:`V` is computed.

            If :math:`\mathrm{jobv} = \texttt{'N'}`, :math:`V` is not computed.

        **jobq** : str, length 1
            If :math:`\mathrm{jobq} = \texttt{'Q'}`, the unitary matrix :math:`Q` is computed.

            If :math:`\mathrm{jobq} = \texttt{'N'}`, :math:`Q` is not computed.

        **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(p, n\right)`
            The :math:`p\times n` matrix :math:`B`.

    **Returns**
        **k** : int
            :math:`\mathrm{k}` and :math:`\mathrm{l}` specify the dimension of the subblocks :math:`k` and :math:`l` as described in :ref:`Notes <f08vq-py2-py-notes>`; :math:`\left(k+l\right)` is the effective numerical rank of (A;B).

        **l** : int
            :math:`\mathrm{k}` and :math:`\mathrm{l}` specify the dimension of the subblocks :math:`k` and :math:`l` as described in :ref:`Notes <f08vq-py2-py-notes>`; :math:`\left(k+l\right)` is the effective numerical rank of (A;B).

        **a** : complex, ndarray, shape :math:`\left(m, n\right)`
            Contains the triangular matrix :math:`R`, or part of :math:`R`. See :ref:`Notes <f08vq-py2-py-notes>` for details.

        **b** : complex, ndarray, shape :math:`\left(p, n\right)`
            Contains the triangular matrix :math:`R` if :math:`m-k-l < 0`. See :ref:`Notes <f08vq-py2-py-notes>` for details.

        **alpha** : float, ndarray, shape :math:`\left(n\right)`
            See the description of :math:`\mathrm{beta}`.

        **beta** : float, ndarray, shape :math:`\left(n\right)`
            :math:`\mathrm{alpha}` and :math:`\mathrm{beta}` contain the generalized singular value pairs of :math:`A` and :math:`B`, :math:`\alpha_i` and :math:`\beta_i`;

                :math:`\mathrm{alpha}[0:\mathrm{k}] = 1`,

                :math:`\mathrm{beta}[0:\mathrm{k}] = 0`,

            and if :math:`m-k-l\geq 0`,

                :math:`\mathrm{alpha}[\mathrm{k}:\mathrm{k}+\mathrm{l}] = C`,

                :math:`\mathrm{beta}[\mathrm{k}:\mathrm{k}+\mathrm{l}] = S`,

            or if :math:`m-k-l < 0`,

                :math:`\mathrm{alpha}[\mathrm{k}:m] = C`,

                :math:`\mathrm{alpha}[m:\mathrm{k}+\mathrm{l}] = 0`,

                :math:`\mathrm{beta}[\mathrm{k}:m] = S`,

                :math:`\mathrm{beta}[m:\mathrm{k}+\mathrm{l}] = 1`, and

                :math:`\mathrm{alpha}[\mathrm{k}+\mathrm{l}:n] = 0`,

                :math:`\mathrm{beta}[\mathrm{k}+\mathrm{l}:n] = 0`.

            The notation :math:`\mathrm{alpha}[\mathrm{k}-1:n]` above refers to consecutive elements :math:`\mathrm{alpha}[\textit{i}-1]`, for :math:`\textit{i} = \mathrm{k},\ldots,n`.

        **u** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobu} = \texttt{'U'}`, :math:`\mathrm{u}` contains the :math:`m\times m` unitary matrix :math:`U`.

            If :math:`\mathrm{jobu} = \texttt{'N'}`, :math:`\mathrm{u}` is not referenced.

        **v** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobv} = \texttt{'V'}`, :math:`\mathrm{v}` contains the :math:`p\times p` unitary matrix :math:`V`.

            If :math:`\mathrm{jobv} = \texttt{'N'}`, :math:`\mathrm{v}` is not referenced.

        **q** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobq} = \texttt{'Q'}`, :math:`\mathrm{q}` contains the :math:`n\times n` unitary matrix :math:`Q`.

            If :math:`\mathrm{jobq} = \texttt{'N'}`, :math:`\mathrm{q}` is not referenced.

        **iwork** : int, ndarray, shape :math:`\left(n\right)`
            Stores the sorting information. More precisely, if :math:`I` is the ordered set of indices of :math:`\mathrm{alpha}` containing :math:`C` (denote as :math:`\mathrm{alpha}[I]`, see :math:`\mathrm{beta}`), then the corresponding elements :math:`\mathrm{iwork}[I]-1` contain the swap pivots, :math:`J`, that sorts :math:`I` such that :math:`\mathrm{alpha}[I]` is in descending numerical order.

            The following pseudocode sorts the set :math:`I`:

            :math:`\begin{array}{l}\text{for }i \in I\\\hspace{2em} j = J_i\\\hspace{2em} \text{swap }I_i\text{ and }I_j\\\text{end}\end{array}`

    .. _f08vq-py2-py-errors:

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

                Constraint: :math:`\mathrm{jobu} = \texttt{'U'}` or :math:`\texttt{'N'}`.

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

                Constraint: :math:`\mathrm{jobv} = \texttt{'V'}` or :math:`\texttt{'N'}`.

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

                Constraint: :math:`\mathrm{jobq} = \texttt{'Q'}` 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:`n\geq 0`.

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

                Constraint: :math:`p\geq 0`.

            (`errno` :math:`1`)
                The Jacobi-type procedure failed to converge.

    .. _f08vq-py2-py-notes:

    **Notes**
        Given an :math:`m\times n` complex matrix :math:`A` and a :math:`p\times n` complex matrix :math:`B`, the generalized singular value decomposition is given by

        .. math::
            U^\mathrm{H}AQ = D_1\begin{pmatrix}0&R\end{pmatrix}\text{, }\quad V^\mathrm{H}BQ = D_2\begin{pmatrix}0&R\end{pmatrix}\text{,}

        where :math:`U`, :math:`V` and :math:`Q` are unitary matrices.
        Let :math:`l` be the effective numerical rank of :math:`B` and :math:`\left(k+l\right)` be the effective numerical rank of the matrix (A;B), then the first :math:`k` generalized singular values are infinite and the remaining :math:`l` are finite. :math:`R` is a :math:`\left(k+l\right)\times \left(k+l\right)` nonsingular upper triangular matrix, :math:`D_1` and :math:`D_2` are :math:`m\times \left(k+l\right)` and :math:`p\times \left(k+l\right)` 'diagonal' matrices structured as follows:

        if :math:`m-k-l\geq 0`,

        .. math::
            D_1 = \begin{matrix}{}\\k\\l\\m-k-l\end{matrix}\begin{pmatrix}k&l\\I&0\\0&C\\0&0\end{pmatrix}

        .. math::
            D_2 = \begin{matrix}{}\\l\\p-l\end{matrix}\begin{pmatrix}k&l\\0&S\\0&0\end{pmatrix}

        .. math::
            \begin{pmatrix}0&R\end{pmatrix} = \begin{matrix}{}\\k\\l\end{matrix}\begin{pmatrix}n-k-l&k&l\\0&R_{11}&R_{12}\\0&0&R_{22}\end{pmatrix}

        where

        .. math::
            C = \mathrm{diag}\left(\alpha_{{k+1}}, \ldots, \alpha_{{k+l}}\right)\text{,}

        .. math::
            S = \mathrm{diag}\left(\beta_{{k+1}}, \ldots, \beta_{{k+l}}\right)\text{,}

        and

        .. math::
            C^2+S^2 = I\text{.}

        :math:`R` is stored as a submatrix of :math:`A` with elements :math:`R_{{ij}}` stored as :math:`A_{{i,n-k-l+j}}` on exit.

        If :math:`m-k-l < 0`,

        .. math::
            D_1 = \begin{matrix}{}\\k\\m-k\end{matrix}\begin{pmatrix}k&m-k&k+l-m\\I&0&0\\0&C&0\end{pmatrix}

        .. math::
            D_2 = \begin{matrix}{}\\m-k\\k+l-m\\p-l\end{matrix}\begin{pmatrix}k&m-k&k+l-m\\0&S&0\\0&0&I\\0&0&0\end{pmatrix}

        .. math::
            \begin{pmatrix}0&R\end{pmatrix} = \begin{matrix}{}\\k\\m-k\\k+l-m\end{matrix}\begin{pmatrix}n-k-l&k&m-k&k+l-m\\0&R_{11}&R_{12}&R_{13}\\0&0&R_{22}&R_{23}\\0&0&0&R_{33}\end{pmatrix}

        where

        .. math::
            C = \mathrm{diag}\left(\alpha_{{k+1}}, \ldots, \alpha_m\right)\text{,}

        .. math::
            S = \mathrm{diag}\left(\beta_{{k+1}}, \ldots, \beta_m\right)\text{,}

        and

        .. math::
            C^2+S^2 = I\text{.}

        :math:`\begin{pmatrix}R_{11}&R_{12}&R_{13}\\0&R_{22}&R_{23}\end{pmatrix}` is stored as a submatrix of :math:`A` with :math:`R_{{ij}}` stored as :math:`A_{{i,n-k-l+j}}`, and :math:`R_{33}` is stored as a submatrix of :math:`B` with :math:`\left(R_{33}\right)_{{ij}}` stored as :math:`B_{{m-k+i,n+m-k-l+j}}`.

        The function computes :math:`C`, :math:`S`, :math:`R` and, optionally, the unitary transformation matrices :math:`U`, :math:`V` and :math:`Q`.

        In particular, if :math:`B` is an :math:`n\times n` nonsingular matrix, then the GSVD of :math:`A` and :math:`B` implicitly gives the SVD of :math:`A\times B^{-1}`:

        .. math::
            AB^{-1} = U\left(D_1D_2^{-1}\right)V^\mathrm{H}\text{.}

        If (A;B) has orthonormal columns, then the GSVD of :math:`A` and :math:`B` is also equal to the CS decomposition of :math:`A` and :math:`B`.
        Furthermore, the GSVD can be used to derive the solution of the eigenvalue problem:

        .. math::
            A^\mathrm{H}Ax = \lambda B^\mathrm{H}Bx\text{.}

        In some literature, the GSVD of :math:`A` and :math:`B` is presented in the form

        .. math::
            U^\mathrm{H}AX = \begin{pmatrix}0&D_1\end{pmatrix}\text{, }\quad V^\mathrm{H}BX = \begin{pmatrix}0&D_2\end{pmatrix}\text{,}

        where :math:`U` and :math:`V` are orthogonal and :math:`X` is nonsingular, and :math:`D_1` and :math:`D_2` are 'diagonal'.
        The former GSVD form can be converted to the latter form by setting

        .. math::
            X = Q\begin{pmatrix}I&0\\0&R^{-1}\end{pmatrix}\text{.}

        A two stage process is used to compute the GSVD of the matrix pair :math:`\left(A, B\right)`.
        The pair is first reduced to upper triangular form by unitary transformations using :meth:`zggsvp3`.
        The GSVD of the resulting upper triangular matrix pair is then performed by :meth:`ztgsja` which uses a variant of the Kogbetliantz algorithm (a cyclic Jacobi method).

    .. _f08vq-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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, 2012, `Matrix Computations`, (4th Edition), Johns Hopkins University Press, Baltimore
    """
    raise NotImplementedError

def zggsvp(jobu, jobv, jobq, a, b, tola, tolb):
    r"""
    ``zggsvp`` uses unitary transformations to simultaneously reduce the :math:`m\times n` matrix :math:`A` and the :math:`p\times n` matrix :math:`B` to upper triangular form.
    This factorization is usually used as a preprocessing step for computing the generalized singular value decomposition (GSVD). ``zggsvp`` is marked as `deprecated` by LAPACK; the replacement routine is :meth:`zggsvp3` which makes better use of Level 3 BLAS.

    .. deprecated:: 27.0.0.0
        ``zggsvp`` is deprecated.
        Please use :meth:`zggsvp3` instead.
        See also the :ref:`Replacement Calls <replace>` document.

    .. _f08vs-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08vsf.html

    .. _f08vs-py2-py-parameters:

    **Parameters**
        **jobu** : str, length 1
            If :math:`\mathrm{jobu} = \texttt{'U'}`, the unitary matrix :math:`U` is computed.

            If :math:`\mathrm{jobu} = \texttt{'N'}`, :math:`U` is not computed.

        **jobv** : str, length 1
            If :math:`\mathrm{jobv} = \texttt{'V'}`, the unitary matrix :math:`V` is computed.

            If :math:`\mathrm{jobv} = \texttt{'N'}`, :math:`V` is not computed.

        **jobq** : str, length 1
            If :math:`\mathrm{jobq} = \texttt{'Q'}`, the unitary matrix :math:`Q` is computed.

            If :math:`\mathrm{jobq} = \texttt{'N'}`, :math:`Q` is not computed.

        **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(p, n\right)`
            The :math:`p\times n` matrix :math:`B`.

        **tola** : float
            :math:`\mathrm{tola}` and :math:`\mathrm{tolb}` are the thresholds to determine the effective numerical rank of matrix :math:`B` and a subblock of :math:`A`. Generally, they are set to

            .. math::
                \begin{array}{c}\mathrm{tola} = \mathrm{max}\left(m, n\right)\left\lVert A\right\rVert \epsilon \text{,}\\\mathrm{tolb} = \mathrm{max}\left(p, n\right)\left\lVert B\right\rVert \epsilon \text{,}\end{array}

            where :math:`\epsilon` is the machine precision.

            The size of :math:`\mathrm{tola}` and :math:`\mathrm{tolb}` may affect the size of backward errors of the decomposition.

        **tolb** : float
            :math:`\mathrm{tola}` and :math:`\mathrm{tolb}` are the thresholds to determine the effective numerical rank of matrix :math:`B` and a subblock of :math:`A`. Generally, they are set to

            .. math::
                \begin{array}{c}\mathrm{tola} = \mathrm{max}\left(m, n\right)\left\lVert A\right\rVert \epsilon \text{,}\\\mathrm{tolb} = \mathrm{max}\left(p, n\right)\left\lVert B\right\rVert \epsilon \text{,}\end{array}

            where :math:`\epsilon` is the machine precision.

            The size of :math:`\mathrm{tola}` and :math:`\mathrm{tolb}` may affect the size of backward errors of the decomposition.

    **Returns**
        **a** : complex, ndarray, shape :math:`\left(m, n\right)`
            Contains the triangular (or trapezoidal) matrix described in :ref:`Notes <f08vs-py2-py-notes>`.

        **b** : complex, ndarray, shape :math:`\left(p, n\right)`
            Contains the triangular matrix described in :ref:`Notes <f08vs-py2-py-notes>`.

        **k** : int
            :math:`\mathrm{k}` and :math:`\mathrm{l}` specify the dimension of the subblocks :math:`k` and :math:`l` as described in :ref:`Notes <f08vs-py2-py-notes>`; :math:`\left(k+l\right)` is the effective numerical rank of :math:`\begin{pmatrix}\mathrm{a}^\mathrm{T}&\mathrm{b}^\mathrm{T}\end{pmatrix}^\mathrm{T}`.

        **l** : int
            :math:`\mathrm{k}` and :math:`\mathrm{l}` specify the dimension of the subblocks :math:`k` and :math:`l` as described in :ref:`Notes <f08vs-py2-py-notes>`; :math:`\left(k+l\right)` is the effective numerical rank of :math:`\begin{pmatrix}\mathrm{a}^\mathrm{T}&\mathrm{b}^\mathrm{T}\end{pmatrix}^\mathrm{T}`.

        **u** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobu} = \texttt{'U'}`, :math:`\mathrm{u}` contains the unitary matrix :math:`U`.

            If :math:`\mathrm{jobu} = \texttt{'N'}`, :math:`\mathrm{u}` is not referenced.

        **v** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobv} = \texttt{'V'}`, :math:`\mathrm{v}` contains the unitary matrix :math:`V`.

            If :math:`\mathrm{jobv} = \texttt{'N'}`, :math:`\mathrm{v}` is not referenced.

        **q** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobq} = \texttt{'Q'}`, :math:`\mathrm{q}` contains the unitary matrix :math:`Q`.

            If :math:`\mathrm{jobq} = \texttt{'N'}`, :math:`\mathrm{q}` is not referenced.

    .. _f08vs-py2-py-errors:

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

                Constraint: :math:`\mathrm{jobu} = \texttt{'U'}` or :math:`\texttt{'N'}`.

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

                Constraint: :math:`\mathrm{jobv} = \texttt{'V'}` or :math:`\texttt{'N'}`.

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

                Constraint: :math:`\mathrm{jobq} = \texttt{'Q'}` 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{p}`.

                Constraint: :math:`p\geq 0`.

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

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

    .. _f08vs-py2-py-notes:

    **Notes**
        ``zggsvp`` computes unitary matrices :math:`U`, :math:`V` and :math:`Q` such that

        .. math::
            \begin{array}{l} U^\mathrm{H}AQ = \left\{\begin{array}{r} \begin{matrix}{}\\k\\l\\m-k-l\end{matrix}\begin{pmatrix}n-k-l&k&l\\0&A_{12}&A_{13}\\0&0&A_{23}\\0&0&0\end{pmatrix} \text{, if }m-k-l\geq 0\text{;} \\ \begin{matrix}{}\\k\\m-k\end{matrix}\begin{pmatrix}n-k-l&k&l\\0&A_{12}&A_{13}\\0&0&A_{23}\end{pmatrix} \text{, if }m-k-l < 0\text{;} \end{array}\right. \\ V^\mathrm{H}BQ = \begin{matrix}{}\\l\\p-l\end{matrix}\begin{pmatrix}n-k-l&k&l\\0&0&B_{13}\\0&0&0\end{pmatrix} \end{array}

        where the :math:`k\times k` matrix :math:`A_{12}` and :math:`l\times l` matrix :math:`B_{13}` are nonsingular upper triangular; :math:`A_{23}` is :math:`l\times l` upper triangular if :math:`m-k-l\geq 0` and is :math:`\left(m-k\right)\times l` upper trapezoidal otherwise. :math:`\left(k+l\right)` is the effective numerical rank of the :math:`\left(m+p\right)\times n` matrix :math:`\begin{pmatrix}A^\mathrm{H}&B^\mathrm{H}\end{pmatrix}^\mathrm{H}`.

        This decomposition is usually used as the preprocessing step for computing the Generalized Singular Value Decomposition (GSVD), see function :meth:`zggsvd`.

    .. _f08vs-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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 zggsvp3(jobu, jobv, jobq, a, b, tola, tolb):
    r"""
    ``zggsvp3`` uses unitary transformations to simultaneously reduce the :math:`m\times n` matrix :math:`A` and the :math:`p\times n` matrix :math:`B` to upper triangular form.
    This factorization is usually used as a preprocessing step for computing the generalized singular value decomposition (GSVD).
    For sufficiently large problems, a blocked algorithm is used to make best use of Level 3 BLAS.

    .. _f08vu-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08vuf.html

    .. _f08vu-py2-py-parameters:

    **Parameters**
        **jobu** : str, length 1
            If :math:`\mathrm{jobu} = \texttt{'U'}`, the unitary matrix :math:`U` is computed.

            If :math:`\mathrm{jobu} = \texttt{'N'}`, :math:`U` is not computed.

        **jobv** : str, length 1
            If :math:`\mathrm{jobv} = \texttt{'V'}`, the unitary matrix :math:`V` is computed.

            If :math:`\mathrm{jobv} = \texttt{'N'}`, :math:`V` is not computed.

        **jobq** : str, length 1
            If :math:`\mathrm{jobq} = \texttt{'Q'}`, the unitary matrix :math:`Q` is computed.

            If :math:`\mathrm{jobq} = \texttt{'N'}`, :math:`Q` is not computed.

        **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(p, n\right)`
            The :math:`p\times n` matrix :math:`B`.

        **tola** : float
            :math:`\mathrm{tola}` and :math:`\mathrm{tolb}` are the thresholds to determine the effective numerical rank of matrix :math:`B` and a subblock of :math:`A`. Generally, they are set to

            .. math::
                \begin{array}{c}\mathrm{tola} = \mathrm{max}\left(m, n\right)\left\lVert A\right\rVert \epsilon \text{,}\\\mathrm{tolb} = \mathrm{max}\left(p, n\right)\left\lVert B\right\rVert \epsilon \text{,}\end{array}

            where :math:`\epsilon` is the machine precision.

            The size of :math:`\mathrm{tola}` and :math:`\mathrm{tolb}` may affect the size of backward errors of the decomposition.

        **tolb** : float
            :math:`\mathrm{tola}` and :math:`\mathrm{tolb}` are the thresholds to determine the effective numerical rank of matrix :math:`B` and a subblock of :math:`A`. Generally, they are set to

            .. math::
                \begin{array}{c}\mathrm{tola} = \mathrm{max}\left(m, n\right)\left\lVert A\right\rVert \epsilon \text{,}\\\mathrm{tolb} = \mathrm{max}\left(p, n\right)\left\lVert B\right\rVert \epsilon \text{,}\end{array}

            where :math:`\epsilon` is the machine precision.

            The size of :math:`\mathrm{tola}` and :math:`\mathrm{tolb}` may affect the size of backward errors of the decomposition.

    **Returns**
        **a** : complex, ndarray, shape :math:`\left(m, n\right)`
            Contains the triangular (or trapezoidal) matrix described in :ref:`Notes <f08vu-py2-py-notes>`.

        **b** : complex, ndarray, shape :math:`\left(p, n\right)`
            Contains the triangular matrix described in :ref:`Notes <f08vu-py2-py-notes>`.

        **k** : int
            :math:`\mathrm{k}` and :math:`\mathrm{l}` specify the dimension of the subblocks :math:`k` and :math:`l` as described in :ref:`Notes <f08vu-py2-py-notes>`; :math:`\left(k+l\right)` is the effective numerical rank of :math:`\begin{pmatrix}\mathrm{a}^\mathrm{T}&\mathrm{b}^\mathrm{T}\end{pmatrix}^\mathrm{T}`.

        **l** : int
            :math:`\mathrm{k}` and :math:`\mathrm{l}` specify the dimension of the subblocks :math:`k` and :math:`l` as described in :ref:`Notes <f08vu-py2-py-notes>`; :math:`\left(k+l\right)` is the effective numerical rank of :math:`\begin{pmatrix}\mathrm{a}^\mathrm{T}&\mathrm{b}^\mathrm{T}\end{pmatrix}^\mathrm{T}`.

        **u** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobu} = \texttt{'U'}`, :math:`\mathrm{u}` contains the unitary matrix :math:`U`.

            If :math:`\mathrm{jobu} = \texttt{'N'}`, :math:`\mathrm{u}` is not referenced.

        **v** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobv} = \texttt{'V'}`, :math:`\mathrm{v}` contains the unitary matrix :math:`V`.

            If :math:`\mathrm{jobv} = \texttt{'N'}`, :math:`\mathrm{v}` is not referenced.

        **q** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobq} = \texttt{'Q'}`, :math:`\mathrm{q}` contains the unitary matrix :math:`Q`.

            If :math:`\mathrm{jobq} = \texttt{'N'}`, :math:`\mathrm{q}` is not referenced.

    .. _f08vu-py2-py-errors:

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

                Constraint: :math:`\mathrm{jobu} = \texttt{'U'}` or :math:`\texttt{'N'}`.

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

                Constraint: :math:`\mathrm{jobv} = \texttt{'V'}` or :math:`\texttt{'N'}`.

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

                Constraint: :math:`\mathrm{jobq} = \texttt{'Q'}` 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{p}`.

                Constraint: :math:`p\geq 0`.

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

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

    .. _f08vu-py2-py-notes:

    **Notes**
        ``zggsvp3`` computes unitary matrices :math:`U`, :math:`V` and :math:`Q` such that

        .. math::
            \begin{array}{l} U^\mathrm{H}AQ = \left\{\begin{array}{r} \begin{matrix}{}\\k\\l\\m-k-l\end{matrix}\begin{pmatrix}n-k-l&k&l\\0&A_{12}&A_{13}\\0&0&A_{23}\\0&0&0\end{pmatrix} \text{, if }m-k-l\geq 0\text{;} \\ \begin{matrix}{}\\k\\m-k\end{matrix}\begin{pmatrix}n-k-l&k&l\\0&A_{12}&A_{13}\\0&0&A_{23}\end{pmatrix} \text{, if }m-k-l < 0\text{;} \end{array}\right. \\ V^\mathrm{H}BQ = \begin{matrix}{}\\l\\p-l\end{matrix}\begin{pmatrix}n-k-l&k&l\\0&0&B_{13}\\0&0&0\end{pmatrix} \end{array}

        where the :math:`k\times k` matrix :math:`A_{12}` and :math:`l\times l` matrix :math:`B_{13}` are nonsingular upper triangular; :math:`A_{23}` is :math:`l\times l` upper triangular if :math:`m-k-l\geq 0` and is :math:`\left(m-k\right)\times l` upper trapezoidal otherwise. :math:`\left(k+l\right)` is the effective numerical rank of the :math:`\left(m+p\right)\times n` matrix :math:`\begin{pmatrix}A^\mathrm{H}&B^\mathrm{H}\end{pmatrix}^\mathrm{H}`.

        This decomposition is usually used as the preprocessing step for computing the Generalized Singular Value Decomposition (GSVD), see function :meth:`ztgsja`; the two steps are combined in :meth:`zggsvd3`.

    .. _f08vu-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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, 2012, `Matrix Computations`, (4th Edition), Johns Hopkins University Press, Baltimore
    """
    raise NotImplementedError

def dggev(jobvl, jobvr, a, b):
    r"""
    ``dggev`` computes for a pair of :math:`n\times n` real nonsymmetric matrices :math:`\left(A, B\right)` the generalized eigenvalues and, optionally, the left and/or right generalized eigenvectors using the :math:`QZ` algorithm. ``dggev`` is marked as `deprecated` by LAPACK; the replacement routine is :meth:`dggev3` which makes better use of Level 3 BLAS.

    .. deprecated:: 27.0.0.0
        ``dggev`` is deprecated.
        Please use :meth:`dggev3` instead.
        See also the :ref:`Replacement Calls <replace>` document.

    .. _f08wa-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08waf.html

    .. _f08wa-py2-py-parameters:

    **Parameters**
        **jobvl** : str, length 1
            If :math:`\mathrm{jobvl} = \texttt{'N'}`, do not compute the left generalized eigenvectors.

            If :math:`\mathrm{jobvl} = \texttt{'V'}`, compute the left generalized eigenvectors.

        **jobvr** : str, length 1
            If :math:`\mathrm{jobvr} = \texttt{'N'}`, do not compute the right generalized eigenvectors.

            If :math:`\mathrm{jobvr} = \texttt{'V'}`, compute the right generalized eigenvectors.

        **a** : float, array-like, shape :math:`\left(n, n\right)`
            The matrix :math:`A` in the pair :math:`\left(A, B\right)`.

        **b** : float, array-like, shape :math:`\left(n, n\right)`
            The matrix :math:`B` in the pair :math:`\left(A, B\right)`.

    **Returns**
        **a** : float, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{a}` has been overwritten.

        **b** : float, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{b}` has been overwritten.

        **alphar** : float, ndarray, shape :math:`\left(n\right)`
            The element :math:`\mathrm{alphar}[j-1]` contains the real part of :math:`\alpha_j`.

        **alphai** : float, ndarray, shape :math:`\left(n\right)`
            The element :math:`\mathrm{alphai}[j-1]` contains the imaginary part of :math:`\alpha_j`.

        **beta** : float, ndarray, shape :math:`\left(n\right)`
            :math:`\left(\mathrm{alphar}[\textit{j}-1]+\mathrm{alphai}[\textit{j}-1]\times i\right)/\mathrm{beta}[\textit{j}-1]`, for :math:`\textit{j} = 1,2,\ldots,n`, will be the generalized eigenvalues.

            If :math:`\mathrm{alphai}[j-1]` is zero, then the :math:`j`\ th eigenvalue is real; if positive, then the :math:`j`\ th and :math:`\left(j+1\right)`\ st eigenvalues are a complex conjugate pair, with :math:`\mathrm{alphai}[j]` negative.

            **Note:** the quotients :math:`\mathrm{alphar}[j-1]/\mathrm{beta}[j-1]` and :math:`\mathrm{alphai}[j-1]/\mathrm{beta}[j-1]` may easily overflow or underflow, and :math:`\mathrm{beta}[j-1]` may even be zero.

            Thus, you should avoid naively computing the ratio :math:`\alpha_j/\beta_j`.

            However, :math:`\mathrm{max}\left(\left\lvert \alpha_j\right\rvert \right)` will always be less than and usually comparable with :math:`\left\lVert A\right\rVert_2` in magnitude, and :math:`\mathrm{max}\left(\left\lvert \beta_j\right\rvert \right)` will always be less than and usually comparable with :math:`\left\lVert B\right\rVert_2`.

        **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 the corresponding eigenvalues.

            If the :math:`j`\ th eigenvalue is real, then :math:`u_j = \mathrm{vl}[:,j]`, the :math:`j`\ th column of :math:`\mathrm{vl}`.

            If the :math:`j`\ th and :math:`\left(j+1\right)`\ th eigenvalues form a complex conjugate pair, then :math:`u_j = \mathrm{vl}[:,j]+i\times \mathrm{vl}[:,j+1]` and :math:`u\left(j+1\right) = \mathrm{vl}[:,j]-i\times \mathrm{vl}[:,j+1]`.

            Each eigenvector will be scaled so the largest component has :math:`\left\lvert \text{real part}\right\rvert +\left\lvert \text{imag. part}\right\rvert = 1`.

            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 the corresponding eigenvalues.

            If the :math:`j`\ th eigenvalue is real, then :math:`v_j = \mathrm{vr}[:,j]`, the :math:`j`\ th column of :math:`\mathrm{VR}`.

            If the :math:`j`\ th and :math:`\left(j+1\right)`\ th eigenvalues form a complex conjugate pair, then :math:`v_j = \mathrm{vr}[:,j]+i\times \mathrm{vr}[:,j+1]` and :math:`v_{{j+1}} = \mathrm{vr}[:,j]-i\times \mathrm{vr}[:,j+1]`.

            Each eigenvector will be scaled so the largest component has :math:`\left\lvert \text{real part}\right\rvert +\left\lvert \text{imag. part}\right\rvert = 1`.

            If :math:`\mathrm{jobvr} = \texttt{'N'}`, :math:`\mathrm{vr}` is not referenced.

    .. _f08wa-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`.

            (`errno` :math:`n+1`)
                The :math:`QZ` iteration failed with an unexpected error, please contact `NAG <https://www.nag.com>`__.

            (`errno` :math:`n+2`)
                A failure occurred in :meth:`dtgevc` while computing generalized eigenvectors.

    **Warns**
        **NagAlgorithmicWarning**
            (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq n\right)`)
                The :math:`QZ` iteration failed. No eigenvectors have been calculated but :math:`\mathrm{alphar}[j]`, :math:`\mathrm{alphai}[j]` and :math:`\mathrm{beta}[j]` should be correct from element :math:`\langle\mathit{\boldsymbol{value}}\rangle`.

    .. _f08wa-py2-py-notes:

    **Notes**
        A generalized eigenvalue for a pair of matrices :math:`\left(A, B\right)` is a scalar :math:`\lambda` or a ratio :math:`\alpha /\beta = \lambda`, such that :math:`A-\lambda B` is singular.
        It is usually represented as the pair :math:`\left(\alpha, \beta \right)`, as there is a reasonable interpretation for :math:`\beta = 0`, and even for both being zero.

        The right eigenvector :math:`v_j` corresponding to the eigenvalue :math:`\lambda_j` of :math:`\left(A, B\right)` satisfies

        .. math::
            Av_j = \lambda_jBv_j\text{.}

        The left eigenvector :math:`u_j` corresponding to the eigenvalue :math:`\lambda_j` of :math:`\left(A, B\right)` satisfies

        .. math::
            u_j^\mathrm{H}A = \lambda_ju_j^\mathrm{H}B\text{,}

        where :math:`u_j^\mathrm{H}` is the conjugate-transpose of :math:`u_j`.

        All the eigenvalues and, if required, all the eigenvectors of the generalized eigenproblem :math:`Ax = \lambda Bx`, where :math:`A` and :math:`B` are real, square matrices, are determined using the :math:`QZ` algorithm.
        The :math:`QZ` algorithm consists of four stages:

        (1) :math:`A` is reduced to upper Hessenberg form and at the same time :math:`B` is reduced to upper triangular form.

        (#) :math:`A` is further reduced to quasi-triangular form while the triangular form of :math:`B` is maintained. This is the real generalized Schur form of the pair :math:`\left(A, B\right)`.

        (#) The quasi-triangular form of :math:`A` is reduced to triangular form and the eigenvalues extracted. This function does not actually produce the eigenvalues :math:`\lambda_j`, but instead returns :math:`\alpha_j` and :math:`\beta_j` such that

            .. math::
                \lambda_j = \alpha_j/\beta_j\text{, }\quad j = 1,2,\ldots,n\text{.}

            The division by :math:`\beta_j` becomes your responsibility, since :math:`\beta_j` may be zero, indicating an infinite eigenvalue. Pairs of complex eigenvalues occur with :math:`\alpha_j/\beta_j` and :math:`\alpha_{{j+1}}/\beta_{{j+1}}` complex conjugates, even though :math:`\alpha_j` and :math:`\alpha_{{j+1}}` are not conjugate.

        (#) If the eigenvectors are required they are obtained from the triangular matrices and then transformed back into the original coordinate system.

    .. _f08wa-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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, 2012, `Matrix Computations`, (4th Edition), Johns Hopkins University Press, Baltimore

        Wilkinson, J H, 1979, `Kronecker's canonical form and the` :math:`{QZ}` `algorithm`, Linear Algebra Appl. (28), 285--303
    """
    raise NotImplementedError

def dggevx(balanc, jobvl, jobvr, sense, a, b):
    r"""
    ``dggevx`` computes for a pair of :math:`n\times n` real nonsymmetric matrices :math:`\left(A, B\right)` the generalized eigenvalues and, optionally, the left and/or right generalized eigenvectors using the :math:`QZ` algorithm.

    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.

    .. _f08wb-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08wbf.html

    .. _f08wb-py2-py-parameters:

    **Parameters**
        **balanc** : str, length 1
            Specifies the balance option to be performed.

            :math:`\mathrm{balanc} = \texttt{'N'}`

                Do not diagonally scale or permute.

            :math:`\mathrm{balanc} = \texttt{'P'}`

                Permute only.

            :math:`\mathrm{balanc} = \texttt{'S'}`

                Scale only.

            :math:`\mathrm{balanc} = \texttt{'B'}`

                Both permute and scale.

            Computed reciprocal condition numbers will be for the matrices after permuting and/or balancing.

            Permuting does not change condition numbers (in exact arithmetic), but balancing does.

            In the absence of other information, :math:`\mathrm{balanc} = \texttt{'B'}` is recommended.

        **jobvl** : str, length 1
            If :math:`\mathrm{jobvl} = \texttt{'N'}`, do not compute the left generalized eigenvectors.

            If :math:`\mathrm{jobvl} = \texttt{'V'}`, compute the left generalized eigenvectors.

        **jobvr** : str, length 1
            If :math:`\mathrm{jobvr} = \texttt{'N'}`, do not compute the right generalized eigenvectors.

            If :math:`\mathrm{jobvr} = \texttt{'V'}`, compute the right generalized eigenvectors.

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

            :math:`\mathrm{sense} = \texttt{'B'}`

                Computed for eigenvalues and eigenvectors.

        **a** : float, array-like, shape :math:`\left(n, n\right)`
            The matrix :math:`A` in the pair :math:`\left(A, B\right)`.

        **b** : float, array-like, shape :math:`\left(n, n\right)`
            The matrix :math:`B` in the pair :math:`\left(A, B\right)`.

    **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'}` or both, then :math:`A` contains the first part of the real Schur form of the 'balanced' versions of the input :math:`A` and :math:`B`.

        **b** : float, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{b}` has been overwritten.

        **alphar** : float, ndarray, shape :math:`\left(n\right)`
            The element :math:`\mathrm{alphar}[j-1]` contains the real part of :math:`\alpha_j`.

        **alphai** : float, ndarray, shape :math:`\left(n\right)`
            The element :math:`\mathrm{alphai}[j-1]` contains the imaginary part of :math:`\alpha_j`.

        **beta** : float, ndarray, shape :math:`\left(n\right)`
            :math:`\left(\mathrm{alphar}[\textit{j}-1]+\mathrm{alphai}[\textit{j}-1]\times i\right)/\mathrm{beta}[\textit{j}-1]`, for :math:`\textit{j} = 1,2,\ldots,n`, will be the generalized eigenvalues.

            If :math:`\mathrm{alphai}[j-1]` is zero, then the :math:`j`\ th eigenvalue is real; if positive, then the :math:`j`\ th and :math:`\left(j+1\right)`\ st eigenvalues are a complex conjugate pair, with :math:`\mathrm{alphai}[j]` negative.

            **Note:** the quotients :math:`\mathrm{alphar}[j-1]/\mathrm{beta}[j-1]` and :math:`\mathrm{alphai}[j-1]/\mathrm{beta}[j-1]` may easily overflow or underflow, and :math:`\mathrm{beta}[j-1]` may even be zero.

            Thus, you should avoid naively computing the ratio :math:`\alpha_j/\beta_j`.

            However, :math:`\mathrm{max}\left(\left\lvert \alpha_j\right\rvert \right)` will always be less than and usually comparable with :math:`\left\lVert A\right\rVert_2` in magnitude, and :math:`\mathrm{max}\left(\left\lvert \beta_j\right\rvert \right)` will always be less than and usually comparable with :math:`\left\lVert B\right\rVert_2`.

        **vl** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobvl} = \texttt{'V'}`, the left generalized eigenvectors :math:`u_j` are stored one after another in the columns of :math:`\mathrm{vl}`, in the same order as the corresponding eigenvalues. Each eigenvector will be scaled so the largest component will have :math:`\left\lvert \text{real part}\right\rvert +\left\lvert \text{imag. part}\right\rvert = 1`.

            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 generalized eigenvectors :math:`v_j` are stored one after another in the columns of :math:`\mathrm{vr}`, in the same order as the corresponding eigenvalues. Each eigenvector will be scaled so the largest component will have :math:`\left\lvert \text{real part}\right\rvert +\left\lvert \text{imag. part}\right\rvert = 1`.

            If :math:`\mathrm{jobvr} = \texttt{'N'}`, :math:`\mathrm{vr}` is not referenced.

        **ilo** : int
            :math:`\mathrm{ilo}` and :math:`\mathrm{ihi}` are integer values such that :math:`\mathrm{a}[i-1,j-1] = 0` and :math:`\mathrm{b}[i-1,j-1] = 0` if :math:`i > j` and :math:`j = 1,2,\ldots,\mathrm{ilo}-1` or :math:`i = \mathrm{ihi}+1,\ldots,n`.

            If :math:`\mathrm{balanc} = \texttt{'N'}` or :math:`\texttt{'S'}`, :math:`\mathrm{ilo} = 1` and :math:`\mathrm{ihi} = n`.

        **ihi** : int
            :math:`\mathrm{ilo}` and :math:`\mathrm{ihi}` are integer values such that :math:`\mathrm{a}[i-1,j-1] = 0` and :math:`\mathrm{b}[i-1,j-1] = 0` if :math:`i > j` and :math:`j = 1,2,\ldots,\mathrm{ilo}-1` or :math:`i = \mathrm{ihi}+1,\ldots,n`.

            If :math:`\mathrm{balanc} = \texttt{'N'}` or :math:`\texttt{'S'}`, :math:`\mathrm{ilo} = 1` and :math:`\mathrm{ihi} = n`.

        **lscale** : float, ndarray, shape :math:`\left(n\right)`
            Details of the permutations and scaling factors applied to the left side of :math:`A` and :math:`B`.

            If :math:`\textit{pl}_j` is the index of the row interchanged with row :math:`j`, and :math:`\textit{dl}_j` is the scaling factor applied to row :math:`j`, then:

                :math:`\mathrm{lscale}[\textit{j}-1] = \textit{pl}_{\textit{j}}`, for :math:`\textit{j} = 1,2,\ldots,\mathrm{ilo}-1`;

                :math:`\mathrm{lscale} = \textit{dl}_{\textit{j}}`, for :math:`\textit{j} = \mathrm{ilo},\ldots,\mathrm{ihi}`;

                :math:`\mathrm{lscale} = \textit{pl}_{\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`.

        **rscale** : float, ndarray, shape :math:`\left(n\right)`
            Details of the permutations and scaling factors applied to the right side of :math:`A` and :math:`B`.

            If :math:`\textit{pr}_j` is the index of the column interchanged with column :math:`j`, and :math:`\textit{dr}_j` is the scaling factor applied to column :math:`j`, then:

                :math:`\mathrm{rscale}[\textit{j}-1] = \textit{pr}_{\textit{j}}`, for :math:`\textit{j} = 1,2,\ldots,\mathrm{ilo}-1`;

                if :math:`\mathrm{rscale} = \textit{dr}_{\textit{j}}`, for :math:`\textit{j} = \mathrm{ilo},\ldots,\mathrm{ihi}`;

                if :math:`\mathrm{rscale} = \textit{pr}_{\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 :math:`A`.

        **bbnrm** : float
            The :math:`1`-norm of the balanced matrix :math:`B`.

        **rconde** : float, ndarray, shape :math:`\left(n\right)`
            If :math:`\mathrm{sense} = \texttt{'E'}` or :math:`\texttt{'B'}`, the reciprocal condition numbers of the eigenvalues, stored in consecutive elements of the array. For a complex conjugate pair of eigenvalues two consecutive elements of :math:`\mathrm{rconde}` are set to the same value. Thus :math:`\mathrm{rconde}[j-1]`, :math:`\mathrm{rcondv}[j-1]`, and the :math:`j`\ th columns of :math:`\mathrm{vl}` and :math:`\mathrm{vr}` all correspond to the :math:`j`\ th eigenpair.

            If :math:`\mathrm{sense} = \texttt{'V'}`, :math:`\mathrm{rconde}` is not referenced.

        **rcondv** : float, ndarray, shape :math:`\left(n\right)`
            If :math:`\mathrm{sense} = \texttt{'V'}` or :math:`\texttt{'B'}`, the estimated reciprocal condition numbers of the eigenvectors, stored in consecutive elements of the array. For a complex eigenvector two consecutive elements of :math:`\mathrm{rcondv}` are set to the same value.

            If :math:`\mathrm{sense} = \texttt{'E'}`, :math:`\mathrm{rcondv}` is not referenced.

    .. _f08wb-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`.

            (`errno` :math:`n+1`)
                The :math:`QZ` iteration failed with an unexpected error, please contact `NAG <https://www.nag.com>`__.

            (`errno` :math:`n+2`)
                A failure occurred in :meth:`dtgevc` while computing generalized eigenvectors.

    **Warns**
        **NagAlgorithmicWarning**
            (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq n\right)`)
                The :math:`QZ` iteration failed. No eigenvectors have been calculated but :math:`\mathrm{alphar}[j]`, :math:`\mathrm{alphai}[j]` and :math:`\mathrm{beta}[j]` should be correct from element :math:`\langle\mathit{\boldsymbol{value}}\rangle`.

    .. _f08wb-py2-py-notes:

    **Notes**
        A generalized eigenvalue for a pair of matrices :math:`\left(A, B\right)` is a scalar :math:`\lambda` or a ratio :math:`\alpha /\beta = \lambda`, such that :math:`A-\lambda B` is singular.
        It is usually represented as the pair :math:`\left(\alpha, \beta \right)`, as there is a reasonable interpretation for :math:`\beta = 0`, and even for both being zero.

        The right eigenvector :math:`v_j` corresponding to the eigenvalue :math:`\lambda_j` of :math:`\left(A, B\right)` satisfies

        .. math::
            Av_j = \lambda_jBv_j\text{.}

        The left eigenvector :math:`u_j` corresponding to the eigenvalue :math:`\lambda_j` of :math:`\left(A, B\right)` satisfies

        .. math::
            u_j^\mathrm{H}A = \lambda_ju_j^\mathrm{H}B\text{,}

        where :math:`u_j^\mathrm{H}` is the conjugate-transpose of :math:`u_j`.

        All the eigenvalues and, if required, all the eigenvectors of the generalized eigenproblem :math:`Ax = \lambda Bx`, where :math:`A` and :math:`B` are real, square matrices, are determined using the :math:`QZ` algorithm.
        The :math:`QZ` algorithm consists of four stages:

        (1) :math:`A` is reduced to upper Hessenberg form and at the same time :math:`B` is reduced to upper triangular form.

        (#) :math:`A` is further reduced to quasi-triangular form while the triangular form of :math:`B` is maintained. This is the real generalized Schur form of the pair :math:`\left(A, B\right)`.

        (#) The quasi-triangular form of :math:`A` is reduced to triangular form and the eigenvalues extracted. This function does not actually produce the eigenvalues :math:`\lambda_j`, but instead returns :math:`\alpha_j` and :math:`\beta_j` such that

            .. math::
                \lambda_j = \alpha_j/\beta_j\text{, }\quad j = 1,2,\ldots,n\text{.}

            The division by :math:`\beta_j` becomes your responsibility, since :math:`\beta_j` may be zero, indicating an infinite eigenvalue. Pairs of complex eigenvalues occur with :math:`\alpha_j/\beta_j` and :math:`\alpha_{{j+1}}/\beta_{{j+1}}` complex conjugates, even though :math:`\alpha_j` and :math:`\alpha_{{j+1}}` are not conjugate.

        (#) If the eigenvectors are required they are obtained from the triangular matrices and then transformed back into the original coordinate system.

        For details of the balancing option, see :ref:`Notes for dggbal <f08wh-py2-py-notes>`.

    .. _f08wb-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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, 2012, `Matrix Computations`, (4th Edition), Johns Hopkins University Press, Baltimore

        Wilkinson, J H, 1979, `Kronecker's canonical form and the` :math:`{QZ}` `algorithm`, Linear Algebra Appl. (28), 285--303
    """
    raise NotImplementedError

def dggev3(jobvl, jobvr, a, b):
    r"""
    ``dggev3`` computes for a pair of :math:`n\times n` real nonsymmetric matrices :math:`\left(A, B\right)` the generalized eigenvalues and, optionally, the left and/or right generalized eigenvectors using the :math:`QZ` algorithm.

    .. _f08wc-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08wcf.html

    .. _f08wc-py2-py-parameters:

    **Parameters**
        **jobvl** : str, length 1
            If :math:`\mathrm{jobvl} = \texttt{'N'}`, do not compute the left generalized eigenvectors.

            If :math:`\mathrm{jobvl} = \texttt{'V'}`, compute the left generalized eigenvectors.

        **jobvr** : str, length 1
            If :math:`\mathrm{jobvr} = \texttt{'N'}`, do not compute the right generalized eigenvectors.

            If :math:`\mathrm{jobvr} = \texttt{'V'}`, compute the right generalized eigenvectors.

        **a** : float, array-like, shape :math:`\left(n, n\right)`
            The matrix :math:`A` in the pair :math:`\left(A, B\right)`.

        **b** : float, array-like, shape :math:`\left(n, n\right)`
            The matrix :math:`B` in the pair :math:`\left(A, B\right)`.

    **Returns**
        **a** : float, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{a}` has been overwritten.

        **b** : float, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{b}` has been overwritten.

        **alphar** : float, ndarray, shape :math:`\left(n\right)`
            The element :math:`\mathrm{alphar}[j-1]` contains the real part of :math:`\alpha_j`.

        **alphai** : float, ndarray, shape :math:`\left(n\right)`
            The element :math:`\mathrm{alphai}[j-1]` contains the imaginary part of :math:`\alpha_j`.

        **beta** : float, ndarray, shape :math:`\left(n\right)`
            :math:`\left(\mathrm{alphar}[\textit{j}-1]+\mathrm{alphai}[\textit{j}-1]\times i\right)/\mathrm{beta}[\textit{j}-1]`, for :math:`\textit{j} = 1,2,\ldots,n`, will be the generalized eigenvalues.

            If :math:`\mathrm{alphai}[j-1]` is zero, then the :math:`j`\ th eigenvalue is real; if positive, then the :math:`j`\ th and :math:`\left(j+1\right)`\ st eigenvalues are a complex conjugate pair, with :math:`\mathrm{alphai}[j]` negative.

            **Note:** the quotients :math:`\mathrm{alphar}[j-1]/\mathrm{beta}[j-1]` and :math:`\mathrm{alphai}[j-1]/\mathrm{beta}[j-1]` may easily overflow or underflow, and :math:`\mathrm{beta}[j-1]` may even be zero.

            Thus, you should avoid naively computing the ratio :math:`\alpha_j/\beta_j`.

            However, :math:`\mathrm{max}\left(\left\lvert \alpha_j\right\rvert \right)` will always be less than and usually comparable with :math:`\left\lVert A\right\rVert_2` in magnitude, and :math:`\mathrm{max}\left(\left\lvert \beta_j\right\rvert \right)` will always be less than and usually comparable with :math:`\left\lVert B\right\rVert_2`.

        **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 the corresponding eigenvalues.

            If the :math:`j`\ th eigenvalue is real, then :math:`u_j = \mathrm{vl}[:,j]`, the :math:`j`\ th column of :math:`\mathrm{vl}`.

            If the :math:`j`\ th and :math:`\left(j+1\right)`\ th eigenvalues form a complex conjugate pair, then :math:`u_j = \mathrm{vl}[:,j]+i\times \mathrm{vl}[:,j+1]` and :math:`u\left(j+1\right) = \mathrm{vl}[:,j]-i\times \mathrm{vl}[:,j+1]`.

            Each eigenvector will be scaled so the largest component has :math:`\left\lvert \text{real part}\right\rvert +\left\lvert \text{imag. part}\right\rvert = 1`.

            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 the corresponding eigenvalues.

            If the :math:`j`\ th eigenvalue is real, then :math:`v_j = \mathrm{vr}[:,j]`, the :math:`j`\ th column of :math:`\mathrm{VR}`.

            If the :math:`j`\ th and :math:`\left(j+1\right)`\ th eigenvalues form a complex conjugate pair, then :math:`v_j = \mathrm{vr}[:,j]+i\times \mathrm{vr}[:,j+1]` and :math:`v_{{j+1}} = \mathrm{vr}[:,j]-i\times \mathrm{vr}[:,j+1]`.

            Each eigenvector will be scaled so the largest component has :math:`\left\lvert \text{real part}\right\rvert +\left\lvert \text{imag. part}\right\rvert = 1`.

            If :math:`\mathrm{jobvr} = \texttt{'N'}`, :math:`\mathrm{vr}` is not referenced.

    .. _f08wc-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`.

            (`errno` :math:`n+1`)
                The :math:`QZ` iteration failed with an unexpected error, please contact `NAG <https://www.nag.com>`__.

            (`errno` :math:`n+2`)
                A failure occurred in :meth:`dtgevc` while computing generalized eigenvectors.

    **Warns**
        **NagAlgorithmicWarning**
            (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq n\right)`)
                The :math:`QZ` iteration failed. No eigenvectors have been calculated but :math:`\mathrm{alphar}[j]`, :math:`\mathrm{alphai}[j]` and :math:`\mathrm{beta}[j]` should be correct from element :math:`\langle\mathit{\boldsymbol{value}}\rangle`.

    .. _f08wc-py2-py-notes:

    **Notes**
        A generalized eigenvalue for a pair of matrices :math:`\left(A, B\right)` is a scalar :math:`\lambda` or a ratio :math:`\alpha /\beta = \lambda`, such that :math:`A-\lambda B` is singular.
        It is usually represented as the pair :math:`\left(\alpha, \beta \right)`, as there is a reasonable interpretation for :math:`\beta = 0`, and even for both being zero.

        The right eigenvector :math:`v_j` corresponding to the eigenvalue :math:`\lambda_j` of :math:`\left(A, B\right)` satisfies

        .. math::
            Av_j = \lambda_jBv_j\text{.}

        The left eigenvector :math:`u_j` corresponding to the eigenvalue :math:`\lambda_j` of :math:`\left(A, B\right)` satisfies

        .. math::
            u_j^\mathrm{H}A = \lambda_ju_j^\mathrm{H}B\text{,}

        where :math:`u_j^\mathrm{H}` is the conjugate-transpose of :math:`u_j`.

        All the eigenvalues and, if required, all the eigenvectors of the generalized eigenproblem :math:`Ax = \lambda Bx`, where :math:`A` and :math:`B` are real, square matrices, are determined using the :math:`QZ` algorithm.
        The :math:`QZ` algorithm consists of four stages:

        (1) :math:`A` is reduced to upper Hessenberg form and at the same time :math:`B` is reduced to upper triangular form.

        (#) :math:`A` is further reduced to quasi-triangular form while the triangular form of :math:`B` is maintained. This is the real generalized Schur form of the pair :math:`\left(A, B\right)`.

        (#) The quasi-triangular form of :math:`A` is reduced to triangular form and the eigenvalues extracted. This function does not actually produce the eigenvalues :math:`\lambda_j`, but instead returns :math:`\alpha_j` and :math:`\beta_j` such that

            .. math::
                \lambda_j = \alpha_j/\beta_j\text{, }\quad j = 1,2,\ldots,n\text{.}

            The division by :math:`\beta_j` becomes your responsibility, since :math:`\beta_j` may be zero, indicating an infinite eigenvalue. Pairs of complex eigenvalues occur with :math:`\alpha_j/\beta_j` and :math:`\alpha_{{j+1}}/\beta_{{j+1}}` complex conjugates, even though :math:`\alpha_j` and :math:`\alpha_{{j+1}}` are not conjugate.

        (#) If the eigenvectors are required they are obtained from the triangular matrices and then transformed back into the original coordinate system.

    .. _f08wc-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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, 2012, `Matrix Computations`, (4th Edition), Johns Hopkins University Press, Baltimore

        Wilkinson, J H, 1979, `Kronecker's canonical form and the` :math:`{QZ}` `algorithm`, Linear Algebra Appl. (28), 285--303
    """
    raise NotImplementedError

def dgghrd(compq, compz, ilo, ihi, a, b, q, z):
    r"""
    ``dgghrd`` reduces a pair of real matrices :math:`\left(A, B\right)`, where :math:`B` is upper triangular, to the generalized upper Hessenberg form using orthogonal transformations. ``dgghrd`` is marked as `deprecated` by LAPACK; the replacement routine is :meth:`dgghd3` which makes better use of Level 3 BLAS.

    .. deprecated:: 27.0.0.0
        ``dgghrd`` is deprecated.
        Please use :meth:`dgghd3` instead.
        See also the :ref:`Replacement Calls <replace>` document.

    .. _f08we-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08wef.html

    .. _f08we-py2-py-parameters:

    **Parameters**
        **compq** : str, length 1
            Specifies the form of the computed orthogonal matrix :math:`Q`.

            :math:`\mathrm{compq} = \texttt{'N'}`

                Do not compute :math:`Q`.

            :math:`\mathrm{compq} = \texttt{'I'}`

                The orthogonal matrix :math:`Q` is returned.

            :math:`\mathrm{compq} = \texttt{'V'}`

                :math:`\mathrm{q}` must contain an orthogonal matrix :math:`Q_1`, and the product :math:`Q_1Q` is returned.

        **compz** : str, length 1
            Specifies the form of the computed orthogonal matrix :math:`Z`.

            :math:`\mathrm{compz} = \texttt{'N'}`

                Do not compute :math:`Z`.

            :math:`\mathrm{compz} = \texttt{'I'}`

                The orthogonal matrix :math:`Z` is returned.

            :math:`\mathrm{compz} = \texttt{'V'}`

                :math:`\mathrm{z}` must contain an orthogonal matrix :math:`Z_1`, and the product :math:`Z_1Z` is returned.

        **ilo** : int
            :math:`i_{\mathrm{lo}}` and :math:`i_{\mathrm{hi}}` as determined by a previous call to :meth:`dggbal`. Otherwise, they should be set to :math:`1` and :math:`n`, respectively.

        **ihi** : int
            :math:`i_{\mathrm{lo}}` and :math:`i_{\mathrm{hi}}` as determined by a previous call to :meth:`dggbal`. Otherwise, they should be set to :math:`1` and :math:`n`, respectively.

        **a** : float, array-like, shape :math:`\left(n, n\right)`
            The matrix :math:`A` of the matrix pair :math:`\left(A, B\right)`. Usually, this is the matrix :math:`A` returned by :meth:`dormqr`.

        **b** : float, array-like, shape :math:`\left(n, n\right)`
            The upper triangular matrix :math:`B` of the matrix pair :math:`\left(A, B\right)`. Usually, this is the matrix :math:`B` returned by the :math:`QR` factorization function :meth:`dgeqrf`.

        **q** : float, array-like, shape :math:`\left(:, :\right)`
            Note: the required extent for this argument in dimension 1 is determined as follows: if :math:`\mathrm{compq}\text{ in } (\texttt{'I'}, \texttt{'V'})`: :math:`n`; if :math:`\mathrm{compq}=\texttt{'N'}`: :math:`1`; otherwise: :math:`0`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{compq}\text{ in } (\texttt{'I'}, \texttt{'V'})`: :math:`n`; if :math:`\mathrm{compq}=\texttt{'N'}`: :math:`1`; otherwise: :math:`0`.

            If :math:`\mathrm{compq} = \texttt{'V'}`, :math:`\mathrm{q}` must contain an orthogonal matrix :math:`Q_1`.

            If :math:`\mathrm{compq} = \texttt{'N'}`, :math:`\mathrm{q}` is not referenced.

        **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 an orthogonal matrix :math:`Z_1`.

            If :math:`\mathrm{compz} = \texttt{'N'}`, :math:`\mathrm{z}` is not referenced.

    **Returns**
        **a** : float, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{a}` is overwritten by the upper Hessenberg matrix :math:`H`.

        **b** : float, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{b}` is overwritten by the upper triangular matrix :math:`T`.

        **q** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{compq} = \texttt{'I'}`, :math:`\mathrm{q}` contains the orthogonal matrix :math:`Q`.

            If :math:`\mathrm{compq} = \texttt{'V'}`, :math:`\mathrm{q}` is overwritten by :math:`Q_1Q`.

        **z** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{compz} = \texttt{'I'}`, :math:`\mathrm{z}` contains the orthogonal matrix :math:`Z`.

            If :math:`\mathrm{compz} = \texttt{'V'}`, :math:`\mathrm{z}` is overwritten by :math:`Z_1Z`.

    .. _f08we-py2-py-errors:

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

                Constraint: :math:`\mathrm{compq} = \texttt{'N'}`, :math:`\texttt{'I'}` or :math:`\texttt{'V'}`.

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

                Constraint: :math:`\mathrm{compz} = \texttt{'N'}`, :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:`-4`)
                On entry, error in parameter :math:`\mathrm{ilo}`.

                Constraint: :math:`\mathrm{ilo}\geq 1`.

            (`errno` :math:`-5`)
                On entry, error in parameter :math:`\mathrm{ihi}`.

                Constraint: :math:`1\leq \mathrm{ilo}\leq \mathrm{ihi}\leq n`.

            (`errno` :math:`-5`)
                On entry, error in parameter :math:`\mathrm{ihi}`.

                Constraint: :math:`\mathrm{ilo} = 1` and :math:`\mathrm{ihi} = 0`.

    .. _f08we-py2-py-notes:

    **Notes**
        ``dgghrd`` is the third step in the solution of the real generalized eigenvalue problem

        .. math::
            Ax = \lambda Bx\text{.}

        The (optional) first step balances the two matrices using :meth:`dggbal`.
        In the second step, matrix :math:`B` is reduced to upper triangular form using the :math:`QR` factorization function :meth:`dgeqrf` and this orthogonal transformation :math:`Q` is applied to matrix :math:`A` by calling :meth:`dormqr`.

        ``dgghrd`` reduces a pair of real matrices :math:`\left(A, B\right)`, where :math:`B` is upper triangular, to the generalized upper Hessenberg form using orthogonal transformations.
        This two-sided transformation is of the form

        .. math::
            \begin{array}{c}Q^\mathrm{T}AZ = H\\Q^\mathrm{T}BZ = T\end{array}

        where :math:`H` is an upper Hessenberg matrix, :math:`T` is an upper triangular matrix and :math:`Q` and :math:`Z` are orthogonal matrices determined as products of Givens rotations.
        They may either be formed explicitly, or they may be postmultiplied into input matrices :math:`Q_1` and :math:`Z_1`, so that

        .. math::
            \begin{array}{c}Q_1AZ_1^\mathrm{T} = \left(Q_1Q\right)H\left(Z_1Z\right)^\mathrm{T}\text{,}\\Q_1BZ_1^\mathrm{T} = \left(Q_1Q\right)T\left(Z_1Z\right)^\mathrm{T}\text{.}\end{array}

    .. _f08we-py2-py-references:

    **References**
        Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore

        Moler, C B and Stewart, G W, 1973, `An algorithm for generalized matrix eigenproblems`, SIAM J. Numer. Anal. (10), 241--256
    """
    raise NotImplementedError

def dgghd3(compq, compz, ilo, ihi, a, b, q, z):
    r"""
    ``dgghd3`` reduces a pair of real matrices :math:`\left(A, B\right)`, where :math:`B` is upper triangular, to the generalized upper Hessenberg form using orthogonal transformations.

    .. _f08wf-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08wff.html

    .. _f08wf-py2-py-parameters:

    **Parameters**
        **compq** : str, length 1
            Specifies the form of the computed orthogonal matrix :math:`Q`.

            :math:`\mathrm{compq} = \texttt{'N'}`

                Do not compute :math:`Q`.

            :math:`\mathrm{compq} = \texttt{'I'}`

                The orthogonal matrix :math:`Q` is returned.

            :math:`\mathrm{compq} = \texttt{'V'}`

                :math:`\mathrm{q}` must contain an orthogonal matrix :math:`Q_1`, and the product :math:`Q_1Q` is returned.

        **compz** : str, length 1
            Specifies the form of the computed orthogonal matrix :math:`Z`.

            :math:`\mathrm{compz} = \texttt{'N'}`

                Do not compute :math:`Z`.

            :math:`\mathrm{compz} = \texttt{'I'}`

                The orthogonal matrix :math:`Z` is returned.

            :math:`\mathrm{compz} = \texttt{'V'}`

                :math:`\mathrm{z}` must contain an orthogonal matrix :math:`Z_1`, and the product :math:`Z_1Z` is returned.

        **ilo** : int
            :math:`i_{\mathrm{lo}}` and :math:`i_{\mathrm{hi}}` as determined by a previous call to :meth:`dggbal`. Otherwise, they should be set to :math:`1` and :math:`n`, respectively.

        **ihi** : int
            :math:`i_{\mathrm{lo}}` and :math:`i_{\mathrm{hi}}` as determined by a previous call to :meth:`dggbal`. Otherwise, they should be set to :math:`1` and :math:`n`, respectively.

        **a** : float, array-like, shape :math:`\left(n, n\right)`
            The matrix :math:`A` of the matrix pair :math:`\left(A, B\right)`. Usually, this is the matrix :math:`A` returned by :meth:`dormqr`.

        **b** : float, array-like, shape :math:`\left(n, n\right)`
            The upper triangular matrix :math:`B` of the matrix pair :math:`\left(A, B\right)`. Usually, this is the matrix :math:`B` returned by the :math:`QR` factorization function :meth:`dgeqrf`.

        **q** : float, array-like, shape :math:`\left(:, :\right)`
            Note: the required extent for this argument in dimension 1 is determined as follows: if :math:`\mathrm{compq}\text{ in } (\texttt{'I'}, \texttt{'V'})`: :math:`n`; if :math:`\mathrm{compq}=\texttt{'N'}`: :math:`1`; otherwise: :math:`0`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{compq}\text{ in } (\texttt{'I'}, \texttt{'V'})`: :math:`n`; if :math:`\mathrm{compq}=\texttt{'N'}`: :math:`1`; otherwise: :math:`0`.

            If :math:`\mathrm{compq} = \texttt{'V'}`, :math:`\mathrm{q}` must contain an orthogonal matrix :math:`Q_1`.

            If :math:`\mathrm{compq} = \texttt{'N'}`, :math:`\mathrm{q}` is not referenced.

        **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 an orthogonal matrix :math:`Z_1`.

            If :math:`\mathrm{compz} = \texttt{'N'}`, :math:`\mathrm{z}` is not referenced.

    **Returns**
        **a** : float, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{a}` is overwritten by the upper Hessenberg matrix :math:`H`.

        **b** : float, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{b}` is overwritten by the upper triangular matrix :math:`T`.

        **q** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{compq} = \texttt{'I'}`, :math:`\mathrm{q}` contains the orthogonal matrix :math:`Q`.

            If :math:`\mathrm{compq} = \texttt{'V'}`, :math:`\mathrm{q}` is overwritten by :math:`Q_1Q`.

        **z** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{compz} = \texttt{'I'}`, :math:`\mathrm{z}` contains the orthogonal matrix :math:`Z`.

            If :math:`\mathrm{compz} = \texttt{'V'}`, :math:`\mathrm{z}` is overwritten by :math:`Z_1Z`.

    .. _f08wf-py2-py-errors:

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

                Constraint: :math:`\mathrm{compq} = \texttt{'N'}`, :math:`\texttt{'I'}` or :math:`\texttt{'V'}`.

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

                Constraint: :math:`\mathrm{compz} = \texttt{'N'}`, :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:`-4`)
                On entry, error in parameter :math:`\mathrm{ilo}`.

                Constraint: :math:`\mathrm{ilo}\geq 1`.

            (`errno` :math:`-5`)
                On entry, error in parameter :math:`\mathrm{ihi}`.

                Constraint: :math:`1\leq \mathrm{ilo}\leq \mathrm{ihi}\leq n`.

            (`errno` :math:`-5`)
                On entry, error in parameter :math:`\mathrm{ihi}`.

                Constraint: :math:`\mathrm{ilo} = 1` and :math:`\mathrm{ihi} = 0`.

    .. _f08wf-py2-py-notes:

    **Notes**
        ``dgghd3`` is the third step in the solution of the real generalized eigenvalue problem

        .. math::
            Ax = \lambda Bx\text{.}

        The (optional) first step balances the two matrices using :meth:`dggbal`.
        In the second step, matrix :math:`B` is reduced to upper triangular form using the :math:`QR` factorization function :meth:`dgeqrf` and this orthogonal transformation :math:`Q` is applied to matrix :math:`A` by calling :meth:`dormqr`.
        The driver, :meth:`dggev3`, solves the real generalized eigenvalue problem by combining all the required steps including those just listed.

        ``dgghd3`` reduces a pair of real matrices :math:`\left(A, B\right)`, where :math:`B` is upper triangular, to the generalized upper Hessenberg form using orthogonal transformations.
        This two-sided transformation is of the form

        .. math::
            \begin{array}{c}Q^\mathrm{T}AZ = H\text{,}\\Q^\mathrm{T}BZ = T\end{array}

        where :math:`H` is an upper Hessenberg matrix, :math:`T` is an upper triangular matrix and :math:`Q` and :math:`Z` are orthogonal matrices determined as products of Givens rotations.
        They may either be formed explicitly, or they may be postmultiplied into input matrices :math:`Q_1` and :math:`Z_1`, so that

        .. math::
            \begin{array}{c}Q_1AZ_1^\mathrm{T} = \left(Q_1Q\right)H\left(Z_1Z\right)^\mathrm{T}\text{,}\\Q_1BZ_1^\mathrm{T} = \left(Q_1Q\right)T\left(Z_1Z\right)^\mathrm{T}\text{.}\end{array}

    .. _f08wf-py2-py-references:

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

        Moler, C B and Stewart, G W, 1973, `An algorithm for generalized matrix eigenproblems`, SIAM J. Numer. Anal. (10), 241--256
    """
    raise NotImplementedError

def dggbal(job, n, a, b):
    r"""
    ``dggbal`` balances a pair of real square matrices :math:`\left(A, B\right)` of order :math:`n`.
    Balancing usually improves the accuracy of computed generalized eigenvalues and eigenvectors.

    .. _f08wh-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08whf.html

    .. _f08wh-py2-py-parameters:

    **Parameters**
        **job** : str, length 1
            Specifies the operations to be performed on matrices :math:`A` and :math:`B`.

            :math:`\mathrm{job} = \texttt{'N'}`

                No balancing is done. Initialize :math:`\mathrm{ilo} = 1`, :math:`\mathrm{ihi} = \mathrm{n}`, :math:`\mathrm{lscale}[\textit{i}-1] = 1.0` and :math:`\mathrm{rscale}[\textit{i}-1] = 1.0`, for :math:`\textit{i} = 1,2,\ldots,n`.

            :math:`\mathrm{job} = \texttt{'P'}`

                Only permutations are used in balancing.

            :math:`\mathrm{job} = \texttt{'S'}`

                Only scalings are are used in balancing.

            :math:`\mathrm{job} = \texttt{'B'}`

                Both permutations and scalings are used in balancing.

        **n** : int
            :math:`n`, the order of the matrices :math:`A` and :math:`B`.

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

        **b** : float, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)`
            The :math:`n\times n` matrix :math:`B`.

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

        **b** : float, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)`
            :math:`\mathrm{b}` is overwritten by the balanced matrix. If :math:`\mathrm{job} = \texttt{'N'}`, :math:`\mathrm{b}` is not referenced.

        **ilo** : int
            :math:`i_{\mathrm{lo}}` and :math:`i_{\mathrm{hi}}` are set such that :math:`\mathrm{a}[i-1,j-1] = 0` and :math:`\mathrm{b}[i-1,j-1] = 0` 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
            :math:`i_{\mathrm{lo}}` and :math:`i_{\mathrm{hi}}` are set such that :math:`\mathrm{a}[i-1,j-1] = 0` and :math:`\mathrm{b}[i-1,j-1] = 0` 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`.

        **lscale** : float, ndarray, shape :math:`\left(\mathrm{n}\right)`
            Details of the permutations and scaling factors applied to the left side of the matrices :math:`A` and :math:`B`. If :math:`P_i` is the index of the row interchanged with row :math:`i` and :math:`d_i` is the scaling factor applied to row :math:`i`, then

                :math:`\mathrm{lscale}[\textit{i}-1] = P_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,\textit{i}_{\mathrm{lo}}-1`;

                :math:`\mathrm{lscale}[\textit{i}-1] = \textit{d}_{\textit{i}}`, for :math:`\textit{i} = \textit{i}_{\mathrm{lo}},\ldots,\textit{i}_{\mathrm{hi}}`;

                :math:`\mathrm{lscale}[\textit{i}-1] = P_{\textit{i}}`, for :math:`\textit{i} = \textit{i}_{\mathrm{hi}}+1,\ldots,n`.

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

        **rscale** : float, ndarray, shape :math:`\left(\mathrm{n}\right)`
            Details of the permutations and scaling factors applied to the right side of the matrices :math:`A` and :math:`B`.

            If :math:`P_j` is the index of the column interchanged with column :math:`j` and :math:`\hat{d}_j` is the scaling factor applied to column :math:`j`, then

                :math:`\mathrm{rscale}[\textit{j}-1] = P_{\textit{j}}`, for :math:`\textit{j} = 1,2,\ldots,\textit{i}_{\mathrm{lo}}-1`;

                :math:`\mathrm{rscale}[\textit{j}-1] = \hat{d}_{\textit{j}}`, for :math:`\textit{j} = i_{\mathrm{lo}},\ldots,i_{\mathrm{hi}}`;

                :math:`\mathrm{rscale}[\textit{j}-1] = P_{\textit{j}}`, for :math:`\textit{j} = i_{\mathrm{hi}}+1,\ldots,n`.

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

    .. _f08wh-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`.

    .. _f08wh-py2-py-notes:

    **Notes**
        Balancing may reduce the :math:`1`-norms of the matrices and improve the accuracy of the computed eigenvalues and eigenvectors in the real generalized eigenvalue problem

        .. math::
            Ax = \lambda Bx\text{.}

        ``dggbal`` is usually the first step in the solution of the above generalized eigenvalue problem.
        Balancing is optional but it is highly recommended.

        The term 'balancing' covers two steps, each of which involves similarity transformations on :math:`A` and :math:`B`.
        The function can perform either or both of these steps.
        Both steps are optional.

        (1) The function first attempts to permute :math:`A` and :math:`B` to block upper triangular form by a similarity transformation:

            .. math::
                PAP^\mathrm{T} = F = \begin{pmatrix}F_{11}&F_{12}&F_{13}\\&F_{22}&F_{23}\\&&F_{33}\end{pmatrix}

            .. math::
                PBP^\mathrm{T} = G = \begin{pmatrix}G_{11}&G_{12}&G_{13}\\&G_{22}&G_{23}\\&&G_{33}\end{pmatrix}

            where :math:`P` is a permutation matrix, :math:`F_{11}`, :math:`F_{33}`, :math:`G_{11}` and :math:`G_{33}` are upper triangular. Then the diagonal elements of the matrix pairs :math:`\left(F_{11}, G_{11}\right)` and :math:`\left(F_{33}, G_{33}\right)` are generalized eigenvalues of :math:`\left(A, B\right)`. The rest of the generalized eigenvalues are given by the matrix pair :math:`\left(F_{22}, G_{22}\right)` which are in rows and columns :math:`i_{\mathrm{lo}}` to :math:`i_{\mathrm{hi}}`. Subsequent operations to compute the generalized eigenvalues of :math:`\left(A, B\right)` need only be applied to the matrix pair :math:`\left(F_{22}, G_{22}\right)`; 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`.

        (#) The function applies a diagonal similarity transformation to :math:`\left(F, G\right)`, to make the rows and columns of :math:`\left(F_{22}, G_{22}\right)` as close in norm as possible:

            .. math::
                DF\hat{D} = \begin{pmatrix}I&0&0\\0&D_{22}&0\\0&0&I\end{pmatrix}\begin{pmatrix}F_{11}&F_{12}&F_{13}\\&F_{22}&F_{23}\\&&F_{33}\end{pmatrix}\begin{pmatrix}I&0&0\\0&\hat{D}_{22}&0\\0&0&I\end{pmatrix}

            .. math::
                DG\hat{D} = \begin{pmatrix}I&0&0\\0&D_{22}&0\\0&0&I\end{pmatrix}\begin{pmatrix}G_{11}&G_{12}&G_{13}\\&G_{22}&G_{23}\\&&G_{33}\end{pmatrix}\begin{pmatrix}I&0&0\\0&\hat{D}_{22}&0\\0&0&I\end{pmatrix}

            This transformation usually improves the accuracy of computed generalized eigenvalues and eigenvectors.

    .. _f08wh-py2-py-references:

    **References**
        Ward, R C, 1981, `Balancing the generalized eigenvalue problem`, SIAM J. Sci. Stat. Comp. (2), 141--152
    """
    raise NotImplementedError

def dggbak(job, side, ilo, ihi, lscale, rscale, v):
    r"""
    ``dggbak`` forms the right or left eigenvectors of the real generalized eigenvalue problem :math:`Ax = \lambda Bx`, by backward transformation on the computed eigenvectors given by :meth:`dtgevc`.
    It is necessary to call this function only if the optional balancing function :meth:`dggbal` was previously called to balance the matrix pair :math:`\left(A, B\right)`.

    .. _f08wj-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08wjf.html

    .. _f08wj-py2-py-parameters:

    **Parameters**
        **job** : str, length 1
            Specifies the backward transformation step required.

            :math:`\mathrm{job} = \texttt{'N'}`

                No transformations are done.

            :math:`\mathrm{job} = \texttt{'P'}`

                Only do backward transformations based on permutations.

            :math:`\mathrm{job} = \texttt{'S'}`

                Only do backward transformations based on scaling.

            :math:`\mathrm{job} = \texttt{'B'}`

                Do backward transformations for both permutations and scaling.

            **Note:** this must be the same argument :math:`\mathrm{job}` as supplied to :meth:`dggbal`.

        **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
            :math:`i_{\mathrm{lo}}` and :math:`i_{\mathrm{hi}}` as determined by a previous call to :meth:`dggbal`.

        **ihi** : int
            :math:`i_{\mathrm{lo}}` and :math:`i_{\mathrm{hi}}` as determined by a previous call to :meth:`dggbal`.

        **lscale** : float, array-like, shape :math:`\left(n\right)`
            Details of the permutations and scaling factors applied to the left side of the matrices :math:`A` and :math:`B`, as returned by a previous call to :meth:`dggbal`.

        **rscale** : float, array-like, shape :math:`\left(n\right)`
            Details of the permutations and scaling factors applied to the right side of the matrices :math:`A` and :math:`B`, as returned by a previous call to :meth:`dggbal`.

        **v** : float, array-like, shape :math:`\left(n, m\right)`
            The matrix of right or left eigenvectors, as returned by :meth:`dggbal`.

    **Returns**
        **v** : float, ndarray, shape :math:`\left(n, m\right)`
            The transformed right or left eigenvectors.

    .. _f08wj-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:`-8`)
                On entry, error in parameter :math:`\textit{m}`.

                Constraint: :math:`0\leq m\leq n`.

    .. _f08wj-py2-py-notes:

    **Notes**
        If the matrix pair has been previously balanced using the function :meth:`dggbal` then ``dggbak`` backtransforms the eigenvector solution given by :meth:`dtgevc`.
        This is usually the sixth and last step in the solution of the generalized eigenvalue problem.

        For a description of balancing, see the document for :meth:`dggbal`.

    .. _f08wj-py2-py-references:

    **References**
        Ward, R C, 1981, `Balancing the generalized eigenvalue problem`, SIAM J. Sci. Stat. Comp. (2), 141--152
    """
    raise NotImplementedError

def zggev(jobvl, jobvr, a, b):
    r"""
    ``zggev`` computes for a pair of :math:`n\times n` complex nonsymmetric matrices :math:`\left(A, B\right)` the generalized eigenvalues and, optionally, the left and/or right generalized eigenvectors using the :math:`QZ` algorithm. ``zggev`` is marked as `deprecated` by LAPACK; the replacement routine is :meth:`zggev3` which makes better use of Level 3 BLAS.

    .. deprecated:: 27.0.0.0
        ``zggev`` is deprecated.
        Please use :meth:`zggev3` instead.
        See also the :ref:`Replacement Calls <replace>` document.

    .. _f08wn-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08wnf.html

    .. _f08wn-py2-py-parameters:

    **Parameters**
        **jobvl** : str, length 1
            If :math:`\mathrm{jobvl} = \texttt{'N'}`, do not compute the left generalized eigenvectors.

            If :math:`\mathrm{jobvl} = \texttt{'V'}`, compute the left generalized eigenvectors.

        **jobvr** : str, length 1
            If :math:`\mathrm{jobvr} = \texttt{'N'}`, do not compute the right generalized eigenvectors.

            If :math:`\mathrm{jobvr} = \texttt{'V'}`, compute the right generalized eigenvectors.

        **a** : complex, array-like, shape :math:`\left(n, n\right)`
            The matrix :math:`A` in the pair :math:`\left(A, B\right)`.

        **b** : complex, array-like, shape :math:`\left(n, n\right)`
            The matrix :math:`B` in the pair :math:`\left(A, B\right)`.

    **Returns**
        **a** : complex, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{a}` has been overwritten.

        **b** : complex, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{b}` has been overwritten.

        **alpha** : complex, ndarray, shape :math:`\left(n\right)`
            See the description of :math:`\mathrm{beta}`.

        **beta** : complex, ndarray, shape :math:`\left(n\right)`
            :math:`\mathrm{alpha}[\textit{j}-1]/\mathrm{beta}[\textit{j}-1]`, for :math:`\textit{j} = 1,2,\ldots,n`, will be the generalized eigenvalues.

            **Note:** the quotients :math:`\mathrm{alpha}[j-1]/\mathrm{beta}[j-1]` may easily overflow or underflow, and :math:`\mathrm{beta}[j-1]` may even be zero.

            Thus, you should avoid naively computing the ratio :math:`\alpha_j/\beta_j`.

            However, :math:`\mathrm{max}\left(\left\lvert \alpha_j\right\rvert \right)` will always be less than and usually comparable with :math:`\left\lVert A\right\rVert_2` in magnitude, and :math:`\mathrm{max}\left(\left\lvert \beta_j\right\rvert \right)` will always be less than and usually comparable with :math:`\left\lVert B\right\rVert_2`.

        **vl** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobvl} = \texttt{'V'}`, the left generalized eigenvectors :math:`u_j` are stored one after another in the columns of :math:`\mathrm{vl}`, in the same order as the corresponding eigenvalues. Each eigenvector will be scaled so the largest component will have :math:`\left\lvert \text{real part}\right\rvert +\left\lvert \text{imag. part}\right\rvert = 1`.

            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 generalized eigenvectors :math:`v_j` are stored one after another in the columns of :math:`\mathrm{vr}`, in the same order as the corresponding eigenvalues. Each eigenvector will be scaled so the largest component will have :math:`\left\lvert \text{real part}\right\rvert +\left\lvert \text{imag. part}\right\rvert = 1`.

            If :math:`\mathrm{jobvr} = \texttt{'N'}`, :math:`\mathrm{vr}` is not referenced.

    .. _f08wn-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`.

            (`errno` :math:`n+1`)
                The :math:`QZ` iteration failed with an unexpected error, please contact `NAG <https://www.nag.com>`__.

            (`errno` :math:`n+2`)
                A failure occurred in :meth:`ztgevc` while computing generalized eigenvectors.

    **Warns**
        **NagAlgorithmicWarning**
            (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq n\right)`)
                The :math:`QZ` iteration failed. No eigenvectors have been calculated but :math:`\mathrm{alpha}` and :math:`\mathrm{beta}` should be correct from element :math:`\langle\mathit{\boldsymbol{value}}\rangle`.

    .. _f08wn-py2-py-notes:

    **Notes**
        A generalized eigenvalue for a pair of matrices :math:`\left(A, B\right)` is a scalar :math:`\lambda` or a ratio :math:`\alpha /\beta = \lambda`, such that :math:`A-\lambda B` is singular.
        It is usually represented as the pair :math:`\left(\alpha, \beta \right)`, as there is a reasonable interpretation for :math:`\beta = 0`, and even for both being zero.

        The right generalized eigenvector :math:`v_j` corresponding to the generalized eigenvalue :math:`\lambda_j` of :math:`\left(A, B\right)` satisfies

        .. math::
            Av_j = \lambda_jBv_j\text{.}

        The left generalized eigenvector :math:`u_j` corresponding to the generalized eigenvalue :math:`\lambda_j` of :math:`\left(A, B\right)` satisfies

        .. math::
            u_j^\mathrm{H}A = \lambda_ju_j^\mathrm{H}B\text{,}

        where :math:`u_j^\mathrm{H}` is the conjugate-transpose of :math:`u_j`.

        All the eigenvalues and, if required, all the eigenvectors of the complex generalized eigenproblem :math:`Ax = \lambda Bx`, where :math:`A` and :math:`B` are complex, square matrices, are determined using the :math:`QZ` algorithm.
        The complex :math:`QZ` algorithm consists of three stages:

        (1) :math:`A` is reduced to upper Hessenberg form (with real, non-negative subdiagonal elements) and at the same time :math:`B` is reduced to upper triangular form.

        (#) :math:`A` is further reduced to triangular form while the triangular form of :math:`B` is maintained and the diagonal elements of :math:`B` are made real and non-negative. This is the generalized Schur form of the pair :math:`\left(A, B\right)`.

            This function does not actually produce the eigenvalues :math:`\lambda_j`, but instead returns :math:`\alpha_j` and :math:`\beta_j` such that

            .. math::
                \lambda_j = \alpha_j/\beta_j\text{, }\quad j = 1,2,\ldots,n\text{.}

            The division by :math:`\beta_j` becomes your responsibility, since :math:`\beta_j` may be zero, indicating an infinite eigenvalue.

        (#) If the eigenvectors are required they are obtained from the triangular matrices and then transformed back into the original coordinate system.

    .. _f08wn-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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, 2012, `Matrix Computations`, (4th Edition), Johns Hopkins University Press, Baltimore

        Wilkinson, J H, 1979, `Kronecker's canonical form and the` :math:`{QZ}` `algorithm`, Linear Algebra Appl. (28), 285--303
    """
    raise NotImplementedError

def zggevx(balanc, jobvl, jobvr, sense, a, b):
    r"""
    ``zggevx`` computes for a pair of :math:`n\times n` complex nonsymmetric matrices :math:`\left(A, B\right)` the generalized eigenvalues and, optionally, the left and/or right generalized eigenvectors using the :math:`QZ` algorithm.

    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.

    .. _f08wp-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08wpf.html

    .. _f08wp-py2-py-parameters:

    **Parameters**
        **balanc** : str, length 1
            Specifies the balance option to be performed.

            :math:`\mathrm{balanc} = \texttt{'N'}`

                Do not diagonally scale or permute.

            :math:`\mathrm{balanc} = \texttt{'P'}`

                Permute only.

            :math:`\mathrm{balanc} = \texttt{'S'}`

                Scale only.

            :math:`\mathrm{balanc} = \texttt{'B'}`

                Both permute and scale.

            Computed reciprocal condition numbers will be for the matrices after permuting and/or balancing.

            Permuting does not change condition numbers (in exact arithmetic), but balancing does.

            In the absence of other information, :math:`\mathrm{balanc} = \texttt{'B'}` is recommended.

        **jobvl** : str, length 1
            If :math:`\mathrm{jobvl} = \texttt{'N'}`, do not compute the left generalized eigenvectors.

            If :math:`\mathrm{jobvl} = \texttt{'V'}`, compute the left generalized eigenvectors.

        **jobvr** : str, length 1
            If :math:`\mathrm{jobvr} = \texttt{'N'}`, do not compute the right generalized eigenvectors.

            If :math:`\mathrm{jobvr} = \texttt{'V'}`, compute the right generalized eigenvectors.

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

            :math:`\mathrm{sense} = \texttt{'B'}`

                Computed for eigenvalues and eigenvectors.

        **a** : complex, array-like, shape :math:`\left(n, n\right)`
            The matrix :math:`A` in the pair :math:`\left(A, B\right)`.

        **b** : complex, array-like, shape :math:`\left(n, n\right)`
            The matrix :math:`B` in the pair :math:`\left(A, B\right)`.

    **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'}` or both, then :math:`A` contains the first part of the Schur form of the 'balanced' versions of the input :math:`A` and :math:`B`.

        **b** : complex, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{b}` has been overwritten.

        **alpha** : complex, ndarray, shape :math:`\left(n\right)`
            See the description of :math:`\mathrm{beta}`.

        **beta** : complex, ndarray, shape :math:`\left(n\right)`
            :math:`\mathrm{alpha}[\textit{j}-1]/\mathrm{beta}[\textit{j}-1]`, for :math:`\textit{j} = 1,2,\ldots,n`, will be the generalized eigenvalues.

            **Note:** the quotients :math:`\mathrm{alpha}[j-1]/\mathrm{beta}[j-1]` may easily overflow or underflow, and :math:`\mathrm{beta}[j-1]` may even be zero.

            Thus, you should avoid naively computing the ratio :math:`\alpha_j/\beta_j`.

            However, :math:`\mathrm{max}\left(\left\lvert \alpha_j\right\rvert \right)` will always be less than and usually comparable with :math:`\left\lVert A\right\rVert_2` in magnitude, and :math:`\mathrm{max}\left(\left\lvert \beta_j\right\rvert \right)` will always be less than and usually comparable with :math:`\left\lVert B\right\rVert_2`.

        **vl** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobvl} = \texttt{'V'}`, the left generalized eigenvectors :math:`u_j` are stored one after another in the columns of :math:`\mathrm{vl}`, in the same order as the corresponding eigenvalues. Each eigenvector will be scaled so the largest component will have :math:`\left\lvert \text{real part}\right\rvert +\left\lvert \text{imag. part}\right\rvert = 1`.

            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 generalized eigenvectors :math:`v_j` are stored one after another in the columns of :math:`\mathrm{vr}`, in the same order as the corresponding eigenvalues. Each eigenvector will be scaled so the largest component will have :math:`\left\lvert \text{real part}\right\rvert +\left\lvert \text{imag. part}\right\rvert = 1`.

            If :math:`\mathrm{jobvr} = \texttt{'N'}`, :math:`\mathrm{vr}` is not referenced.

        **ilo** : int
            :math:`\mathrm{ilo}` and :math:`\mathrm{ihi}` are integer values such that :math:`\mathrm{a}[i-1,j-1] = 0` and :math:`\mathrm{b}[i-1,j-1] = 0` if :math:`i > j` and :math:`j = 1,2,\ldots,\mathrm{ilo}-1` or :math:`i = \mathrm{ihi}+1,\ldots,n`.

            If :math:`\mathrm{balanc} = \texttt{'N'}` or :math:`\texttt{'S'}`, :math:`\mathrm{ilo} = 1` and :math:`\mathrm{ihi} = n`.

        **ihi** : int
            :math:`\mathrm{ilo}` and :math:`\mathrm{ihi}` are integer values such that :math:`\mathrm{a}[i-1,j-1] = 0` and :math:`\mathrm{b}[i-1,j-1] = 0` if :math:`i > j` and :math:`j = 1,2,\ldots,\mathrm{ilo}-1` or :math:`i = \mathrm{ihi}+1,\ldots,n`.

            If :math:`\mathrm{balanc} = \texttt{'N'}` or :math:`\texttt{'S'}`, :math:`\mathrm{ilo} = 1` and :math:`\mathrm{ihi} = n`.

        **lscale** : float, ndarray, shape :math:`\left(n\right)`
            Details of the permutations and scaling factors applied to the left side of :math:`A` and :math:`B`.

            If :math:`\textit{pl}_j` is the index of the row interchanged with row :math:`j`, and :math:`\textit{dl}_j` is the scaling factor applied to row :math:`j`, then:

                :math:`\mathrm{lscale}[\textit{j}-1] = \textit{pl}_{\textit{j}}`, for :math:`\textit{j} = 1,2,\ldots,\mathrm{ilo}-1`;

                :math:`\mathrm{lscale} = \textit{dl}_{\textit{j}}`, for :math:`\textit{j} = \mathrm{ilo},\ldots,\mathrm{ihi}`;

                :math:`\mathrm{lscale} = \textit{pl}_{\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`.

        **rscale** : float, ndarray, shape :math:`\left(n\right)`
            Details of the permutations and scaling factors applied to the right side of :math:`A` and :math:`B`.

            If :math:`\textit{pr}_j` is the index of the column interchanged with column :math:`j`, and :math:`\textit{dr}_j` is the scaling factor applied to column :math:`j`, then:

                :math:`\mathrm{rscale}[\textit{j}-1] = \textit{pr}_{\textit{j}}`, for :math:`\textit{j} = 1,2,\ldots,\mathrm{ilo}-1`;

                if :math:`\mathrm{rscale} = \textit{dr}_{\textit{j}}`, for :math:`\textit{j} = \mathrm{ilo},\ldots,\mathrm{ihi}`;

                if :math:`\mathrm{rscale} = \textit{pr}_{\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 :math:`A`.

        **bbnrm** : float
            The :math:`1`-norm of the balanced matrix :math:`B`.

        **rconde** : float, ndarray, shape :math:`\left(n\right)`
            If :math:`\mathrm{sense} = \texttt{'E'}` or :math:`\texttt{'B'}`, the reciprocal condition numbers of the eigenvalues, stored in consecutive elements of the array.

            If :math:`\mathrm{sense} = \texttt{'N'}` or :math:`\texttt{'V'}`, :math:`\mathrm{rconde}` is not referenced.

        **rcondv** : float, ndarray, shape :math:`\left(n\right)`
            If :math:`\mathrm{sense} = \texttt{'V'}` or :math:`\texttt{'B'}`, the estimated reciprocal condition numbers of the selected eigenvectors, stored in consecutive elements of the array.

            If :math:`\mathrm{sense} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{rcondv}` is not referenced.

    .. _f08wp-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`.

            (`errno` :math:`n+1`)
                The :math:`QZ` iteration failed with an unexpected error, please contact `NAG <https://www.nag.com>`__.

            (`errno` :math:`n+2`)
                A failure occurred in :meth:`ztgevc` while computing generalized eigenvectors.

    **Warns**
        **NagAlgorithmicWarning**
            (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq n\right)`)
                The :math:`QZ` iteration failed. No eigenvectors have been calculated but :math:`\mathrm{alpha}` and :math:`\mathrm{beta}` should be correct from element :math:`\langle\mathit{\boldsymbol{value}}\rangle`.

    .. _f08wp-py2-py-notes:

    **Notes**
        A generalized eigenvalue for a pair of matrices :math:`\left(A, B\right)` is a scalar :math:`\lambda` or a ratio :math:`\alpha /\beta = \lambda`, such that :math:`A-\lambda B` is singular.
        It is usually represented as the pair :math:`\left(\alpha, \beta \right)`, as there is a reasonable interpretation for :math:`\beta = 0`, and even for both being zero.

        The right generalized eigenvector :math:`v_j` corresponding to the generalized eigenvalue :math:`\lambda_j` of :math:`\left(A, B\right)` satisfies

        .. math::
            Av_j = \lambda_jBv_j\text{.}

        The left generalized eigenvector :math:`u_j` corresponding to the generalized eigenvalue :math:`\lambda_j` of :math:`\left(A, B\right)` satisfies

        .. math::
            u_j^\mathrm{H}A = \lambda_ju_j^\mathrm{H}B\text{,}

        where :math:`u_j^\mathrm{H}` is the conjugate-transpose of :math:`u_j`.

        All the eigenvalues and, if required, all the eigenvectors of the complex generalized eigenproblem :math:`Ax = \lambda Bx`, where :math:`A` and :math:`B` are complex, square matrices, are determined using the :math:`QZ` algorithm.
        The complex :math:`QZ` algorithm consists of three stages:

        (1) :math:`A` is reduced to upper Hessenberg form (with real, non-negative subdiagonal elements) and at the same time :math:`B` is reduced to upper triangular form.

        (#) :math:`A` is further reduced to triangular form while the triangular form of :math:`B` is maintained and the diagonal elements of :math:`B` are made real and non-negative. This is the generalized Schur form of the pair :math:`\left(A, B\right)`.

            This function does not actually produce the eigenvalues :math:`\lambda_j`, but instead returns :math:`\alpha_j` and :math:`\beta_j` such that

            .. math::
                \lambda_j = \alpha_j/\beta_j\text{, }\quad j = 1,2,\ldots,n\text{.}

            The division by :math:`\beta_j` becomes your responsibility, since :math:`\beta_j` may be zero, indicating an infinite eigenvalue.

        (#) If the eigenvectors are required they are obtained from the triangular matrices and then transformed back into the original coordinate system.

        For details of the balancing option, see :ref:`Notes for zggbal <f08wv-py2-py-notes>`.

    .. _f08wp-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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, 2012, `Matrix Computations`, (4th Edition), Johns Hopkins University Press, Baltimore

        Wilkinson, J H, 1979, `Kronecker's canonical form and the` :math:`{QZ}` `algorithm`, Linear Algebra Appl. (28), 285--303
    """
    raise NotImplementedError

def zggev3(jobvl, jobvr, a, b):
    r"""
    ``zggev3`` computes for a pair of :math:`n\times n` complex nonsymmetric matrices :math:`\left(A, B\right)` the generalized eigenvalues and, optionally, the left and/or right generalized eigenvectors using the :math:`QZ` algorithm.

    .. _f08wq-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08wqf.html

    .. _f08wq-py2-py-parameters:

    **Parameters**
        **jobvl** : str, length 1
            If :math:`\mathrm{jobvl} = \texttt{'N'}`, do not compute the left generalized eigenvectors.

            If :math:`\mathrm{jobvl} = \texttt{'V'}`, compute the left generalized eigenvectors.

        **jobvr** : str, length 1
            If :math:`\mathrm{jobvr} = \texttt{'N'}`, do not compute the right generalized eigenvectors.

            If :math:`\mathrm{jobvr} = \texttt{'V'}`, compute the right generalized eigenvectors.

        **a** : complex, array-like, shape :math:`\left(n, n\right)`
            The matrix :math:`A` in the pair :math:`\left(A, B\right)`.

        **b** : complex, array-like, shape :math:`\left(n, n\right)`
            The matrix :math:`B` in the pair :math:`\left(A, B\right)`.

    **Returns**
        **a** : complex, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{a}` has been overwritten.

        **b** : complex, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{b}` has been overwritten.

        **alpha** : complex, ndarray, shape :math:`\left(n\right)`
            See the description of :math:`\mathrm{beta}`.

        **beta** : complex, ndarray, shape :math:`\left(n\right)`
            :math:`\mathrm{alpha}[\textit{j}-1]/\mathrm{beta}[\textit{j}-1]`, for :math:`\textit{j} = 1,2,\ldots,n`, will be the generalized eigenvalues.

            **Note:** the quotients :math:`\mathrm{alpha}[j-1]/\mathrm{beta}[j-1]` may easily overflow or underflow, and :math:`\mathrm{beta}[j-1]` may even be zero.

            Thus, you should avoid naively computing the ratio :math:`\alpha_j/\beta_j`.

            However, :math:`\mathrm{max}\left(\left\lvert \alpha_j\right\rvert \right)` will always be less than and usually comparable with :math:`\left\lVert A\right\rVert_2` in magnitude, and :math:`\mathrm{max}\left(\left\lvert \beta_j\right\rvert \right)` will always be less than and usually comparable with :math:`\left\lVert B\right\rVert_2`.

        **vl** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobvl} = \texttt{'V'}`, the left generalized eigenvectors :math:`u_j` are stored one after another in the columns of :math:`\mathrm{vl}`, in the same order as the corresponding eigenvalues. Each eigenvector will be scaled so the largest component will have :math:`\left\lvert \text{real part}\right\rvert +\left\lvert \text{imag. part}\right\rvert = 1`.

            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 generalized eigenvectors :math:`v_j` are stored one after another in the columns of :math:`\mathrm{vr}`, in the same order as the corresponding eigenvalues. Each eigenvector will be scaled so the largest component will have :math:`\left\lvert \text{real part}\right\rvert +\left\lvert \text{imag. part}\right\rvert = 1`.

            If :math:`\mathrm{jobvr} = \texttt{'N'}`, :math:`\mathrm{vr}` is not referenced.

    .. _f08wq-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`.

            (`errno` :math:`n+1`)
                The :math:`QZ` iteration failed with an unexpected error, please contact `NAG <https://www.nag.com>`__.

            (`errno` :math:`n+2`)
                A failure occurred in :meth:`ztgevc` while computing generalized eigenvectors.

    **Warns**
        **NagAlgorithmicWarning**
            (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq n\right)`)
                The :math:`QZ` iteration failed. No eigenvectors have been calculated but :math:`\mathrm{alpha}` and :math:`\mathrm{beta}` should be correct from element :math:`\langle\mathit{\boldsymbol{value}}\rangle`.

    .. _f08wq-py2-py-notes:

    **Notes**
        A generalized eigenvalue for a pair of matrices :math:`\left(A, B\right)` is a scalar :math:`\lambda` or a ratio :math:`\alpha /\beta = \lambda`, such that :math:`A-\lambda B` is singular.
        It is usually represented as the pair :math:`\left(\alpha, \beta \right)`, as there is a reasonable interpretation for :math:`\beta = 0`, and even for both being zero.

        The right generalized eigenvector :math:`v_j` corresponding to the generalized eigenvalue :math:`\lambda_j` of :math:`\left(A, B\right)` satisfies

        .. math::
            Av_j = \lambda_jBv_j\text{.}

        The left generalized eigenvector :math:`u_j` corresponding to the generalized eigenvalue :math:`\lambda_j` of :math:`\left(A, B\right)` satisfies

        .. math::
            u_j^\mathrm{H}A = \lambda_ju_j^\mathrm{H}B\text{,}

        where :math:`u_j^\mathrm{H}` is the conjugate-transpose of :math:`u_j`.

        All the eigenvalues and, if required, all the eigenvectors of the complex generalized eigenproblem :math:`Ax = \lambda Bx`, where :math:`A` and :math:`B` are complex, square matrices, are determined using the :math:`QZ` algorithm.
        The complex :math:`QZ` algorithm consists of three stages:

        (1) :math:`A` is reduced to upper Hessenberg form (with real, non-negative subdiagonal elements) and at the same time :math:`B` is reduced to upper triangular form.

        (#) :math:`A` is further reduced to triangular form while the triangular form of :math:`B` is maintained and the diagonal elements of :math:`B` are made real and non-negative. This is the generalized Schur form of the pair :math:`\left(A, B\right)`.

            This function does not actually produce the eigenvalues :math:`\lambda_j`, but instead returns :math:`\alpha_j` and :math:`\beta_j` such that

            .. math::
                \lambda_j = \alpha_j/\beta_j\text{, }\quad j = 1,2,\ldots,n\text{.}

            The division by :math:`\beta_j` becomes your responsibility, since :math:`\beta_j` may be zero, indicating an infinite eigenvalue.

        (#) If the eigenvectors are required they are obtained from the triangular matrices and then transformed back into the original coordinate system.

    .. _f08wq-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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, 2012, `Matrix Computations`, (4th Edition), Johns Hopkins University Press, Baltimore

        Wilkinson, J H, 1979, `Kronecker's canonical form and the` :math:`{QZ}` `algorithm`, Linear Algebra Appl. (28), 285--303
    """
    raise NotImplementedError

def zgghrd(compq, compz, ilo, ihi, a, b, q, z):
    r"""
    ``zgghrd`` reduces a pair of complex matrices :math:`\left(A, B\right)`, where :math:`B` is upper triangular, to the generalized upper Hessenberg form using unitary transformations.

    .. deprecated:: 27.0.0.0
        ``zgghrd`` is deprecated.
        Please use :meth:`zgghd3` instead.
        See also the :ref:`Replacement Calls <replace>` document.

    .. _f08ws-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08wsf.html

    .. _f08ws-py2-py-parameters:

    **Parameters**
        **compq** : str, length 1
            Specifies the form of the computed unitary matrix :math:`Q`.

            :math:`\mathrm{compq} = \texttt{'N'}`

                Do not compute :math:`Q`.

            :math:`\mathrm{compq} = \texttt{'I'}`

                The unitary matrix :math:`Q` is returned.

            :math:`\mathrm{compq} = \texttt{'V'}`

                :math:`\mathrm{q}` must contain a unitary matrix :math:`Q_1`, and the product :math:`Q_1Q` is returned.

        **compz** : str, length 1
            Specifies the form of the computed unitary matrix :math:`Z`.

            :math:`\mathrm{compz} = \texttt{'N'}`

                Do not compute :math:`Z`.

            :math:`\mathrm{compz} = \texttt{'V'}`

                :math:`\mathrm{z}` must contain a unitary matrix :math:`Z_1`, and the product :math:`Z_1Z` is returned.

            :math:`\mathrm{compz} = \texttt{'I'}`

                The unitary matrix :math:`Z` is returned.

        **ilo** : int
            :math:`i_{\mathrm{lo}}` and :math:`i_{\mathrm{hi}}` as determined by a previous call to :meth:`zggbal`. Otherwise, they should be set to :math:`1` and :math:`n`, respectively.

        **ihi** : int
            :math:`i_{\mathrm{lo}}` and :math:`i_{\mathrm{hi}}` as determined by a previous call to :meth:`zggbal`. Otherwise, they should be set to :math:`1` and :math:`n`, respectively.

        **a** : complex, array-like, shape :math:`\left(n, n\right)`
            The matrix :math:`A` of the matrix pair :math:`\left(A, B\right)`. Usually, this is the matrix :math:`A` returned by :meth:`zunmqr`.

        **b** : complex, array-like, shape :math:`\left(n, n\right)`
            The upper triangular matrix :math:`B` of the matrix pair :math:`\left(A, B\right)`. Usually, this is the matrix :math:`B` returned by the :math:`QR` factorization function :meth:`zgeqrf`.

        **q** : complex, array-like, shape :math:`\left(:, :\right)`
            Note: the required extent for this argument in dimension 1 is determined as follows: if :math:`\mathrm{compq}\text{ in } (\texttt{'I'}, \texttt{'V'})`: :math:`n`; if :math:`\mathrm{compq}=\texttt{'N'}`: :math:`1`; otherwise: :math:`0`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{compq}\text{ in } (\texttt{'I'}, \texttt{'V'})`: :math:`n`; if :math:`\mathrm{compq}=\texttt{'N'}`: :math:`1`; otherwise: :math:`0`.

            If :math:`\mathrm{compq} = \texttt{'V'}`, :math:`\mathrm{q}` must contain a unitary matrix :math:`Q_1`.

            If :math:`\mathrm{compq} = \texttt{'N'}`, :math:`\mathrm{q}` is not referenced.

        **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 a unitary matrix :math:`Z_1`.

            If :math:`\mathrm{compz} = \texttt{'N'}`, :math:`\mathrm{z}` is not referenced.

    **Returns**
        **a** : complex, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{a}` is overwritten by the upper Hessenberg matrix :math:`H`.

        **b** : complex, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{b}` is overwritten by the upper triangular matrix :math:`T`.

        **q** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{compq} = \texttt{'I'}`, :math:`\mathrm{q}` contains the unitary matrix :math:`Q`.

            Iif :math:`\mathrm{compq} = \texttt{'V'}`, :math:`\mathrm{q}` is overwritten by :math:`Q_1Q`.

        **z** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{compz} = \texttt{'I'}`, :math:`\mathrm{z}` contains the unitary matrix :math:`Z`.

            If :math:`\mathrm{compz} = \texttt{'V'}`, :math:`\mathrm{z}` is overwritten by :math:`Z_1Z`.

    .. _f08ws-py2-py-errors:

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

                Constraint: :math:`\mathrm{compq} = \texttt{'N'}`, :math:`\texttt{'I'}` or :math:`\texttt{'V'}`.

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

                Constraint: :math:`\mathrm{compz} = \texttt{'N'}`, :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:`-4`)
                On entry, error in parameter :math:`\mathrm{ilo}`.

                Constraint: :math:`\mathrm{ilo}\geq 1`.

            (`errno` :math:`-5`)
                On entry, error in parameter :math:`\mathrm{ihi}`.

                Constraint: :math:`1\leq \mathrm{ilo}\leq \mathrm{ihi}\leq n`.

            (`errno` :math:`-5`)
                On entry, error in parameter :math:`\mathrm{ihi}`.

                Constraint: :math:`\mathrm{ilo} = 1` and :math:`\mathrm{ihi} = 0`.

    .. _f08ws-py2-py-notes:

    **Notes**
        ``zgghrd`` is usually the third step in the solution of the complex generalized eigenvalue problem

        .. math::
            Ax = \lambda Bx\text{.}

        The (optional) first step balances the two matrices using :meth:`zggbal`.
        In the second step, matrix :math:`B` is reduced to upper triangular form using the :math:`QR` factorization function :meth:`zgeqrf` and this unitary transformation :math:`Q` is applied to matrix :math:`A` by calling :meth:`zunmqr`.

        ``zgghrd`` reduces a pair of complex matrices :math:`\left(A, B\right)`, where :math:`B` is triangular, to the generalized upper Hessenberg form using unitary transformations.
        This two-sided transformation is of the form

        .. math::
            \begin{array}{c}Q^\mathrm{H}AZ = H\\Q^\mathrm{H}BZ = T\end{array}

        where :math:`H` is an upper Hessenberg matrix, :math:`T` is an upper triangular matrix and :math:`Q` and :math:`Z` are unitary matrices determined as products of Givens rotations.
        They may either be formed explicitly, or they may be postmultiplied into input matrices :math:`Q_1` and :math:`Z_1`, so that

        .. math::
            \begin{array}{c}Q_1AZ_1^\mathrm{H} = \left(Q_1Q\right)H\left(Z_1Z\right)^\mathrm{H}\text{,}\\Q_1BZ_1^\mathrm{H} = \left(Q_1Q\right)T\left(Z_1Z\right)^\mathrm{H}\text{.}\end{array}

    .. _f08ws-py2-py-references:

    **References**
        Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore

        Moler, C B and Stewart, G W, 1973, `An algorithm for generalized matrix eigenproblems`, SIAM J. Numer. Anal. (10), 241--256
    """
    raise NotImplementedError

def zgghd3(compq, compz, ilo, ihi, a, b, q, z):
    r"""
    ``zgghd3`` reduces a pair of complex matrices :math:`\left(A, B\right)`, where :math:`B` is upper triangular, to the generalized upper Hessenberg form using unitary transformations.

    .. _f08wt-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08wtf.html

    .. _f08wt-py2-py-parameters:

    **Parameters**
        **compq** : str, length 1
            Specifies the form of the computed unitary matrix :math:`Q`.

            :math:`\mathrm{compq} = \texttt{'N'}`

                Do not compute :math:`Q`.

            :math:`\mathrm{compq} = \texttt{'I'}`

                The unitary matrix :math:`Q` is returned.

            :math:`\mathrm{compq} = \texttt{'V'}`

                :math:`\mathrm{q}` must contain a unitary matrix :math:`Q_1`, and the product :math:`Q_1Q` is returned.

        **compz** : str, length 1
            Specifies the form of the computed unitary matrix :math:`Z`.

            :math:`\mathrm{compz} = \texttt{'N'}`

                Do not compute :math:`Z`.

            :math:`\mathrm{compz} = \texttt{'V'}`

                :math:`\mathrm{z}` must contain a unitary matrix :math:`Z_1`, and the product :math:`Z_1Z` is returned.

            :math:`\mathrm{compz} = \texttt{'I'}`

                The unitary matrix :math:`Z` is returned.

        **ilo** : int
            :math:`i_{\mathrm{lo}}` and :math:`i_{\mathrm{hi}}` as determined by a previous call to :meth:`zggbal`. Otherwise, they should be set to :math:`1` and :math:`n`, respectively.

        **ihi** : int
            :math:`i_{\mathrm{lo}}` and :math:`i_{\mathrm{hi}}` as determined by a previous call to :meth:`zggbal`. Otherwise, they should be set to :math:`1` and :math:`n`, respectively.

        **a** : complex, array-like, shape :math:`\left(n, n\right)`
            The matrix :math:`A` of the matrix pair :math:`\left(A, B\right)`. Usually, this is the matrix :math:`A` returned by :meth:`zunmqr`.

        **b** : complex, array-like, shape :math:`\left(n, n\right)`
            The upper triangular matrix :math:`B` of the matrix pair :math:`\left(A, B\right)`. Usually, this is the matrix :math:`B` returned by the :math:`QR` factorization function :meth:`zgeqrf`.

        **q** : complex, array-like, shape :math:`\left(:, :\right)`
            Note: the required extent for this argument in dimension 1 is determined as follows: if :math:`\mathrm{compq}\text{ in } (\texttt{'I'}, \texttt{'V'})`: :math:`n`; if :math:`\mathrm{compq}=\texttt{'N'}`: :math:`1`; otherwise: :math:`0`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{compq}\text{ in } (\texttt{'I'}, \texttt{'V'})`: :math:`n`; if :math:`\mathrm{compq}=\texttt{'N'}`: :math:`1`; otherwise: :math:`0`.

            If :math:`\mathrm{compq} = \texttt{'V'}`, :math:`\mathrm{q}` must contain a unitary matrix :math:`Q_1`.

            If :math:`\mathrm{compq} = \texttt{'N'}`, :math:`\mathrm{q}` is not referenced.

        **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 a unitary matrix :math:`Z_1`.

            If :math:`\mathrm{compz} = \texttt{'N'}`, :math:`\mathrm{z}` is not referenced.

    **Returns**
        **a** : complex, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{a}` is overwritten by the upper Hessenberg matrix :math:`H`.

        **b** : complex, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{b}` is overwritten by the upper triangular matrix :math:`T`.

        **q** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{compq} = \texttt{'I'}`, :math:`\mathrm{q}` contains the unitary matrix :math:`Q`.

            Iif :math:`\mathrm{compq} = \texttt{'V'}`, :math:`\mathrm{q}` is overwritten by :math:`Q_1Q`.

        **z** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{compz} = \texttt{'I'}`, :math:`\mathrm{z}` contains the unitary matrix :math:`Z`.

            If :math:`\mathrm{compz} = \texttt{'V'}`, :math:`\mathrm{z}` is overwritten by :math:`Z_1Z`.

    .. _f08wt-py2-py-errors:

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

                Constraint: :math:`\mathrm{compq} = \texttt{'N'}`, :math:`\texttt{'I'}` or :math:`\texttt{'V'}`.

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

                Constraint: :math:`\mathrm{compz} = \texttt{'N'}`, :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:`-4`)
                On entry, error in parameter :math:`\mathrm{ilo}`.

                Constraint: :math:`\mathrm{ilo}\geq 1`.

            (`errno` :math:`-5`)
                On entry, error in parameter :math:`\mathrm{ihi}`.

                Constraint: :math:`1\leq \mathrm{ilo}\leq \mathrm{ihi}\leq n`.

            (`errno` :math:`-5`)
                On entry, error in parameter :math:`\mathrm{ihi}`.

                Constraint: :math:`\mathrm{ilo} = 1` and :math:`\mathrm{ihi} = 0`.

    .. _f08wt-py2-py-notes:

    **Notes**
        ``zgghd3`` is usually the third step in the solution of the complex generalized eigenvalue problem

        .. math::
            Ax = \lambda Bx\text{.}

        The (optional) first step balances the two matrices using :meth:`zggbal`.
        In the second step, matrix :math:`B` is reduced to upper triangular form using the :math:`QR` factorization function :meth:`zgeqrf` and this unitary transformation :math:`Q` is applied to matrix :math:`A` by calling :meth:`zunmqr`.
        The driver, :meth:`zggev3`, solves the complex generalized eigenvalue problem by combining all the required steps including those just listed.

        ``zgghd3`` reduces a pair of complex matrices :math:`\left(A, B\right)`, where :math:`B` is triangular, to the generalized upper Hessenberg form using unitary transformations.
        This two-sided transformation is of the form

        .. math::
            \begin{array}{c}Q^\mathrm{H}AZ = H\text{,}\\Q^\mathrm{H}BZ = T\end{array}

        where :math:`H` is an upper Hessenberg matrix, :math:`T` is an upper triangular matrix and :math:`Q` and :math:`Z` are unitary matrices determined as products of Givens rotations.
        They may either be formed explicitly, or they may be postmultiplied into input matrices :math:`Q_1` and :math:`Z_1`, so that

        .. math::
            \begin{array}{c}Q_1AZ_1^\mathrm{H} = \left(Q_1Q\right)H\left(Z_1Z\right)^\mathrm{H}\text{,}\\Q_1BZ_1^\mathrm{H} = \left(Q_1Q\right)T\left(Z_1Z\right)^\mathrm{H}\text{.}\end{array}

    .. _f08wt-py2-py-references:

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

        Moler, C B and Stewart, G W, 1973, `An algorithm for generalized matrix eigenproblems`, SIAM J. Numer. Anal. (10), 241--256
    """
    raise NotImplementedError

def zggbal(job, n, a, b):
    r"""
    ``zggbal`` balances a pair of complex square matrices :math:`\left(A, B\right)` of order :math:`n`.
    Balancing usually improves the accuracy of computed generalized eigenvalues and eigenvectors.

    .. _f08wv-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08wvf.html

    .. _f08wv-py2-py-parameters:

    **Parameters**
        **job** : str, length 1
            Specifies the operations to be performed on matrices :math:`A` and :math:`B`.

            :math:`\mathrm{job} = \texttt{'N'}`

                No balancing is done. Initialize :math:`\mathrm{ilo} = 1`, :math:`\mathrm{ihi} = \mathrm{n}`, :math:`\mathrm{lscale}[\textit{i}-1] = 1.0` and :math:`\mathrm{rscale}[\textit{i}-1] = 1.0`, for :math:`\textit{i} = 1,2,\ldots,n`.

            :math:`\mathrm{job} = \texttt{'P'}`

                Only permutations are used in balancing.

            :math:`\mathrm{job} = \texttt{'S'}`

                Only scalings are are used in balancing.

            :math:`\mathrm{job} = \texttt{'B'}`

                Both permutations and scalings are used in balancing.

        **n** : int
            :math:`n`, the order of the matrices :math:`A` and :math:`B`.

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

        **b** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)`
            The :math:`n\times n` matrix :math:`B`.

    **Returns**
        **a** : complex, 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.

        **b** : complex, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)`
            :math:`\mathrm{b}` is overwritten by the balanced matrix. If :math:`\mathrm{job} = \texttt{'N'}`, :math:`\mathrm{b}` is not referenced.

        **ilo** : int
            :math:`i_{\mathrm{lo}}` and :math:`i_{\mathrm{hi}}` are set such that :math:`\mathrm{a}[i-1,j-1] = 0` and :math:`\mathrm{b}[i-1,j-1] = 0` 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
            :math:`i_{\mathrm{lo}}` and :math:`i_{\mathrm{hi}}` are set such that :math:`\mathrm{a}[i-1,j-1] = 0` and :math:`\mathrm{b}[i-1,j-1] = 0` 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`.

        **lscale** : float, ndarray, shape :math:`\left(\mathrm{n}\right)`
            Details of the permutations and scaling factors applied to the left side of the matrices :math:`A` and :math:`B`. If :math:`P_i` is the index of the row interchanged with row :math:`i` and :math:`d_i` is the scaling factor applied to row :math:`i`, then

                :math:`\mathrm{lscale}[\textit{i}-1] = P_{\textit{i}}`, for :math:`\textit{i} = 1,2,\ldots,\textit{i}_{\mathrm{lo}}-1`;

                :math:`\mathrm{lscale}[\textit{i}-1] = \textit{d}_{\textit{i}}`, for :math:`\textit{i} = \textit{i}_{\mathrm{lo}},\ldots,\textit{i}_{\mathrm{hi}}`;

                :math:`\mathrm{lscale}[\textit{i}-1] = P_{\textit{i}}`, for :math:`\textit{i} = \textit{i}_{\mathrm{hi}}+1,\ldots,n`.

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

        **rscale** : float, ndarray, shape :math:`\left(\mathrm{n}\right)`
            Details of the permutations and scaling factors applied to the right side of the matrices :math:`A` and :math:`B`.

            If :math:`P_j` is the index of the column interchanged with column :math:`j` and :math:`\hat{d}_j` is the scaling factor applied to column :math:`j`, then

                :math:`\mathrm{rscale}[\textit{j}-1] = P_{\textit{j}}`, for :math:`\textit{j} = 1,2,\ldots,\textit{i}_{\mathrm{lo}}-1`;

                :math:`\mathrm{rscale}[\textit{j}-1] = \hat{d}_{\textit{j}}`, for :math:`\textit{j} = i_{\mathrm{lo}},\ldots,i_{\mathrm{hi}}`;

                :math:`\mathrm{rscale}[\textit{j}-1] = P_{\textit{j}}`, for :math:`\textit{j} = i_{\mathrm{hi}}+1,\ldots,n`.

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

    .. _f08wv-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`.

    .. _f08wv-py2-py-notes:

    **Notes**
        Balancing may reduce the :math:`1`-norm of the matrices and improve the accuracy of the computed eigenvalues and eigenvectors in the complex generalized eigenvalue problem

        .. math::
            Ax = \lambda Bx\text{.}

        ``zggbal`` is usually the first step in the solution of the above generalized eigenvalue problem.
        Balancing is optional but it is highly recommended.

        The term 'balancing' covers two steps, each of which involves similarity transformations on :math:`A` and :math:`B`.
        The function can perform either or both of these steps.
        Both steps are optional.

        (1) The function first attempts to permute :math:`A` and :math:`B` to block upper triangular form by a similarity transformation:

            .. math::
                PAP^\mathrm{T} = F = \begin{pmatrix}F_{11}&F_{12}&F_{13}\\&F_{22}&F_{23}\\&&F_{33}\end{pmatrix}

            .. math::
                PBP^\mathrm{T} = G = \begin{pmatrix}G_{11}&G_{12}&G_{13}\\&G_{22}&G_{23}\\&&G_{33}\end{pmatrix}

            where :math:`P` is a permutation matrix, :math:`F_{11}`, :math:`F_{33}`, :math:`G_{11}` and :math:`G_{33}` are upper triangular. Then the diagonal elements of the matrix pairs :math:`\left(F_{11}, G_{11}\right)` and :math:`\left(F_{33}, G_{33}\right)` are generalized eigenvalues of :math:`\left(A, B\right)`. The rest of the generalized eigenvalues are given by the matrix pair :math:`\left(F_{22}, G_{22}\right)` which are in rows and columns :math:`i_{\mathrm{lo}}` to :math:`i_{\mathrm{hi}}`. Subsequent operations to compute the generalized eigenvalues of :math:`\left(A, B\right)` need only be applied to the matrix pair :math:`\left(F_{22}, G_{22}\right)`; 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`.

        (#) The function applies a diagonal similarity transformation to :math:`\left(F, G\right)`, to make the rows and columns of :math:`\left(F_{22}, G_{22}\right)` as close in norm as possible:

            .. math::
                DF\hat{D} = \begin{pmatrix}I&0&0\\0&D_{22}&0\\0&0&I\end{pmatrix}\begin{pmatrix}F_{11}&F_{12}&F_{13}\\&F_{22}&F_{23}\\&&F_{33}\end{pmatrix}\begin{pmatrix}I&0&0\\0&\hat{D}_{22}&0\\0&0&I\end{pmatrix}

            .. math::
                DGD^{-1} = \begin{pmatrix}I&0&0\\0&D_{22}&0\\0&0&I\end{pmatrix}\begin{pmatrix}G_{11}&G_{12}&G_{13}\\&G_{22}&G_{23}\\&&G_{33}\end{pmatrix}\begin{pmatrix}I&0&0\\0&\hat{D}_{22}&0\\0&0&I\end{pmatrix}

            This transformation usually improves the accuracy of computed generalized eigenvalues and eigenvectors.

    .. _f08wv-py2-py-references:

    **References**
        Ward, R C, 1981, `Balancing the generalized eigenvalue problem`, SIAM J. Sci. Stat. Comp. (2), 141--152
    """
    raise NotImplementedError

def zggbak(job, side, ilo, ihi, lscale, rscale, v):
    r"""
    ``zggbak`` forms the right or left eigenvectors of the real generalized eigenvalue problem :math:`Ax = \lambda Bx`, by backward transformation on the computed eigenvectors given by :meth:`ztgevc`.
    It is necessary to call this function only if the optional balancing function :meth:`zggbal` was previously called to balance the matrix pair :math:`\left(A, B\right)`.

    .. _f08ww-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08wwf.html

    .. _f08ww-py2-py-parameters:

    **Parameters**
        **job** : str, length 1
            Specifies the backtransformation step required.

            :math:`\mathrm{job} = \texttt{'N'}`

                No transformations are done.

            :math:`\mathrm{job} = \texttt{'P'}`

                Only do backward transformations based on permutations.

            :math:`\mathrm{job} = \texttt{'S'}`

                Only do backward transformations based on scaling.

            :math:`\mathrm{job} = \texttt{'B'}`

                Do backward transformations for both permutations and scaling.

            **Note:** this must be identical to the argument :math:`\mathrm{job}` as supplied to :meth:`zggbal`.

        **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
            :math:`i_{\mathrm{lo}}` and :math:`i_{\mathrm{hi}}` as determined by a previous call to :meth:`zggbal`.

        **ihi** : int
            :math:`i_{\mathrm{lo}}` and :math:`i_{\mathrm{hi}}` as determined by a previous call to :meth:`zggbal`.

        **lscale** : float, array-like, shape :math:`\left(n\right)`
            Details of the permutations and scaling factors applied to the left side of the matrices :math:`A` and :math:`B`, as returned by a previous call to :meth:`zggbal`.

        **rscale** : float, array-like, shape :math:`\left(n\right)`
            Details of the permutations and scaling factors applied to the right side of the matrices :math:`A` and :math:`B`, as returned by a previous call to :meth:`zggbal`.

        **v** : complex, array-like, shape :math:`\left(n, m\right)`
            The matrix of right or left eigenvectors, as returned by :meth:`zggbal`.

    **Returns**
        **v** : complex, ndarray, shape :math:`\left(n, m\right)`
            The transformed right or left eigenvectors.

    .. _f08ww-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:`-8`)
                On entry, error in parameter :math:`\textit{m}`.

                Constraint: :math:`0\leq m\leq n`.

    .. _f08ww-py2-py-notes:

    **Notes**
        If the matrix pair has been previously balanced using the function :meth:`zggbal` then ``zggbak`` backtransforms the eigenvector solution given by :meth:`ztgevc`.
        This is usually the sixth and last step in the solution of the generalized eigenvalue problem.

        For a description of balancing, see the document for :meth:`zggbal`.

    .. _f08ww-py2-py-references:

    **References**
        Ward, R C, 1981, `Balancing the generalized eigenvalue problem`, SIAM J. Sci. Stat. Comp. (2), 141--152
    """
    raise NotImplementedError

def dgges(jobvsl, jobvsr, sort, a, b, selctg=None, data=None):
    r"""
    ``dgges`` computes the generalized eigenvalues, the generalized real Schur form :math:`\left(S, T\right)` and, optionally, the left and/or right generalized Schur vectors for a pair of :math:`n\times n` real nonsymmetric matrices :math:`\left(A, B\right)`. ``dgges`` is marked as `deprecated` by LAPACK; the replacement routine is :meth:`dgges3` which makes better use of Level 3 BLAS.

    .. deprecated:: 27.0.0.0
        ``dgges`` is deprecated.
        Please use :meth:`dgges3` instead.
        See also the :ref:`Replacement Calls <replace>` document.

    .. _f08xa-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08xaf.html

    .. _f08xa-py2-py-parameters:

    **Parameters**
        **jobvsl** : str, length 1
            If :math:`\mathrm{jobvsl} = \texttt{'N'}`, do not compute the left Schur vectors.

            If :math:`\mathrm{jobvsl} = \texttt{'V'}`, compute the left Schur vectors.

        **jobvsr** : str, length 1
            If :math:`\mathrm{jobvsr} = \texttt{'N'}`, do not compute the right Schur vectors.

            If :math:`\mathrm{jobvsr} = \texttt{'V'}`, compute the right Schur vectors.

        **sort** : str, length 1
            Specifies whether or not to order the eigenvalues on the diagonal of the generalized Schur form.

            :math:`\mathrm{sort} = \texttt{'N'}`

                Eigenvalues are not ordered.

            :math:`\mathrm{sort} = \texttt{'S'}`

                Eigenvalues are ordered (see :math:`\mathrm{selctg}`).

        **a** : float, array-like, shape :math:`\left(n, n\right)`
            The first of the pair of matrices, :math:`A`.

        **b** : float, array-like, shape :math:`\left(n, n\right)`
            The second of the pair of matrices, :math:`B`.

        **selctg** : None or callable retval = selctg(ar, ai, b, data=None), optional
            Note: if this argument is **None** then a NAG-supplied facility will be used.

            If :math:`\mathrm{sort} = \texttt{'S'}`, :math:`\mathrm{selctg}` is used to select generalized eigenvalues to be moved to the top left of the generalized Schur form.

            **Parameters**
                **ar** : float
                    An eigenvalue :math:`\left(\mathrm{ar}[j-1]+\sqrt{-1}\times \mathrm{ai}[j-1]\right)/\mathrm{b}[j-1]` is selected if :math:`\mathrm{selctg}\left(\mathrm{ar}[j-1], \mathrm{ai}[j-1], \mathrm{b}[j-1]\right) = \mathbf{True}`. If either one of a complex conjugate pair is selected, then both complex generalized eigenvalues are selected.

                    Note that in the ill-conditioned case, a selected complex generalized eigenvalue may no longer satisfy :math:`\mathrm{selctg}\left(\mathrm{ar}[j-1], \mathrm{ai}[j-1], \mathrm{b}[j-1]\right) = \mathbf{True}` after ordering. :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 2 in this case.

                **ai** : float
                    An eigenvalue :math:`\left(\mathrm{ar}[j-1]+\sqrt{-1}\times \mathrm{ai}[j-1]\right)/\mathrm{b}[j-1]` is selected if :math:`\mathrm{selctg}\left(\mathrm{ar}[j-1], \mathrm{ai}[j-1], \mathrm{b}[j-1]\right) = \mathbf{True}`. If either one of a complex conjugate pair is selected, then both complex generalized eigenvalues are selected.

                    Note that in the ill-conditioned case, a selected complex generalized eigenvalue may no longer satisfy :math:`\mathrm{selctg}\left(\mathrm{ar}[j-1], \mathrm{ai}[j-1], \mathrm{b}[j-1]\right) = \mathbf{True}` after ordering. :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 2 in this case.

                **b** : float
                    An eigenvalue :math:`\left(\mathrm{ar}[j-1]+\sqrt{-1}\times \mathrm{ai}[j-1]\right)/\mathrm{b}[j-1]` is selected if :math:`\mathrm{selctg}\left(\mathrm{ar}[j-1], \mathrm{ai}[j-1], \mathrm{b}[j-1]\right) = \mathbf{True}`. If either one of a complex conjugate pair is selected, then both complex generalized eigenvalues are selected.

                    Note that in the ill-conditioned case, a selected complex generalized eigenvalue may no longer satisfy :math:`\mathrm{selctg}\left(\mathrm{ar}[j-1], \mathrm{ai}[j-1], \mathrm{b}[j-1]\right) = \mathbf{True}` after ordering. :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 2 in this case.

                **data** : arbitrary, optional, modifiable in place
                    User-communication data for callback functions.

            **Returns**
                **retval** : bool
                    Must be :math:`\mathbf{True}` if the eigenvalue is to be selected.

        **data** : arbitrary, optional
            User-communication data for callback functions.

    **Returns**
        **a** : float, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{a}` has been overwritten by its generalized Schur form :math:`S`.

        **b** : float, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{b}` has been overwritten by its generalized Schur form :math:`T`.

        **sdim** : int
            If :math:`\mathrm{sort} = \texttt{'N'}`, :math:`\mathrm{sdim} = 0`.

            If :math:`\mathrm{sort} = \texttt{'S'}`, :math:`\mathrm{sdim} = \text{}` number of eigenvalues (after sorting) for which :math:`\mathrm{selctg}` is :math:`\mathbf{True}`. (Complex conjugate pairs for which :math:`\mathrm{selctg}` is :math:`\mathbf{True}` for either eigenvalue count as :math:`2`.)

        **alphar** : float, ndarray, shape :math:`\left(n\right)`
            See the description of :math:`\mathrm{beta}`.

        **alphai** : float, ndarray, shape :math:`\left(n\right)`
            See the description of :math:`\mathrm{beta}`.

        **beta** : float, ndarray, shape :math:`\left(n\right)`
            :math:`\left(\mathrm{alphar}[\textit{j}-1]+\mathrm{alphai}[\textit{j}-1]\times i\right)/\mathrm{beta}[\textit{j}-1]`, for :math:`\textit{j} = 1,2,\ldots,n`, will be the generalized eigenvalues. :math:`\mathrm{alphar}[\textit{j}-1]+\mathrm{alphai}[\textit{j}-1]\times i`, and :math:`\mathrm{beta}[\textit{j}-1]`, for :math:`\textit{j} = 1,2,\ldots,n`, are the diagonals of the complex Schur form :math:`\left(S, T\right)` that would result if the :math:`2\times 2` diagonal blocks of the real Schur form of :math:`\left(A, B\right)` were further reduced to triangular form using :math:`2\times 2` complex unitary transformations.

            If :math:`\mathrm{alphai}[j-1]` is zero, then the :math:`j`\ th eigenvalue is real; if positive, then the :math:`j`\ th and :math:`\left(j+1\right)`\ st eigenvalues are a complex conjugate pair, with :math:`\mathrm{alphai}[j]` negative.

            **Note:** the quotients :math:`\mathrm{alphar}[j-1]/\mathrm{beta}[j-1]` and :math:`\mathrm{alphai}[j-1]/\mathrm{beta}[j-1]` may easily overflow or underflow, and :math:`\mathrm{beta}[j-1]` may even be zero.

            Thus, you should avoid naively computing the ratio :math:`\alpha /\beta`.

            However, :math:`\mathrm{alphar}` and :math:`\mathrm{alphai}` will always be less than and usually comparable with :math:`\left\lVert A\right\rVert_2` in magnitude, and :math:`\mathrm{beta}` will always be less than and usually comparable with :math:`\left\lVert B\right\rVert_2`.

        **vsl** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobvsl} = \texttt{'V'}`, :math:`\mathrm{vsl}` will contain the left Schur vectors, :math:`Q`.

            If :math:`\mathrm{jobvsl} = \texttt{'N'}`, :math:`\mathrm{vsl}` is not referenced.

        **vsr** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobvsr} = \texttt{'V'}`, :math:`\mathrm{vsr}` will contain the right Schur vectors, :math:`Z`.

            If :math:`\mathrm{jobvsr} = \texttt{'N'}`, :math:`\mathrm{vsr}` is not referenced.

    .. _f08xa-py2-py-errors:

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

                Constraint: :math:`\mathrm{jobvsl} = \texttt{'N'}` or :math:`\texttt{'V'}`.

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

                Constraint: :math:`\mathrm{jobvsr} = \texttt{'N'}` or :math:`\texttt{'V'}`.

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

                Constraint: :math:`\mathrm{sort} = \texttt{'N'}` or :math:`\texttt{'S'}`.

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

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

            (`errno` :math:`n+1`)
                The :math:`QZ` iteration failed with an unexpected error, please contact `NAG <https://www.nag.com>`__.

    **Warns**
        **NagAlgorithmicWarning**
            (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq n\right)`)
                The :math:`QZ` iteration failed. No eigenvectors have been calculated but :math:`\mathrm{alphar}[j]`, :math:`\mathrm{alphai}[j]` and :math:`\mathrm{beta}[j]` should be correct from element :math:`\langle\mathit{\boldsymbol{value}}\rangle`.

            (`errno` :math:`n+2`)
                After reordering, roundoff changed values of some complex eigenvalues so that leading eigenvalues in the generalized Schur form no longer satisfy :math:`\mathrm{selctg} = \mathbf{True}`. This could also be caused by underflow due to scaling.

            (`errno` :math:`n+3`)
                The eigenvalues could not be reordered because some eigenvalues were too close to separate (the problem is very ill-conditioned).

    .. _f08xa-py2-py-notes:

    **Notes**
        The generalized Schur factorization for a pair of real matrices :math:`\left(A, B\right)` is given by

        .. math::
            A = QSZ^\mathrm{T}\text{, }\quad B = QTZ^\mathrm{T}\text{,}

        where :math:`Q` and :math:`Z` are orthogonal, :math:`T` is upper triangular and :math:`S` is upper quasi-triangular with :math:`1\times 1` and :math:`2\times 2` diagonal blocks.
        The generalized eigenvalues, :math:`\lambda`, of :math:`\left(A, B\right)` are computed from the diagonals of :math:`S` and :math:`T` and satisfy

        .. math::
            Az = \lambda Bz\text{,}

        where :math:`z` is the corresponding generalized eigenvector. :math:`\lambda` is actually returned as the pair :math:`\left(\alpha, \beta \right)` such that

        .. math::
            \lambda = \alpha /\beta

        since :math:`\beta`, or even both :math:`\alpha` and :math:`\beta` can be zero.
        The columns of :math:`Q` and :math:`Z` are the left and right generalized Schur vectors of :math:`\left(A, B\right)`.

        Optionally, ``dgges`` can order the generalized eigenvalues on the diagonals of :math:`\left(S, T\right)` so that selected eigenvalues are at the top left.
        The leading columns of :math:`Q` and :math:`Z` then form an orthonormal basis for the corresponding eigenspaces, the deflating subspaces.

        ``dgges`` computes :math:`T` to have non-negative diagonal elements, and the :math:`2\times 2` blocks of :math:`S` correspond to complex conjugate pairs of generalized eigenvalues.
        The generalized Schur factorization, before reordering, is computed by the :math:`QZ` algorithm.

    .. _f08xa-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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 dggesx(jobvsl, jobvsr, sort, sense, a, b, selctg=None, data=None):
    r"""
    ``dggesx`` computes the generalized eigenvalues, the generalized real Schur form :math:`\left(S, T\right)` and, optionally, the left and/or right generalized Schur vectors for a pair of :math:`n\times n` real nonsymmetric matrices :math:`\left(A, B\right)`.

    Estimates of condition numbers for selected generalized eigenvalue clusters and Schur vectors are also computed.

    .. _f08xb-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08xbf.html

    .. _f08xb-py2-py-parameters:

    **Parameters**
        **jobvsl** : str, length 1
            If :math:`\mathrm{jobvsl} = \texttt{'N'}`, do not compute the left Schur vectors.

            If :math:`\mathrm{jobvsl} = \texttt{'V'}`, compute the left Schur vectors.

        **jobvsr** : str, length 1
            If :math:`\mathrm{jobvsr} = \texttt{'N'}`, do not compute the right Schur vectors.

            If :math:`\mathrm{jobvsr} = \texttt{'V'}`, compute the right Schur vectors.

        **sort** : str, length 1
            Specifies whether or not to order the eigenvalues on the diagonal of the generalized Schur form.

            :math:`\mathrm{sort} = \texttt{'N'}`

                Eigenvalues are not ordered.

            :math:`\mathrm{sort} = \texttt{'S'}`

                Eigenvalues are ordered (see :math:`\mathrm{selctg}`).

        **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 average of selected eigenvalues only.

            :math:`\mathrm{sense} = \texttt{'V'}`

                Computed for selected deflating subspaces only.

            :math:`\mathrm{sense} = \texttt{'B'}`

                Computed for both.

            If :math:`\mathrm{sense} = \texttt{'E'}`, :math:`\texttt{'V'}` or :math:`\texttt{'B'}`, :math:`\mathrm{sort} = \texttt{'S'}`.

        **a** : float, array-like, shape :math:`\left(n, n\right)`
            The first of the pair of matrices, :math:`A`.

        **b** : float, array-like, shape :math:`\left(n, n\right)`
            The second of the pair of matrices, :math:`B`.

        **selctg** : None or callable retval = selctg(ar, ai, b, data=None), optional
            Note: if this argument is **None** then a NAG-supplied facility will be used.

            If :math:`\mathrm{sort} = \texttt{'S'}`, :math:`\mathrm{selctg}` is used to select generalized eigenvalues to be moved to the top left of the generalized Schur form.

            **Parameters**
                **ar** : float
                    An eigenvalue :math:`\left(\mathrm{ar}[j-1]+\sqrt{-1}\times \mathrm{ai}[j-1]\right)/\mathrm{b}[j-1]` is selected if :math:`\mathrm{selctg}\left(\mathrm{ar}[j-1], \mathrm{ai}[j-1], \mathrm{b}[j-1]\right)` is :math:`\mathbf{True}`. If either one of a complex conjugate pair is selected, then both complex generalized eigenvalues are selected.

                    Note that in the ill-conditioned case, a selected complex generalized eigenvalue may no longer satisfy :math:`\mathrm{selctg}\left(\mathrm{ar}[j-1], \mathrm{ai}[j-1], \mathrm{b}[j-1]\right) = \mathbf{True}` after ordering. :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 2 in this case.

                **ai** : float
                    An eigenvalue :math:`\left(\mathrm{ar}[j-1]+\sqrt{-1}\times \mathrm{ai}[j-1]\right)/\mathrm{b}[j-1]` is selected if :math:`\mathrm{selctg}\left(\mathrm{ar}[j-1], \mathrm{ai}[j-1], \mathrm{b}[j-1]\right)` is :math:`\mathbf{True}`. If either one of a complex conjugate pair is selected, then both complex generalized eigenvalues are selected.

                    Note that in the ill-conditioned case, a selected complex generalized eigenvalue may no longer satisfy :math:`\mathrm{selctg}\left(\mathrm{ar}[j-1], \mathrm{ai}[j-1], \mathrm{b}[j-1]\right) = \mathbf{True}` after ordering. :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 2 in this case.

                **b** : float
                    An eigenvalue :math:`\left(\mathrm{ar}[j-1]+\sqrt{-1}\times \mathrm{ai}[j-1]\right)/\mathrm{b}[j-1]` is selected if :math:`\mathrm{selctg}\left(\mathrm{ar}[j-1], \mathrm{ai}[j-1], \mathrm{b}[j-1]\right)` is :math:`\mathbf{True}`. If either one of a complex conjugate pair is selected, then both complex generalized eigenvalues are selected.

                    Note that in the ill-conditioned case, a selected complex generalized eigenvalue may no longer satisfy :math:`\mathrm{selctg}\left(\mathrm{ar}[j-1], \mathrm{ai}[j-1], \mathrm{b}[j-1]\right) = \mathbf{True}` after ordering. :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 2 in this case.

                **data** : arbitrary, optional, modifiable in place
                    User-communication data for callback functions.

            **Returns**
                **retval** : bool
                    Must be :math:`\mathbf{True}` if the eigenvalue is to be selected.

        **data** : arbitrary, optional
            User-communication data for callback functions.

    **Returns**
        **a** : float, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{a}` has been overwritten by its generalized Schur form :math:`S`.

        **b** : float, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{b}` has been overwritten by its generalized Schur form :math:`T`.

        **sdim** : int
            If :math:`\mathrm{sort} = \texttt{'N'}`, :math:`\mathrm{sdim} = 0`.

            If :math:`\mathrm{sort} = \texttt{'S'}`, :math:`\mathrm{sdim} = \text{}` number of eigenvalues (after sorting) for which :math:`\mathrm{selctg}` is :math:`\mathbf{True}`. (Complex conjugate pairs for which :math:`\mathrm{selctg}` is :math:`\mathbf{True}` for either eigenvalue count as :math:`2`.)

        **alphar** : float, ndarray, shape :math:`\left(n\right)`
            See the description of :math:`\mathrm{beta}`.

        **alphai** : float, ndarray, shape :math:`\left(n\right)`
            See the description of :math:`\mathrm{beta}`.

        **beta** : float, ndarray, shape :math:`\left(n\right)`
            :math:`\left(\mathrm{alphar}[\textit{j}-1]+\mathrm{alphai}[\textit{j}-1]\times i\right)/\mathrm{beta}[\textit{j}-1]`, for :math:`\textit{j} = 1,2,\ldots,n`, will be the generalized eigenvalues. :math:`\mathrm{alphar}[\textit{j}-1]+\mathrm{alphai}[\textit{j}-1]\times i`, and :math:`\mathrm{beta}[\textit{j}-1]`, for :math:`\textit{j} = 1,2,\ldots,n`, are the diagonals of the complex Schur form :math:`\left(S, T\right)` that would result if the :math:`2\times 2` diagonal blocks of the real Schur form of :math:`\left(A, B\right)` were further reduced to triangular form using :math:`2\times 2` complex unitary transformations.

            If :math:`\mathrm{alphai}[j-1]` is zero, then the :math:`j`\ th eigenvalue is real; if positive, then the :math:`j`\ th and :math:`\left(j+1\right)`\ st eigenvalues are a complex conjugate pair, with :math:`\mathrm{alphai}[j]` negative.

            **Note:** the quotients :math:`\mathrm{alphar}[j-1]/\mathrm{beta}[j-1]` and :math:`\mathrm{alphai}[j-1]/\mathrm{beta}[j-1]` may easily overflow or underflow, and :math:`\mathrm{beta}[j-1]` may even be zero.

            Thus, you should avoid naively computing the ratio :math:`\alpha /\beta`.

            However, :math:`\mathrm{alphar}` and :math:`\mathrm{alphai}` will always be less than and usually comparable with :math:`\left\lVert A\right\rVert_2` in magnitude, and :math:`\mathrm{beta}` will always be less than and usually comparable with :math:`\left\lVert B\right\rVert_2`.

        **vsl** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobvsl} = \texttt{'V'}`, :math:`\mathrm{vsl}` will contain the left Schur vectors, :math:`Q`.

            If :math:`\mathrm{jobvsl} = \texttt{'N'}`, :math:`\mathrm{vsl}` is not referenced.

        **vsr** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobvsr} = \texttt{'V'}`, :math:`\mathrm{vsr}` will contain the right Schur vectors, :math:`Z`.

            If :math:`\mathrm{jobvsr} = \texttt{'N'}`, :math:`\mathrm{vsr}` is not referenced.

        **rconde** : float, ndarray, shape :math:`\left(2\right)`
            If :math:`\mathrm{sense} = \texttt{'E'}` or :math:`\texttt{'B'}`, :math:`\mathrm{rconde}[0]` and :math:`\mathrm{rconde}[1]` contain the reciprocal condition numbers for the average of the selected eigenvalues.

            If :math:`\mathrm{sense} = \texttt{'N'}` or :math:`\texttt{'V'}`, :math:`\mathrm{rconde}` is not referenced.

        **rcondv** : float, ndarray, shape :math:`\left(2\right)`
            If :math:`\mathrm{sense} = \texttt{'V'}` or :math:`\texttt{'B'}`, :math:`\mathrm{rcondv}[0]` and :math:`\mathrm{rcondv}[1]` contain the reciprocal condition numbers for the selected deflating subspaces.

            if :math:`\mathrm{sense} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{rcondv}` is not referenced.

    .. _f08xb-py2-py-errors:

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

                Constraint: :math:`\mathrm{jobvsl} = \texttt{'N'}` or :math:`\texttt{'V'}`.

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

                Constraint: :math:`\mathrm{jobvsr} = \texttt{'N'}` or :math:`\texttt{'V'}`.

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

                Constraint: :math:`\mathrm{sort} = \texttt{'N'}` or :math:`\texttt{'S'}`.

            (`errno` :math:`-5`)
                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:`-6`)
                On entry, error in parameter :math:`\textit{n}`.

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

            (`errno` :math:`n+1`)
                The :math:`QZ` iteration failed with an unexpected error, please contact `NAG <https://www.nag.com>`__.

    **Warns**
        **NagAlgorithmicWarning**
            (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq n\right)`)
                The :math:`QZ` iteration failed. No eigenvectors have been calculated but :math:`\mathrm{alphar}[j]`, :math:`\mathrm{alphai}[j]` and :math:`\mathrm{beta}[j]` should be correct from element :math:`\langle\mathit{\boldsymbol{value}}\rangle`.

            (`errno` :math:`n+2`)
                After reordering, roundoff changed values of some complex eigenvalues so that leading eigenvalues in the generalized Schur form no longer satisfy :math:`\mathrm{selctg} = \mathbf{True}`. This could also be caused by underflow due to scaling.

            (`errno` :math:`n+3`)
                The eigenvalues could not be reordered because some eigenvalues were too close to separate (the problem is very ill-conditioned).

    .. _f08xb-py2-py-notes:

    **Notes**
        The generalized real Schur factorization of :math:`\left(A, B\right)` is given by

        .. math::
            A = QSZ^\mathrm{T}\text{, }\quad B = QTZ^\mathrm{T}\text{,}

        where :math:`Q` and :math:`Z` are orthogonal, :math:`T` is upper triangular and :math:`S` is upper quasi-triangular with :math:`1\times 1` and :math:`2\times 2` diagonal blocks.
        The generalized eigenvalues, :math:`\lambda`, of :math:`\left(A, B\right)` are computed from the diagonals of :math:`T` and :math:`S` and satisfy

        .. math::
            Az = \lambda Bz\text{,}

        where :math:`z` is the corresponding generalized eigenvector. :math:`\lambda` is actually returned as the pair :math:`\left(\alpha, \beta \right)` such that

        .. math::
            \lambda = \alpha /\beta

        since :math:`\beta`, or even both :math:`\alpha` and :math:`\beta` can be zero.
        The columns of :math:`Q` and :math:`Z` are the left and right generalized Schur vectors of :math:`\left(A, B\right)`.

        Optionally, ``dggesx`` can order the generalized eigenvalues on the diagonals of :math:`\left(S, T\right)` so that selected eigenvalues are at the top left.
        The leading columns of :math:`Q` and :math:`Z` then form an orthonormal basis for the corresponding eigenspaces, the deflating subspaces.

        ``dggesx`` computes :math:`T` to have non-negative diagonal elements, and the :math:`2\times 2` blocks of :math:`S` correspond to complex conjugate pairs of generalized eigenvalues.
        The generalized Schur factorization, before reordering, is computed by the :math:`QZ` algorithm.

        The reciprocals of the condition estimates, the reciprocal values of the left and right projection norms, are returned in :math:`\mathrm{rconde}[0]` and :math:`\mathrm{rconde}[1]` respectively, for the selected generalized eigenvalues, together with reciprocal condition estimates for the corresponding left and right deflating subspaces, in :math:`\mathrm{rcondv}[0]` and :math:`\mathrm{rcondv}[1]`.
        See Section 4.11 of Anderson `et al.` (1999) for further information.

    .. _f08xb-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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 dgges3(jobvsl, jobvsr, sort, a, b, selctg=None, data=None):
    r"""
    ``dgges3`` computes the generalized eigenvalues, the generalized real Schur form :math:`\left(S, T\right)` and, optionally, the left and/or right generalized Schur vectors for a pair of :math:`n\times n` real nonsymmetric matrices :math:`\left(A, B\right)`.

    .. _f08xc-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08xcf.html

    .. _f08xc-py2-py-parameters:

    **Parameters**
        **jobvsl** : str, length 1
            If :math:`\mathrm{jobvsl} = \texttt{'N'}`, do not compute the left Schur vectors.

            If :math:`\mathrm{jobvsl} = \texttt{'V'}`, compute the left Schur vectors.

        **jobvsr** : str, length 1
            If :math:`\mathrm{jobvsr} = \texttt{'N'}`, do not compute the right Schur vectors.

            If :math:`\mathrm{jobvsr} = \texttt{'V'}`, compute the right Schur vectors.

        **sort** : str, length 1
            Specifies whether or not to order the eigenvalues on the diagonal of the generalized Schur form.

            :math:`\mathrm{sort} = \texttt{'N'}`

                Eigenvalues are not ordered.

            :math:`\mathrm{sort} = \texttt{'S'}`

                Eigenvalues are ordered (see :math:`\mathrm{selctg}`).

        **a** : float, array-like, shape :math:`\left(n, n\right)`
            The first of the pair of matrices, :math:`A`.

        **b** : float, array-like, shape :math:`\left(n, n\right)`
            The second of the pair of matrices, :math:`B`.

        **selctg** : None or callable retval = selctg(ar, ai, b, data=None), optional
            Note: if this argument is **None** then a NAG-supplied facility will be used.

            If :math:`\mathrm{sort} = \texttt{'S'}`, :math:`\mathrm{selctg}` is used to select generalized eigenvalues to be moved to the top left of the generalized Schur form.

            **Parameters**
                **ar** : float
                    An eigenvalue :math:`\left(\mathrm{ar}[j-1]+\sqrt{-1}\times \mathrm{ai}[j-1]\right)/\mathrm{b}[j-1]` is selected if :math:`\mathrm{selctg}\left(\mathrm{ar}[j-1], \mathrm{ai}[j-1], \mathrm{b}[j-1]\right) = \mathbf{True}`. If either one of a complex conjugate pair is selected, then both complex generalized eigenvalues are selected.

                    Note that in the ill-conditioned case, a selected complex generalized eigenvalue may no longer satisfy :math:`\mathrm{selctg}\left(\mathrm{ar}[j-1], \mathrm{ai}[j-1], \mathrm{b}[j-1]\right) = \mathbf{True}` after ordering. :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 2 in this case.

                **ai** : float
                    An eigenvalue :math:`\left(\mathrm{ar}[j-1]+\sqrt{-1}\times \mathrm{ai}[j-1]\right)/\mathrm{b}[j-1]` is selected if :math:`\mathrm{selctg}\left(\mathrm{ar}[j-1], \mathrm{ai}[j-1], \mathrm{b}[j-1]\right) = \mathbf{True}`. If either one of a complex conjugate pair is selected, then both complex generalized eigenvalues are selected.

                    Note that in the ill-conditioned case, a selected complex generalized eigenvalue may no longer satisfy :math:`\mathrm{selctg}\left(\mathrm{ar}[j-1], \mathrm{ai}[j-1], \mathrm{b}[j-1]\right) = \mathbf{True}` after ordering. :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 2 in this case.

                **b** : float
                    An eigenvalue :math:`\left(\mathrm{ar}[j-1]+\sqrt{-1}\times \mathrm{ai}[j-1]\right)/\mathrm{b}[j-1]` is selected if :math:`\mathrm{selctg}\left(\mathrm{ar}[j-1], \mathrm{ai}[j-1], \mathrm{b}[j-1]\right) = \mathbf{True}`. If either one of a complex conjugate pair is selected, then both complex generalized eigenvalues are selected.

                    Note that in the ill-conditioned case, a selected complex generalized eigenvalue may no longer satisfy :math:`\mathrm{selctg}\left(\mathrm{ar}[j-1], \mathrm{ai}[j-1], \mathrm{b}[j-1]\right) = \mathbf{True}` after ordering. :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 2 in this case.

                **data** : arbitrary, optional, modifiable in place
                    User-communication data for callback functions.

            **Returns**
                **retval** : bool
                    Must be :math:`\mathbf{True}` if the eigenvalue is to be selected.

        **data** : arbitrary, optional
            User-communication data for callback functions.

    **Returns**
        **a** : float, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{a}` has been overwritten by its generalized Schur form :math:`S`.

        **b** : float, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{b}` has been overwritten by its generalized Schur form :math:`T`.

        **sdim** : int
            If :math:`\mathrm{sort} = \texttt{'N'}`, :math:`\mathrm{sdim} = 0`.

            If :math:`\mathrm{sort} = \texttt{'S'}`, :math:`\mathrm{sdim} = \text{}` number of eigenvalues (after sorting) for which :math:`\mathrm{selctg}` is :math:`\mathbf{True}`. (Complex conjugate pairs for which :math:`\mathrm{selctg}` is :math:`\mathbf{True}` for either eigenvalue count as :math:`2`.)

        **alphar** : float, ndarray, shape :math:`\left(n\right)`
            See the description of :math:`\mathrm{beta}`.

        **alphai** : float, ndarray, shape :math:`\left(n\right)`
            See the description of :math:`\mathrm{beta}`.

        **beta** : float, ndarray, shape :math:`\left(n\right)`
            :math:`\left(\mathrm{alphar}[\textit{j}-1]+\mathrm{alphai}[\textit{j}-1]\times i\right)/\mathrm{beta}[\textit{j}-1]`, for :math:`\textit{j} = 1,2,\ldots,n`, will be the generalized eigenvalues. :math:`\mathrm{alphar}[\textit{j}-1]+\mathrm{alphai}[\textit{j}-1]\times i`, and :math:`\mathrm{beta}[\textit{j}-1]`, for :math:`\textit{j} = 1,2,\ldots,n`, are the diagonals of the complex Schur form :math:`\left(S, T\right)` that would result if the :math:`2\times 2` diagonal blocks of the real Schur form of :math:`\left(A, B\right)` were further reduced to triangular form using :math:`2\times 2` complex unitary transformations.

            If :math:`\mathrm{alphai}[j-1]` is zero, then the :math:`j`\ th eigenvalue is real; if positive, then the :math:`j`\ th and :math:`\left(j+1\right)`\ st eigenvalues are a complex conjugate pair, with :math:`\mathrm{alphai}[j]` negative.

            **Note:** the quotients :math:`\mathrm{alphar}[j-1]/\mathrm{beta}[j-1]` and :math:`\mathrm{alphai}[j-1]/\mathrm{beta}[j-1]` may easily overflow or underflow, and :math:`\mathrm{beta}[j-1]` may even be zero.

            Thus, you should avoid naively computing the ratio :math:`\alpha /\beta`.

            However, :math:`\mathrm{alphar}` and :math:`\mathrm{alphai}` will always be less than and usually comparable with :math:`\left\lVert A\right\rVert_2` in magnitude, and :math:`\mathrm{beta}` will always be less than and usually comparable with :math:`\left\lVert B\right\rVert_2`.

        **vsl** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobvsl} = \texttt{'V'}`, :math:`\mathrm{vsl}` will contain the left Schur vectors, :math:`Q`.

            If :math:`\mathrm{jobvsl} = \texttt{'N'}`, :math:`\mathrm{vsl}` is not referenced.

        **vsr** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobvsr} = \texttt{'V'}`, :math:`\mathrm{vsr}` will contain the right Schur vectors, :math:`Z`.

            If :math:`\mathrm{jobvsr} = \texttt{'N'}`, :math:`\mathrm{vsr}` is not referenced.

    .. _f08xc-py2-py-errors:

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

                Constraint: :math:`\mathrm{jobvsl} = \texttt{'N'}` or :math:`\texttt{'V'}`.

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

                Constraint: :math:`\mathrm{jobvsr} = \texttt{'N'}` or :math:`\texttt{'V'}`.

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

                Constraint: :math:`\mathrm{sort} = \texttt{'N'}` or :math:`\texttt{'S'}`.

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

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

            (`errno` :math:`n+1`)
                The :math:`QZ` iteration failed with an unexpected error, please contact `NAG <https://www.nag.com>`__.

    **Warns**
        **NagAlgorithmicWarning**
            (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq n\right)`)
                The :math:`QZ` iteration failed. No eigenvectors have been calculated but :math:`\mathrm{alphar}[j]`, :math:`\mathrm{alphai}[j]` and :math:`\mathrm{beta}[j]` should be correct from element :math:`\langle\mathit{\boldsymbol{value}}\rangle`.

            (`errno` :math:`n+2`)
                After reordering, roundoff changed values of some complex eigenvalues so that leading eigenvalues in the generalized Schur form no longer satisfy :math:`\mathrm{selctg} = \mathbf{True}`. This could also be caused by underflow due to scaling.

            (`errno` :math:`n+3`)
                The eigenvalues could not be reordered because some eigenvalues were too close to separate (the problem is very ill-conditioned).

    .. _f08xc-py2-py-notes:

    **Notes**
        The generalized Schur factorization for a pair of real matrices :math:`\left(A, B\right)` is given by

        .. math::
            A = QSZ^\mathrm{T}\text{, }\quad B = QTZ^\mathrm{T}\text{,}

        where :math:`Q` and :math:`Z` are orthogonal, :math:`T` is upper triangular and :math:`S` is upper quasi-triangular with :math:`1\times 1` and :math:`2\times 2` diagonal blocks.
        The generalized eigenvalues, :math:`\lambda`, of :math:`\left(A, B\right)` are computed from the diagonals of :math:`S` and :math:`T` and satisfy

        .. math::
            Az = \lambda Bz\text{,}

        where :math:`z` is the corresponding generalized eigenvector. :math:`\lambda` is actually returned as the pair :math:`\left(\alpha, \beta \right)` such that

        .. math::
            \lambda = \alpha /\beta

        since :math:`\beta`, or even both :math:`\alpha` and :math:`\beta` can be zero.
        The columns of :math:`Q` and :math:`Z` are the left and right generalized Schur vectors of :math:`\left(A, B\right)`.

        Optionally, ``dgges3`` can order the generalized eigenvalues on the diagonals of :math:`\left(S, T\right)` so that selected eigenvalues are at the top left.
        The leading columns of :math:`Q` and :math:`Z` then form an orthonormal basis for the corresponding eigenspaces, the deflating subspaces.

        ``dgges3`` computes :math:`T` to have non-negative diagonal elements, and the :math:`2\times 2` blocks of :math:`S` correspond to complex conjugate pairs of generalized eigenvalues.
        The generalized Schur factorization, before reordering, is computed by the :math:`QZ` algorithm.

    .. _f08xc-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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, 2012, `Matrix Computations`, (4th Edition), Johns Hopkins University Press, Baltimore
    """
    raise NotImplementedError

def dhgeqz(job, compq, compz, ilo, ihi, a, b, q, z):
    r"""
    ``dhgeqz`` implements the :math:`QZ` method for finding generalized eigenvalues of the real matrix pair :math:`\left(A, B\right)` of order :math:`n`, which is in the generalized upper Hessenberg form.

    .. _f08xe-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08xef.html

    .. _f08xe-py2-py-parameters:

    **Parameters**
        **job** : str, length 1
            Specifies the operations to be performed on :math:`\left(A, B\right)`.

            :math:`\mathrm{job} = \texttt{'E'}`

                The matrix pair :math:`\left(A, B\right)` on exit might not be in the generalized Schur form.

            :math:`\mathrm{job} = \texttt{'S'}`

                The matrix pair :math:`\left(A, B\right)` on exit will be in the generalized Schur form.

        **compq** : str, length 1
            Specifies the operations to be performed on :math:`Q`:

            :math:`\mathrm{compq} = \texttt{'N'}`

                The array :math:`\mathrm{q}` is unchanged.

            :math:`\mathrm{compq} = \texttt{'V'}`

                The left transformation :math:`Q` is accumulated on the array :math:`\mathrm{q}`.

            :math:`\mathrm{compq} = \texttt{'I'}`

                The array :math:`\mathrm{q}` is initialized to the identity matrix before the left transformation :math:`Q` is accumulated in :math:`\mathrm{q}`.

        **compz** : str, length 1
            Specifies the operations to be performed on :math:`Z`.

            :math:`\mathrm{compz} = \texttt{'N'}`

                The array :math:`\mathrm{z}` is unchanged.

            :math:`\mathrm{compz} = \texttt{'V'}`

                The right transformation :math:`Z` is accumulated on the array :math:`\mathrm{z}`.

            :math:`\mathrm{compz} = \texttt{'I'}`

                The array :math:`\mathrm{z}` is initialized to the identity matrix before the right transformation :math:`Z` is accumulated in :math:`\mathrm{z}`.

        **ilo** : int
            The indices :math:`i_{\mathrm{lo}}` and :math:`i_{\mathrm{hi}}`, respectively which define the upper triangular parts of :math:`A`. The submatrices :math:`A\left({1:i_{\mathrm{lo}}-1}, {1:i_{\mathrm{lo}}-1}\right)` and :math:`A\left({i_{\mathrm{hi}}+1:n}, {i_{\mathrm{hi}}+1:n}\right)` are then upper triangular. These arguments are provided by :meth:`dggbal` if the matrix pair was previously balanced; otherwise, :math:`\mathrm{ilo} = 1` and :math:`\mathrm{ihi} = n`.

        **ihi** : int
            The indices :math:`i_{\mathrm{lo}}` and :math:`i_{\mathrm{hi}}`, respectively which define the upper triangular parts of :math:`A`. The submatrices :math:`A\left({1:i_{\mathrm{lo}}-1}, {1:i_{\mathrm{lo}}-1}\right)` and :math:`A\left({i_{\mathrm{hi}}+1:n}, {i_{\mathrm{hi}}+1:n}\right)` are then upper triangular. These arguments are provided by :meth:`dggbal` if the matrix pair was previously balanced; otherwise, :math:`\mathrm{ilo} = 1` and :math:`\mathrm{ihi} = n`.

        **a** : float, array-like, shape :math:`\left(n, n\right)`
            The :math:`n\times n` upper Hessenberg matrix :math:`A`. The elements below the first subdiagonal must be set to zero.

        **b** : float, array-like, shape :math:`\left(n, n\right)`
            The :math:`n\times n` upper triangular matrix :math:`B`. The elements below the diagonal must be zero.

        **q** : float, array-like, shape :math:`\left(:, :\right)`
            Note: the required extent for this argument in dimension 1 is determined as follows: if :math:`\mathrm{compq}\text{ in } (\texttt{'V'}, \texttt{'I'})`: :math:`n`; if :math:`\mathrm{compq}=\texttt{'N'}`: :math:`1`; otherwise: :math:`0`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{compq}\text{ in } (\texttt{'V'}, \texttt{'I'})`: :math:`n`; if :math:`\mathrm{compq}=\texttt{'N'}`: :math:`1`; otherwise: :math:`0`.

            If :math:`\mathrm{compq} = \texttt{'V'}`, the matrix :math:`Q_0`. The matrix :math:`Q_0` is usually the matrix :math:`Q` returned by :meth:`dgghd3`.

            If :math:`\mathrm{compq} = \texttt{'N'}`, :math:`\mathrm{q}` is not referenced.

        **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`; 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'}`, the matrix :math:`Z_0`. The matrix :math:`Z_0` is usually the matrix :math:`Z` returned by :meth:`dgghd3`.

            If :math:`\mathrm{compz} = \texttt{'N'}`, :math:`\mathrm{z}` is not referenced.

    **Returns**
        **a** : float, ndarray, shape :math:`\left(n, n\right)`
            If :math:`\mathrm{job} = \texttt{'S'}`, the matrix pair :math:`\left(A, B\right)` will be simultaneously reduced to generalized Schur form.

            If :math:`\mathrm{job} = \texttt{'E'}`, the :math:`1\times 1` and :math:`2\times 2` diagonal blocks of the matrix pair :math:`\left(A, B\right)` will give generalized eigenvalues but the remaining elements will be irrelevant.

        **b** : float, ndarray, shape :math:`\left(n, n\right)`
            If :math:`\mathrm{job} = \texttt{'S'}`, the matrix pair :math:`\left(A, B\right)` will be simultaneously reduced to generalized Schur form.

            If :math:`\mathrm{job} = \texttt{'E'}`, the :math:`1\times 1` and :math:`2\times 2` diagonal blocks of the matrix pair :math:`\left(A, B\right)` will give generalized eigenvalues but the remaining elements will be irrelevant.

        **alphar** : float, ndarray, shape :math:`\left(n\right)`
            The real parts of :math:`\alpha_{\textit{j}}`, for :math:`\textit{j} = 1,2,\ldots,n`.

        **alphai** : float, ndarray, shape :math:`\left(n\right)`
            The imaginary parts of :math:`\alpha_{\textit{j}}`, for :math:`\textit{j} = 1,2,\ldots,n`.

        **beta** : float, ndarray, shape :math:`\left(n\right)`
            :math:`\beta_{\textit{j}}`, for :math:`\textit{j} = 1,2,\ldots,n`.

        **q** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{compq} = \texttt{'V'}`, :math:`\mathrm{q}` contains the matrix product :math:`QQ_0`.

            If :math:`\mathrm{compq} = \texttt{'I'}`, :math:`\mathrm{q}` contains the transformation matrix :math:`Q`.

        **z** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{compz} = \texttt{'V'}`, :math:`\mathrm{z}` contains the matrix product :math:`ZZ_0`.

            If :math:`\mathrm{compz} = \texttt{'I'}`, :math:`\mathrm{z}` contains the transformation matrix :math:`Z`.

    .. _f08xe-py2-py-errors:

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

                Constraint: :math:`\mathrm{job} = \texttt{'E'}` or :math:`\texttt{'S'}`.

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

                Constraint: :math:`\mathrm{compq} = \texttt{'N'}`, :math:`\texttt{'V'}` or :math:`\texttt{'I'}`.

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

                Constraint: :math:`\mathrm{compz} = \texttt{'N'}`, :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:`-6`)
                On entry, error in parameter :math:`\mathrm{ihi}`.

                Constraint: :math:`1\leq \mathrm{ilo}\leq \mathrm{ihi}\leq n`.

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

                Constraint: :math:`\mathrm{ilo} = 1` and :math:`\mathrm{ihi} = 0`.

    **Warns**
        **NagAlgorithmicWarning**
            (`errno` :math:`i < n`)
                The :math:`QZ` iteration did not converge and the matrix pair :math:`\left(A, B\right)` is not in the generalized Schur form. The computed :math:`\alpha_i` and :math:`\beta_i` should be correct for :math:`i = \langle\mathit{\boldsymbol{value}}\rangle,\ldots,\langle\mathit{\boldsymbol{value}}\rangle`.

            (`errno` :math:`i > n\text{ and }i\leq{2\times n}`)
                The computation of shifts failed and the matrix pair :math:`\left(A, B\right)` is not in the generalized Schur form. The computed :math:`\alpha_i` and :math:`\beta_i` should be correct for :math:`i = \langle\mathit{\boldsymbol{value}}\rangle,\ldots,\langle\mathit{\boldsymbol{value}}\rangle`.

            (`errno` :math:`i > 2\times n`)
                An unexpected Library error has occurred.

    .. _f08xe-py2-py-notes:

    **Notes**
        ``dhgeqz`` implements a single-double-shift version of the :math:`QZ` method for finding the generalized eigenvalues of the real matrix pair :math:`\left(A, B\right)` which is in the generalized upper Hessenberg form.
        If the matrix pair :math:`\left(A, B\right)` is not in the generalized upper Hessenberg form, then the function :meth:`dgghd3` should be called before invoking ``dhgeqz``.

        This problem is mathematically equivalent to solving the equation

        .. math::
            \mathrm{det}\left(A-\lambda B\right) = 0\text{.}

        Note that, to avoid underflow, overflow and other arithmetic problems, the generalized eigenvalues :math:`\lambda_j` are never computed explicitly by this function but defined as ratios between two computed values, :math:`\alpha_j` and :math:`\beta_j`:

        .. math::
            \lambda_j = \alpha_j/\beta_j\text{.}

        The arguments :math:`\alpha_j`, in general, are finite complex values and :math:`\beta_j` are finite real non-negative values.

        If desired, the matrix pair :math:`\left(A, B\right)` may be reduced to generalized Schur form.
        That is, the transformed matrix :math:`B` is upper triangular and the transformed matrix :math:`A` is block upper triangular, where the diagonal blocks are either :math:`1\times 1` or :math:`2\times 2`.
        The :math:`1\times 1` blocks provide generalized eigenvalues which are real and the :math:`2\times 2` blocks give complex generalized eigenvalues.

        The argument :math:`\mathrm{job}` specifies two options.
        If :math:`\mathrm{job} = \texttt{'S'}` then the matrix pair :math:`\left(A, B\right)` is simultaneously reduced to Schur form by applying one orthogonal transformation (usually called :math:`Q`) on the left and another (usually called :math:`Z`) on the right.
        That is,

        .. math::
            \begin{array}{c}A←Q^\mathrm{T}AZ\\B←Q^\mathrm{T}BZ\end{array}

        The :math:`2\times 2` upper-triangular diagonal blocks of :math:`B` corresponding to :math:`2\times 2` blocks of :math:`\mathrm{a}` will be reduced to non-negative diagonal matrices.
        That is, if :math:`\mathrm{a}[j,j-1]` is nonzero, then :math:`\mathrm{b}[j,j-1] = \mathrm{b}[j-1,j] = 0` and :math:`\mathrm{b}[j-1,j-1]` and :math:`\mathrm{b}[j,j]` will be non-negative.

        If :math:`\mathrm{job} = \texttt{'E'}`, then at each iteration the same transformations are computed but they are only applied to those parts of :math:`A` and :math:`B` which are needed to compute :math:`\alpha` and :math:`\beta`.
        This option could be used if generalized eigenvalues are required but not generalized eigenvectors.

        If :math:`\mathrm{job} = \texttt{'S'}` and :math:`\mathrm{compq} = \texttt{'V'}` or :math:`\texttt{'I'}`, and :math:`\mathrm{compz} = \texttt{'V'}` or :math:`\texttt{'I'}`, then the orthogonal transformations used to reduce the pair :math:`\left(A, B\right)` are accumulated into the input arrays :math:`\mathrm{q}` and :math:`\mathrm{z}`.
        If generalized eigenvectors are required then :math:`\mathrm{job}` must be set to :math:`\mathrm{job} = \texttt{'S'}` and if left (right) generalized eigenvectors are to be computed then :math:`\mathrm{compq}` (:math:`\mathrm{compz}`) must be set to :math:`\mathrm{compq} = \texttt{'V'}` or :math:`\texttt{'I'}` and not :math:`\mathrm{compq} \neq \texttt{'N'}`.

        If :math:`\mathrm{compq} = \texttt{'I'}`, then eigenvectors are accumulated on the identity matrix and on exit the array :math:`\mathrm{q}` contains the left eigenvector matrix :math:`Q`.
        However, if :math:`\mathrm{compq} = \texttt{'V'}` then the transformations are accumulated on the user-supplied matrix :math:`Q_0` in array :math:`\mathrm{q}` on entry and thus on exit :math:`\mathrm{q}` contains the matrix product :math:`QQ_0`.
        A similar convention is used for :math:`\mathrm{compz}`.

    .. _f08xe-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia

        Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore

        Moler, C B and Stewart, G W, 1973, `An algorithm for generalized matrix eigenproblems`, SIAM J. Numer. Anal. (10), 241--256

        Stewart, G W and Sun, J-G, 1990, `Matrix Perturbation Theory`, Academic Press, London
    """
    raise NotImplementedError

def zgges(jobvsl, jobvsr, sort, n, a, b, selctg=None, data=None):
    r"""
    ``zgges`` computes the generalized eigenvalues, the generalized Schur form :math:`\left(S, T\right)` and, optionally, the left and/or right generalized Schur vectors for a pair of :math:`n\times n` complex nonsymmetric matrices :math:`\left(A, B\right)`. ``zgges`` is marked as `deprecated` by LAPACK; the replacement routine is :meth:`zgges3` which makes better use of Level 3 BLAS.

    .. deprecated:: 27.0.0.0
        ``zgges`` is deprecated.
        Please use :meth:`zgges3` instead.
        See also the :ref:`Replacement Calls <replace>` document.

    .. _f08xn-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08xnf.html

    .. _f08xn-py2-py-parameters:

    **Parameters**
        **jobvsl** : str, length 1
            If :math:`\mathrm{jobvsl} = \texttt{'N'}`, do not compute the left Schur vectors.

            If :math:`\mathrm{jobvsl} = \texttt{'V'}`, compute the left Schur vectors.

        **jobvsr** : str, length 1
            If :math:`\mathrm{jobvsr} = \texttt{'N'}`, do not compute the right Schur vectors.

            If :math:`\mathrm{jobvsr} = \texttt{'V'}`, compute the right Schur vectors.

        **sort** : str, length 1
            Specifies whether or not to order the eigenvalues on the diagonal of the generalized Schur form.

            :math:`\mathrm{sort} = \texttt{'N'}`

                Eigenvalues are not ordered.

            :math:`\mathrm{sort} = \texttt{'S'}`

                Eigenvalues are ordered (see :math:`\mathrm{selctg}`).

        **n** : int
            :math:`n`, the order of the matrices :math:`A` and :math:`B`.

        **a** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)`
            The first of the pair of matrices, :math:`A`.

        **b** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)`
            The second of the pair of matrices, :math:`B`.

        **selctg** : None or callable retval = selctg(a, b, data=None), optional
            Note: if this argument is **None** then a NAG-supplied facility will be used.

            If :math:`\mathrm{sort} = \texttt{'S'}`, :math:`\mathrm{selctg}` is used to select generalized eigenvalues to be moved to the top left of the generalized Schur form.

            **Parameters**
                **a** : complex
                    An eigenvalue :math:`\mathrm{a}[j-1]/\mathrm{b}[j-1]` is selected if :math:`\mathrm{selctg}\left(\mathrm{a}[j-1], \mathrm{b}[j-1]\right)` is :math:`\mathbf{True}`.

                    Note that in the ill-conditioned case, a selected generalized eigenvalue may no longer satisfy :math:`\mathrm{selctg}\left(\mathrm{a}[j-1], \mathrm{b}[j-1]\right) = \mathbf{True}` after ordering. :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 2 in this case.

                **b** : complex
                    An eigenvalue :math:`\mathrm{a}[j-1]/\mathrm{b}[j-1]` is selected if :math:`\mathrm{selctg}\left(\mathrm{a}[j-1], \mathrm{b}[j-1]\right)` is :math:`\mathbf{True}`.

                    Note that in the ill-conditioned case, a selected generalized eigenvalue may no longer satisfy :math:`\mathrm{selctg}\left(\mathrm{a}[j-1], \mathrm{b}[j-1]\right) = \mathbf{True}` after ordering. :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 2 in this case.

                **data** : arbitrary, optional, modifiable in place
                    User-communication data for callback functions.

            **Returns**
                **retval** : bool
                    Must be :math:`\mathbf{True}` if the eigenvalue is to be selected.

        **data** : arbitrary, optional
            User-communication data for callback functions.

    **Returns**
        **a** : complex, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)`
            :math:`\mathrm{a}` has been overwritten by its generalized Schur form :math:`S`.

        **b** : complex, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)`
            :math:`\mathrm{b}` has been overwritten by its generalized Schur form :math:`T`.

        **sdim** : int
            If :math:`\mathrm{sort} = \texttt{'N'}`, :math:`\mathrm{sdim} = 0`.

            If :math:`\mathrm{sort} = \texttt{'S'}`, :math:`\mathrm{sdim} = \text{}` number of eigenvalues (after sorting) for which :math:`\mathrm{selctg}` is :math:`\mathbf{True}`.

        **alpha** : complex, ndarray, shape :math:`\left(\mathrm{n}\right)`
            See the description of :math:`\mathrm{beta}`.

        **beta** : complex, ndarray, shape :math:`\left(\mathrm{n}\right)`
            :math:`\mathrm{alpha}[\textit{j}-1]/\mathrm{beta}[\textit{j}-1]`, for :math:`\textit{j} = 1,2,\ldots,\mathrm{n}`, will be the generalized eigenvalues. :math:`\mathrm{alpha}[\textit{j}-1]`, for :math:`\textit{j} = 1,2,\ldots,\mathrm{n}` and :math:`\mathrm{beta}[\textit{j}-1]`, for :math:`\textit{j} = 1,2,\ldots,\mathrm{n}`, are the diagonals of the complex Schur form :math:`\left(A, B\right)` output by ``zgges``. The :math:`\mathrm{beta}[j-1]` will be non-negative real.

            **Note:** the quotients :math:`\mathrm{alpha}[j-1]/\mathrm{beta}[j-1]` may easily overflow or underflow, and :math:`\mathrm{beta}[j-1]` may even be zero.

            Thus, you should avoid naively computing the ratio :math:`\alpha /\beta`.

            However, :math:`\mathrm{alpha}` will always be less than and usually comparable with :math:`\left\lVert A\right\rVert_2` in magnitude, and :math:`\mathrm{beta}` will always be less than and usually comparable with :math:`\left\lVert B\right\rVert_2`.

        **vsl** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobvsl} = \texttt{'V'}`, :math:`\mathrm{vsl}` will contain the left Schur vectors, :math:`Q`.

            If :math:`\mathrm{jobvsl} = \texttt{'N'}`, :math:`\mathrm{vsl}` is not referenced.

        **vsr** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobvsr} = \texttt{'V'}`, :math:`\mathrm{vsr}` will contain the right Schur vectors, :math:`Z`.

            If :math:`\mathrm{jobvsr} = \texttt{'N'}`, :math:`\mathrm{vsr}` is not referenced.

    .. _f08xn-py2-py-errors:

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

                Constraint: :math:`\mathrm{jobvsl} = \texttt{'N'}` or :math:`\texttt{'V'}`.

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

                Constraint: :math:`\mathrm{jobvsr} = \texttt{'N'}` or :math:`\texttt{'V'}`.

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

                Constraint: :math:`\mathrm{sort} = \texttt{'N'}` or :math:`\texttt{'S'}`.

            (`errno` :math:`-5`)
                On entry, error in parameter :math:`\mathrm{n}`.

                Constraint: :math:`\mathrm{n}\geq 0`.

            (`errno` :math:`\mathrm{n}+1`)
                The :math:`QZ` iteration failed with an unexpected error, please contact `NAG <https://www.nag.com>`__.

    **Warns**
        **NagAlgorithmicWarning**
            (`errno` :math:`\mathrm{n}+2`)
                After reordering, roundoff changed values of some complex eigenvalues so that leading eigenvalues in the generalized Schur form no longer satisfy :math:`\mathrm{selctg} = \mathbf{True}`. This could also be caused by underflow due to scaling.

            (`errno` :math:`\mathrm{n}+3`)
                The eigenvalues could not be reordered because some eigenvalues were too close to separate (the problem is very ill-conditioned).

            (`errno` :math:`i < \mathrm{n}`)
                The :math:`QZ` iteration did not converge and the matrix pair :math:`\left(A, B\right)` is not in the generalized Schur form. The computed :math:`\alpha_i` and :math:`\beta_i` should be correct for :math:`i = \langle\mathit{\boldsymbol{value}}\rangle,\ldots,\langle\mathit{\boldsymbol{value}}\rangle`.

    .. _f08xn-py2-py-notes:

    **Notes**
        The generalized Schur factorization for a pair of complex matrices :math:`\left(A, B\right)` is given by

        .. math::
            A = QSZ^\mathrm{H}\text{, }\quad B = QTZ^\mathrm{H}\text{,}

        where :math:`Q` and :math:`Z` are unitary, :math:`T` and :math:`S` are upper triangular.
        The generalized eigenvalues, :math:`\lambda`, of :math:`\left(A, B\right)` are computed from the diagonals of :math:`T` and :math:`S` and satisfy

        .. math::
            Az = \lambda Bz\text{,}

        where :math:`z` is the corresponding generalized eigenvector. :math:`\lambda` is actually returned as the pair :math:`\left(\alpha, \beta \right)` such that

        .. math::
            \lambda = \alpha /\beta

        since :math:`\beta`, or even both :math:`\alpha` and :math:`\beta` can be zero.
        The columns of :math:`Q` and :math:`Z` are the left and right generalized Schur vectors of :math:`\left(A, B\right)`.

        Optionally, ``zgges`` can order the generalized eigenvalues on the diagonals of :math:`\left(S, T\right)` so that selected eigenvalues are at the top left.
        The leading columns of :math:`Q` and :math:`Z` then form an orthonormal basis for the corresponding eigenspaces, the deflating subspaces.

        ``zgges`` computes :math:`T` to have real non-negative diagonal entries.
        The generalized Schur factorization, before reordering, is computed by the :math:`QZ` algorithm.

    .. _f08xn-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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 zggesx(jobvsl, jobvsr, sort, sense, a, b, selctg=None, data=None):
    r"""
    ``zggesx`` computes the generalized eigenvalues, the generalized Schur form :math:`\left(S, T\right)` and, optionally, the left and/or right generalized Schur vectors for a pair of :math:`n\times n` complex nonsymmetric matrices :math:`\left(A, B\right)`.

    Estimates of condition numbers for selected generalized eigenvalue clusters and Schur vectors are also computed.

    .. _f08xp-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08xpf.html

    .. _f08xp-py2-py-parameters:

    **Parameters**
        **jobvsl** : str, length 1
            If :math:`\mathrm{jobvsl} = \texttt{'N'}`, do not compute the left Schur vectors.

            If :math:`\mathrm{jobvsl} = \texttt{'V'}`, compute the left Schur vectors.

        **jobvsr** : str, length 1
            If :math:`\mathrm{jobvsr} = \texttt{'N'}`, do not compute the right Schur vectors.

            If :math:`\mathrm{jobvsr} = \texttt{'V'}`, compute the right Schur vectors.

        **sort** : str, length 1
            Specifies whether or not to order the eigenvalues on the diagonal of the generalized Schur form.

            :math:`\mathrm{sort} = \texttt{'N'}`

                Eigenvalues are not ordered.

            :math:`\mathrm{sort} = \texttt{'S'}`

                Eigenvalues are ordered (see :math:`\mathrm{selctg}`).

        **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 average of selected eigenvalues only.

            :math:`\mathrm{sense} = \texttt{'V'}`

                Computed for selected deflating subspaces only.

            :math:`\mathrm{sense} = \texttt{'B'}`

                Computed for both.

            If :math:`\mathrm{sense} = \texttt{'E'}`, :math:`\texttt{'V'}` or :math:`\texttt{'B'}`, :math:`\mathrm{sort} = \texttt{'S'}`.

        **a** : complex, array-like, shape :math:`\left(n, n\right)`
            The first of the pair of matrices, :math:`A`.

        **b** : complex, array-like, shape :math:`\left(n, n\right)`
            The second of the pair of matrices, :math:`B`.

        **selctg** : None or callable retval = selctg(a, b, data=None), optional
            Note: if this argument is **None** then a NAG-supplied facility will be used.

            If :math:`\mathrm{sort} = \texttt{'S'}`, :math:`\mathrm{selctg}` is used to select generalized eigenvalues to be moved to the top left of the generalized Schur form.

            **Parameters**
                **a** : complex
                    An eigenvalue :math:`\mathrm{a}[j-1]/\mathrm{b}[j-1]` is selected if :math:`\mathrm{selctg}\left(\mathrm{a}[j-1], \mathrm{b}[j-1]\right)` is :math:`\mathbf{True}`.

                    Note that in the ill-conditioned case, a selected generalized eigenvalue may no longer satisfy :math:`\mathrm{selctg}\left(\mathrm{a}[j-1], \mathrm{b}[j-1]\right) = \mathbf{True}` after ordering. :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 2 in this case.

                **b** : complex
                    An eigenvalue :math:`\mathrm{a}[j-1]/\mathrm{b}[j-1]` is selected if :math:`\mathrm{selctg}\left(\mathrm{a}[j-1], \mathrm{b}[j-1]\right)` is :math:`\mathbf{True}`.

                    Note that in the ill-conditioned case, a selected generalized eigenvalue may no longer satisfy :math:`\mathrm{selctg}\left(\mathrm{a}[j-1], \mathrm{b}[j-1]\right) = \mathbf{True}` after ordering. :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 2 in this case.

                **data** : arbitrary, optional, modifiable in place
                    User-communication data for callback functions.

            **Returns**
                **retval** : bool
                    Must be :math:`\mathbf{True}` if the eigenvalue is to be selected.

        **data** : arbitrary, optional
            User-communication data for callback functions.

    **Returns**
        **a** : complex, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{a}` has been overwritten by its generalized Schur form :math:`S`.

        **b** : complex, ndarray, shape :math:`\left(n, n\right)`
            :math:`\mathrm{b}` has been overwritten by its generalized Schur form :math:`T`.

        **sdim** : int
            If :math:`\mathrm{sort} = \texttt{'N'}`, :math:`\mathrm{sdim} = 0`.

            If :math:`\mathrm{sort} = \texttt{'S'}`, :math:`\mathrm{sdim} = \text{}` number of eigenvalues (after sorting) for which :math:`\mathrm{selctg}` is :math:`\mathbf{True}`.

        **alpha** : complex, ndarray, shape :math:`\left(n\right)`
            See the description of :math:`\mathrm{beta}`.

        **beta** : complex, ndarray, shape :math:`\left(n\right)`
            :math:`\mathrm{alpha}[\textit{j}-1]/\mathrm{beta}[\textit{j}-1]`, for :math:`\textit{j} = 1,2,\ldots,n`, will be the generalized eigenvalues. :math:`\mathrm{alpha}[j-1]` and :math:`\mathrm{beta}[j-1],j = 1,2,\ldots,n` are the diagonals of the complex Schur form :math:`\left(S, T\right)`. :math:`\mathrm{beta}[j-1]` will be non-negative real.

            **Note:** the quotients :math:`\mathrm{alpha}[j-1]/\mathrm{beta}[j-1]` may easily overflow or underflow, and :math:`\mathrm{beta}[j-1]` may even be zero.

            Thus, you should avoid naively computing the ratio :math:`\alpha /\beta`.

            However, :math:`\mathrm{alpha}` will always be less than and usually comparable with :math:`\left\lVert \mathrm{a}\right\rVert` in magnitude, and :math:`\mathrm{beta}` will always be less than and usually comparable with :math:`\left\lVert \mathrm{b}\right\rVert`.

        **vsl** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobvsl} = \texttt{'V'}`, :math:`\mathrm{vsl}` will contain the left Schur vectors, :math:`Q`.

            If :math:`\mathrm{jobvsl} = \texttt{'N'}`, :math:`\mathrm{vsl}` is not referenced.

        **vsr** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobvsr} = \texttt{'V'}`, :math:`\mathrm{vsr}` will contain the right Schur vectors, :math:`Z`.

            If :math:`\mathrm{jobvsr} = \texttt{'N'}`, :math:`\mathrm{vsr}` is not referenced.

        **rconde** : float, ndarray, shape :math:`\left(2\right)`
            If :math:`\mathrm{sense} = \texttt{'E'}` or :math:`\texttt{'B'}`, :math:`\mathrm{rconde}[0]` and :math:`\mathrm{rconde}[1]` contain the reciprocal condition numbers for the average of the selected eigenvalues.

            If :math:`\mathrm{sense} = \texttt{'N'}` or :math:`\texttt{'V'}`, :math:`\mathrm{rconde}` is not referenced.

        **rcondv** : float, ndarray, shape :math:`\left(2\right)`
            If :math:`\mathrm{sense} = \texttt{'V'}` or :math:`\texttt{'B'}`, :math:`\mathrm{rcondv}[0]` and :math:`\mathrm{rcondv}[1]` contain the reciprocal condition numbers for the selected deflating subspaces.

            if :math:`\mathrm{sense} = \texttt{'N'}` or :math:`\texttt{'E'}`, :math:`\mathrm{rcondv}` is not referenced.

    .. _f08xp-py2-py-errors:

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

                Constraint: :math:`\mathrm{jobvsl} = \texttt{'N'}` or :math:`\texttt{'V'}`.

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

                Constraint: :math:`\mathrm{jobvsr} = \texttt{'N'}` or :math:`\texttt{'V'}`.

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

                Constraint: :math:`\mathrm{sort} = \texttt{'N'}` or :math:`\texttt{'S'}`.

            (`errno` :math:`-5`)
                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:`-6`)
                On entry, error in parameter :math:`\textit{n}`.

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

            (`errno` :math:`n+1`)
                The :math:`QZ` iteration failed with an unexpected error, please contact `NAG <https://www.nag.com>`__.

    **Warns**
        **NagAlgorithmicWarning**
            (`errno` :math:`\left(i > 0\right)\text{ and }\left(i \leq n\right)`)
                The :math:`QZ` iteration failed. :math:`\left(A, B\right)` are not in Schur form, but :math:`\mathrm{alpha}[j]` and :math:`\mathrm{beta}[j]` should be correct from element :math:`\langle\mathit{\boldsymbol{value}}\rangle`.

            (`errno` :math:`n+2`)
                After reordering, roundoff changed values of some complex eigenvalues so that leading eigenvalues in the generalized Schur form no longer satisfy :math:`\mathrm{selctg} = \mathbf{True}`. This could also be caused by underflow due to scaling.

            (`errno` :math:`n+3`)
                The eigenvalues could not be reordered because some eigenvalues were too close to separate (the problem is very ill-conditioned).

    .. _f08xp-py2-py-notes:

    **Notes**
        The generalized Schur factorization for a pair of complex matrices :math:`\left(A, B\right)` is given by

        .. math::
            A = QSZ^\mathrm{H}\text{, }\quad B = QTZ^\mathrm{H}\text{,}

        where :math:`Q` and :math:`Z` are unitary, :math:`T` and :math:`S` are upper triangular.
        The generalized eigenvalues, :math:`\lambda`, of :math:`\left(A, B\right)` are computed from the diagonals of :math:`T` and :math:`S` and satisfy

        .. math::
            Az = \lambda Bz\text{,}

        where :math:`z` is the corresponding generalized eigenvector. :math:`\lambda` is actually returned as the pair :math:`\left(\alpha, \beta \right)` such that

        .. math::
            \lambda = \alpha /\beta

        since :math:`\beta`, or even both :math:`\alpha` and :math:`\beta` can be zero.
        The columns of :math:`Q` and :math:`Z` are the left and right generalized Schur vectors of :math:`\left(A, B\right)`.

        Optionally, ``zggesx`` can order the generalized eigenvalues on the diagonals of :math:`\left(S, T\right)` so that selected eigenvalues are at the top left.
        The leading columns of :math:`Q` and :math:`Z` then form an orthonormal basis for the corresponding eigenspaces, the deflating subspaces.

        ``zggesx`` computes :math:`T` to have real non-negative diagonal entries.
        The generalized Schur factorization, before reordering, is computed by the :math:`QZ` algorithm.

        The reciprocals of the condition estimates, the reciprocal values of the left and right projection norms, are returned in :math:`\mathrm{rconde}[0]` and :math:`\mathrm{rconde}[1]` respectively, for the selected generalized eigenvalues, together with reciprocal condition estimates for the corresponding left and right deflating subspaces, in :math:`\mathrm{rcondv}[0]` and :math:`\mathrm{rcondv}[1]`.
        See Section 4.11 of Anderson `et al.` (1999) for further information.

    .. _f08xp-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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 zgges3(jobvsl, jobvsr, sort, n, a, b, selctg=None, data=None):
    r"""
    ``zgges3`` computes the generalized eigenvalues, the generalized Schur form :math:`\left(S, T\right)` and, optionally, the left and/or right generalized Schur vectors for a pair of :math:`n\times n` complex nonsymmetric matrices :math:`\left(A, B\right)`.

    .. _f08xq-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08xqf.html

    .. _f08xq-py2-py-parameters:

    **Parameters**
        **jobvsl** : str, length 1
            If :math:`\mathrm{jobvsl} = \texttt{'N'}`, do not compute the left Schur vectors.

            If :math:`\mathrm{jobvsl} = \texttt{'V'}`, compute the left Schur vectors.

        **jobvsr** : str, length 1
            If :math:`\mathrm{jobvsr} = \texttt{'N'}`, do not compute the right Schur vectors.

            If :math:`\mathrm{jobvsr} = \texttt{'V'}`, compute the right Schur vectors.

        **sort** : str, length 1
            Specifies whether or not to order the eigenvalues on the diagonal of the generalized Schur form.

            :math:`\mathrm{sort} = \texttt{'N'}`

                Eigenvalues are not ordered.

            :math:`\mathrm{sort} = \texttt{'S'}`

                Eigenvalues are ordered (see :math:`\mathrm{selctg}`).

        **n** : int
            :math:`n`, the order of the matrices :math:`A` and :math:`B`.

        **a** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)`
            The first of the pair of matrices, :math:`A`.

        **b** : complex, array-like, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)`
            The second of the pair of matrices, :math:`B`.

        **selctg** : None or callable retval = selctg(a, b, data=None), optional
            Note: if this argument is **None** then a NAG-supplied facility will be used.

            If :math:`\mathrm{sort} = \texttt{'S'}`, :math:`\mathrm{selctg}` is used to select generalized eigenvalues to be moved to the top left of the generalized Schur form.

            **Parameters**
                **a** : complex
                    An eigenvalue :math:`\mathrm{a}[j-1]/\mathrm{b}[j-1]` is selected if :math:`\mathrm{selctg}\left(\mathrm{a}[j-1], \mathrm{b}[j-1]\right)` is :math:`\mathbf{True}`.

                    Note that in the ill-conditioned case, a selected generalized eigenvalue may no longer satisfy :math:`\mathrm{selctg}\left(\mathrm{a}[j-1], \mathrm{b}[j-1]\right) = \mathbf{True}` after ordering. :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 2 in this case.

                **b** : complex
                    An eigenvalue :math:`\mathrm{a}[j-1]/\mathrm{b}[j-1]` is selected if :math:`\mathrm{selctg}\left(\mathrm{a}[j-1], \mathrm{b}[j-1]\right)` is :math:`\mathbf{True}`.

                    Note that in the ill-conditioned case, a selected generalized eigenvalue may no longer satisfy :math:`\mathrm{selctg}\left(\mathrm{a}[j-1], \mathrm{b}[j-1]\right) = \mathbf{True}` after ordering. :math:`\mathrm{errno}` = :math:`\mathrm{n}` + 2 in this case.

                **data** : arbitrary, optional, modifiable in place
                    User-communication data for callback functions.

            **Returns**
                **retval** : bool
                    Must be :math:`\mathbf{True}` if the eigenvalue is to be selected.

        **data** : arbitrary, optional
            User-communication data for callback functions.

    **Returns**
        **a** : complex, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)`
            :math:`\mathrm{a}` has been overwritten by its generalized Schur form :math:`S`.

        **b** : complex, ndarray, shape :math:`\left(\mathrm{n}, \mathrm{n}\right)`
            :math:`\mathrm{b}` has been overwritten by its generalized Schur form :math:`T`.

        **sdim** : int
            If :math:`\mathrm{sort} = \texttt{'N'}`, :math:`\mathrm{sdim} = 0`.

            If :math:`\mathrm{sort} = \texttt{'S'}`, :math:`\mathrm{sdim} = \text{}` number of eigenvalues (after sorting) for which :math:`\mathrm{selctg}` is :math:`\mathbf{True}`.

        **alpha** : complex, ndarray, shape :math:`\left(\mathrm{n}\right)`
            See the description of :math:`\mathrm{beta}`.

        **beta** : complex, ndarray, shape :math:`\left(\mathrm{n}\right)`
            :math:`\mathrm{alpha}[\textit{j}-1]/\mathrm{beta}[\textit{j}-1]`, for :math:`\textit{j} = 1,2,\ldots,\mathrm{n}`, will be the generalized eigenvalues. :math:`\mathrm{alpha}[\textit{j}-1]`, for :math:`\textit{j} = 1,2,\ldots,\mathrm{n}` and :math:`\mathrm{beta}[\textit{j}-1]`, for :math:`\textit{j} = 1,2,\ldots,\mathrm{n}`, are the diagonals of the complex Schur form :math:`\left(A, B\right)` output by ``zgges3``. The :math:`\mathrm{beta}[j-1]` will be non-negative real.

            **Note:** the quotients :math:`\mathrm{alpha}[j-1]/\mathrm{beta}[j-1]` may easily overflow or underflow, and :math:`\mathrm{beta}[j-1]` may even be zero.

            Thus, you should avoid naively computing the ratio :math:`\alpha /\beta`.

            However, :math:`\mathrm{alpha}` will always be less than and usually comparable with :math:`\left\lVert A\right\rVert_2` in magnitude, and :math:`\mathrm{beta}` will always be less than and usually comparable with :math:`\left\lVert B\right\rVert_2`.

        **vsl** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobvsl} = \texttt{'V'}`, :math:`\mathrm{vsl}` will contain the left Schur vectors, :math:`Q`.

            If :math:`\mathrm{jobvsl} = \texttt{'N'}`, :math:`\mathrm{vsl}` is not referenced.

        **vsr** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobvsr} = \texttt{'V'}`, :math:`\mathrm{vsr}` will contain the right Schur vectors, :math:`Z`.

            If :math:`\mathrm{jobvsr} = \texttt{'N'}`, :math:`\mathrm{vsr}` is not referenced.

    .. _f08xq-py2-py-errors:

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

                Constraint: :math:`\mathrm{jobvsl} = \texttt{'N'}` or :math:`\texttt{'V'}`.

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

                Constraint: :math:`\mathrm{jobvsr} = \texttt{'N'}` or :math:`\texttt{'V'}`.

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

                Constraint: :math:`\mathrm{sort} = \texttt{'N'}` or :math:`\texttt{'S'}`.

            (`errno` :math:`-5`)
                On entry, error in parameter :math:`\mathrm{n}`.

                Constraint: :math:`\mathrm{n}\geq 0`.

            (`errno` :math:`\mathrm{n}+1`)
                The :math:`QZ` iteration failed with an unexpected error, please contact `NAG <https://www.nag.com>`__.

    **Warns**
        **NagAlgorithmicWarning**
            (`errno` :math:`\mathrm{n}+2`)
                After reordering, roundoff changed values of some complex eigenvalues so that leading eigenvalues in the generalized Schur form no longer satisfy :math:`\mathrm{selctg} = \mathbf{True}`. This could also be caused by underflow due to scaling.

            (`errno` :math:`\mathrm{n}+3`)
                The eigenvalues could not be reordered because some eigenvalues were too close to separate (the problem is very ill-conditioned).

            (`errno` :math:`i < \mathrm{n}`)
                The :math:`QZ` iteration did not converge and the matrix pair :math:`\left(A, B\right)` is not in the generalized Schur form. The computed :math:`\alpha_i` and :math:`\beta_i` should be correct for :math:`i = \langle\mathit{\boldsymbol{value}}\rangle,\ldots,\langle\mathit{\boldsymbol{value}}\rangle`.

    .. _f08xq-py2-py-notes:

    **Notes**
        The generalized Schur factorization for a pair of complex matrices :math:`\left(A, B\right)` is given by

        .. math::
            A = QSZ^\mathrm{H}\text{, }\quad B = QTZ^\mathrm{H}\text{,}

        where :math:`Q` and :math:`Z` are unitary, :math:`T` and :math:`S` are upper triangular.
        The generalized eigenvalues, :math:`\lambda`, of :math:`\left(A, B\right)` are computed from the diagonals of :math:`T` and :math:`S` and satisfy

        .. math::
            Az = \lambda Bz\text{,}

        where :math:`z` is the corresponding generalized eigenvector. :math:`\lambda` is actually returned as the pair :math:`\left(\alpha, \beta \right)` such that

        .. math::
            \lambda = \alpha /\beta

        since :math:`\beta`, or even both :math:`\alpha` and :math:`\beta` can be zero.
        The columns of :math:`Q` and :math:`Z` are the left and right generalized Schur vectors of :math:`\left(A, B\right)`.

        Optionally, ``zgges3`` can order the generalized eigenvalues on the diagonals of :math:`\left(S, T\right)` so that selected eigenvalues are at the top left.
        The leading columns of :math:`Q` and :math:`Z` then form an orthonormal basis for the corresponding eigenspaces, the deflating subspaces.

        ``zgges3`` computes :math:`T` to have real non-negative diagonal entries.
        The generalized Schur factorization, before reordering, is computed by the :math:`QZ` algorithm.

    .. _f08xq-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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, 2012, `Matrix Computations`, (4th Edition), Johns Hopkins University Press, Baltimore
    """
    raise NotImplementedError

def zhgeqz(job, compq, compz, ilo, ihi, a, b, q, z):
    r"""
    ``zhgeqz`` implements the :math:`QZ` method for finding generalized eigenvalues of the complex matrix pair :math:`\left(A, B\right)` of order :math:`n`, which is in the generalized upper Hessenberg form.

    .. _f08xs-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08xsf.html

    .. _f08xs-py2-py-parameters:

    **Parameters**
        **job** : str, length 1
            Specifies the operations to be performed on :math:`\left(A, B\right)`.

            :math:`\mathrm{job} = \texttt{'E'}`

                The matrix pair :math:`\left(A, B\right)` on exit might not be in the generalized Schur form.

            :math:`\mathrm{job} = \texttt{'S'}`

                The matrix pair :math:`\left(A, B\right)` on exit will be in the generalized Schur form.

        **compq** : str, length 1
            Specifies the operations to be performed on :math:`Q`:

            :math:`\mathrm{compq} = \texttt{'N'}`

                The array :math:`\mathrm{q}` is unchanged.

            :math:`\mathrm{compq} = \texttt{'V'}`

                The left transformation :math:`Q` is accumulated on the array :math:`\mathrm{q}`.

            :math:`\mathrm{compq} = \texttt{'I'}`

                The array :math:`\mathrm{q}` is initialized to the identity matrix before the left transformation :math:`Q` is accumulated in :math:`\mathrm{q}`.

        **compz** : str, length 1
            Specifies the operations to be performed on :math:`Z`.

            :math:`\mathrm{compz} = \texttt{'N'}`

                The array :math:`\mathrm{z}` is unchanged.

            :math:`\mathrm{compz} = \texttt{'V'}`

                The right transformation :math:`Z` is accumulated on the array :math:`\mathrm{z}`.

            :math:`\mathrm{compz} = \texttt{'I'}`

                The array :math:`\mathrm{z}` is initialized to the identity matrix before the right transformation :math:`Z` is accumulated in :math:`\mathrm{z}`.

        **ilo** : int
            The indices :math:`i_{\mathrm{lo}}` and :math:`i_{\mathrm{hi}}`, respectively which define the upper triangular parts of :math:`A`. The submatrices :math:`A\left({1:i_{\mathrm{lo}}-1}, {1:i_{\mathrm{lo}}-1}\right)` and :math:`A\left({i_{\mathrm{hi}}+1:n}, {i_{\mathrm{hi}}+1:n}\right)` are then upper triangular. These arguments are provided by :meth:`zggbal` if the matrix pair was previously balanced; otherwise, :math:`\mathrm{ilo} = 1` and :math:`\mathrm{ihi} = n`.

        **ihi** : int
            The indices :math:`i_{\mathrm{lo}}` and :math:`i_{\mathrm{hi}}`, respectively which define the upper triangular parts of :math:`A`. The submatrices :math:`A\left({1:i_{\mathrm{lo}}-1}, {1:i_{\mathrm{lo}}-1}\right)` and :math:`A\left({i_{\mathrm{hi}}+1:n}, {i_{\mathrm{hi}}+1:n}\right)` are then upper triangular. These arguments are provided by :meth:`zggbal` if the matrix pair was previously balanced; otherwise, :math:`\mathrm{ilo} = 1` and :math:`\mathrm{ihi} = n`.

        **a** : complex, array-like, shape :math:`\left(n, n\right)`
            The :math:`n\times n` upper Hessenberg matrix :math:`A`. The elements below the first subdiagonal must be set to zero.

        **b** : complex, array-like, shape :math:`\left(n, n\right)`
            The :math:`n\times n` upper triangular matrix :math:`B`. The elements below the diagonal must be zero.

        **q** : complex, array-like, shape :math:`\left(:, :\right)`
            Note: the required extent for this argument in dimension 1 is determined as follows: if :math:`\mathrm{compq}\text{ in } (\texttt{'V'}, \texttt{'I'})`: :math:`n`; if :math:`\mathrm{compq}=\texttt{'N'}`: :math:`1`; otherwise: :math:`0`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{compq}\text{ in } (\texttt{'V'}, \texttt{'I'})`: :math:`n`; if :math:`\mathrm{compq}=\texttt{'N'}`: :math:`1`; otherwise: :math:`0`.

            If :math:`\mathrm{compq} = \texttt{'V'}`, the matrix :math:`Q_0`. The matrix :math:`Q_0` is usually the matrix :math:`Q` returned by :meth:`zgghd3`.

            If :math:`\mathrm{compq} = \texttt{'N'}`, :math:`\mathrm{q}` is not referenced.

        **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`; 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'}`, the matrix :math:`Z_0`. The matrix :math:`Z_0` is usually the matrix :math:`Z` returned by :meth:`zgghd3`.

            If :math:`\mathrm{compz} = \texttt{'N'}`, :math:`\mathrm{z}` is not referenced.

    **Returns**
        **a** : complex, ndarray, shape :math:`\left(n, n\right)`
            If :math:`\mathrm{job} = \texttt{'S'}`, the matrix pair :math:`\left(A, B\right)` will be simultaneously reduced to generalized Schur form.

            If :math:`\mathrm{job} = \texttt{'E'}`, the :math:`1\times 1` and :math:`2\times 2` diagonal blocks of the matrix pair :math:`\left(A, B\right)` will give generalized eigenvalues but the remaining elements will be irrelevant.

        **b** : complex, ndarray, shape :math:`\left(n, n\right)`
            If :math:`\mathrm{job} = \texttt{'S'}`, the matrix pair :math:`\left(A, B\right)` will be simultaneously reduced to generalized Schur form.

            If :math:`\mathrm{job} = \texttt{'E'}`, the :math:`1\times 1` and :math:`2\times 2` diagonal blocks of the matrix pair :math:`\left(A, B\right)` will give generalized eigenvalues but the remaining elements will be irrelevant.

        **alpha** : complex, ndarray, shape :math:`\left(n\right)`
            :math:`\alpha_{\textit{j}}`, for :math:`\textit{j} = 1,2,\ldots,n`.

        **beta** : complex, ndarray, shape :math:`\left(n\right)`
            :math:`\beta_{\textit{j}}`, for :math:`\textit{j} = 1,2,\ldots,n`.

        **q** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{compq} = \texttt{'V'}`, :math:`\mathrm{q}` contains the matrix product :math:`QQ_0`.

            If :math:`\mathrm{compq} = \texttt{'I'}`, :math:`\mathrm{q}` contains the transformation matrix :math:`Q`.

        **z** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{compz} = \texttt{'V'}`, :math:`\mathrm{z}` contains the matrix product :math:`ZZ_0`.

            If :math:`\mathrm{compz} = \texttt{'I'}`, :math:`\mathrm{z}` contains the transformation matrix :math:`Z`.

    .. _f08xs-py2-py-errors:

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

                Constraint: :math:`\mathrm{job} = \texttt{'E'}` or :math:`\texttt{'S'}`.

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

                Constraint: :math:`\mathrm{compq} = \texttt{'N'}`, :math:`\texttt{'V'}` or :math:`\texttt{'I'}`.

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

                Constraint: :math:`\mathrm{compz} = \texttt{'N'}`, :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:`-6`)
                On entry, error in parameter :math:`\mathrm{ihi}`.

                Constraint: :math:`1\leq \mathrm{ilo}\leq \mathrm{ihi}\leq n`.

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

                Constraint: :math:`\mathrm{ilo} = 1` and :math:`\mathrm{ihi} = 0`.

            (`errno` :math:`i < n`)
                The :math:`QZ` iteration did not converge and the matrix pair :math:`\left(A, B\right)` is not in the generalized Schur form. The computed :math:`\alpha_i` and :math:`\beta_i` should be correct for :math:`i = \langle\mathit{\boldsymbol{value}}\rangle,\ldots,\langle\mathit{\boldsymbol{value}}\rangle`.

            (`errno` :math:`i > n\text{ and }i\leq{2\times n}`)
                The computation of shifts failed and the matrix pair :math:`\left(A, B\right)` is not in the generalized Schur form. The computed :math:`\alpha_i` and :math:`\beta_i` should be correct for :math:`i = \langle\mathit{\boldsymbol{value}}\rangle,\ldots,\langle\mathit{\boldsymbol{value}}\rangle`.

            (`errno` :math:`i > 2\times n`)
                An unexpected Library error has occurred.

    .. _f08xs-py2-py-notes:

    **Notes**
        ``zhgeqz`` implements a single-shift version of the :math:`QZ` method for finding the generalized eigenvalues of the complex matrix pair :math:`\left(A, B\right)` which is in the generalized upper Hessenberg form.
        If the matrix pair :math:`\left(A, B\right)` is not in the generalized upper Hessenberg form, then the function :meth:`zgghd3` should be called before invoking ``zhgeqz``.

        This problem is mathematically equivalent to solving the matrix equation

        .. math::
            \mathrm{det}\left(A-\lambda B\right) = 0\text{.}

        Note that, to avoid underflow, overflow and other arithmetic problems, the generalized eigenvalues :math:`\lambda_j` are never computed explicitly by this function but defined as ratios between two computed values, :math:`\alpha_j` and :math:`\beta_j`:

        .. math::
            \lambda_j = \alpha_j/\beta_j\text{.}

        The arguments :math:`\alpha_j`, in general, are finite complex values and :math:`\beta_j` are finite real non-negative values.

        If desired, the matrix pair :math:`\left(A, B\right)` may be reduced to generalized Schur form.
        That is, the transformed matrices :math:`A` and :math:`B` are upper triangular and the diagonal values of :math:`A` and :math:`B` provide :math:`\alpha` and :math:`\beta`.

        The argument :math:`\mathrm{job}` specifies two options.
        If :math:`\mathrm{job} = \texttt{'S'}` then the matrix pair :math:`\left(A, B\right)` is simultaneously reduced to Schur form by applying one unitary transformation (usually called :math:`Q`) on the left and another (usually called :math:`Z`) on the right.
        That is,

        .. math::
            \begin{array}{c}A←Q^\mathrm{H}AZ\\B←Q^\mathrm{H}BZ\end{array}

        If :math:`\mathrm{job} = \texttt{'E'}`, then at each iteration the same transformations are computed but they are only applied to those parts of :math:`A` and :math:`B` which are needed to compute :math:`\alpha` and :math:`\beta`.
        This option could be used if generalized eigenvalues are required but not generalized eigenvectors.

        If :math:`\mathrm{job} = \texttt{'S'}` and :math:`\mathrm{compq} = \texttt{'V'}` or :math:`\texttt{'I'}`, and :math:`\mathrm{compz} = \texttt{'V'}` or :math:`\texttt{'I'}`, then the unitary transformations used to reduce the pair :math:`\left(A, B\right)` are accumulated into the input arrays :math:`\mathrm{q}` and :math:`\mathrm{z}`.
        If generalized eigenvectors are required then :math:`\mathrm{job}` must be set to :math:`\mathrm{job} = \texttt{'S'}` and if left (right) generalized eigenvectors are to be computed then :math:`\mathrm{compq}` (:math:`\mathrm{compz}`) must be set to :math:`\mathrm{compq} = \texttt{'V'}` or :math:`\texttt{'I'}` rather than :math:`\mathrm{compq} = \texttt{'N'}`.

        If :math:`\mathrm{compq} = \texttt{'I'}`, then eigenvectors are accumulated on the identity matrix and on exit the array :math:`\mathrm{q}` contains the left eigenvector matrix :math:`Q`.
        However, if :math:`\mathrm{compq} = \texttt{'V'}` then the transformations are accumulated in the user-supplied matrix :math:`Q_0` in array :math:`\mathrm{q}` on entry and thus on exit :math:`\mathrm{q}` contains the matrix product :math:`QQ_0`.
        A similar convention is used for :math:`\mathrm{compz}`.

    .. _f08xs-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia

        Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore

        Moler, C B and Stewart, G W, 1973, `An algorithm for generalized matrix eigenproblems`, SIAM J. Numer. Anal. (10), 241--256

        Stewart, G W and Sun, J-G, 1990, `Matrix Perturbation Theory`, Academic Press, London
    """
    raise NotImplementedError

def dtgsja(jobu, jobv, jobq, k, l, a, b, tola, tolb, u, v, q):
    r"""
    ``dtgsja`` computes the generalized singular value decomposition (GSVD) of two real upper trapezoidal matrices :math:`A` and :math:`B`, where :math:`A` is an :math:`m\times n` matrix and :math:`B` is a :math:`p\times n` matrix.

    :math:`A` and :math:`B` are assumed to be in the form returned by :meth:`dggsvp3`.

    .. _f08ye-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08yef.html

    .. _f08ye-py2-py-parameters:

    **Parameters**
        **jobu** : str, length 1
            If :math:`\mathrm{jobu} = \texttt{'U'}`, :math:`\mathrm{u}` must contain an orthogonal matrix :math:`U_1` on entry, and the product :math:`U_1U` is returned.

            If :math:`\mathrm{jobu} = \texttt{'I'}`, :math:`\mathrm{u}` is initialized to the unit matrix, and the orthogonal matrix :math:`U` is returned.

            If :math:`\mathrm{jobu} = \texttt{'N'}`, :math:`U` is not computed.

        **jobv** : str, length 1
            If :math:`\mathrm{jobv} = \texttt{'V'}`, :math:`\mathrm{v}` must contain an orthogonal matrix :math:`V_1` on entry, and the product :math:`V_1V` is returned.

            If :math:`\mathrm{jobv} = \texttt{'I'}`, :math:`\mathrm{v}` is initialized to the unit matrix, and the orthogonal matrix :math:`V` is returned.

            If :math:`\mathrm{jobv} = \texttt{'N'}`, :math:`V` is not computed.

        **jobq** : str, length 1
            If :math:`\mathrm{jobq} = \texttt{'Q'}`, :math:`\mathrm{q}` must contain an orthogonal matrix :math:`Q_1` on entry, and the product :math:`Q_1Q` is returned.

            If :math:`\mathrm{jobq} = \texttt{'I'}`, :math:`\mathrm{q}` is initialized to the unit matrix, and the orthogonal matrix :math:`Q` is returned.

            If :math:`\mathrm{jobq} = \texttt{'N'}`, :math:`Q` is not computed.

        **k** : int
            :math:`\mathrm{k}` and :math:`\mathrm{l}` specify the sizes, :math:`k` and :math:`l`, of the subblocks of :math:`A` and :math:`B`, whose GSVD is to be computed by ``dtgsja``.

        **l** : int
            :math:`\mathrm{k}` and :math:`\mathrm{l}` specify the sizes, :math:`k` and :math:`l`, of the subblocks of :math:`A` and :math:`B`, whose GSVD is to be computed by ``dtgsja``.

        **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(p, n\right)`
            The :math:`p\times n` matrix :math:`B`.

        **tola** : float
            :math:`\mathrm{tola}` and :math:`\mathrm{tolb}` are the convergence criteria for the Jacobi--Kogbetliantz iteration procedure. Generally, they should be the same as used in the preprocessing step performed by :meth:`dggsvp3`, say

            .. math::
                \begin{array}{c}\mathrm{tola} = \mathrm{max}\left(m, n\right)\left\lVert A\right\rVert \epsilon \text{,}\\\mathrm{tolb} = \mathrm{max}\left(p, n\right)\left\lVert B\right\rVert \epsilon \text{,}\end{array}

            where :math:`\epsilon` is the machine precision.

        **tolb** : float
            :math:`\mathrm{tola}` and :math:`\mathrm{tolb}` are the convergence criteria for the Jacobi--Kogbetliantz iteration procedure. Generally, they should be the same as used in the preprocessing step performed by :meth:`dggsvp3`, say

            .. math::
                \begin{array}{c}\mathrm{tola} = \mathrm{max}\left(m, n\right)\left\lVert A\right\rVert \epsilon \text{,}\\\mathrm{tolb} = \mathrm{max}\left(p, n\right)\left\lVert B\right\rVert \epsilon \text{,}\end{array}

            where :math:`\epsilon` is the machine precision.

        **u** : float, array-like, shape :math:`\left(:, :\right)`
            Note: the required extent for this argument in dimension 1 is determined as follows: if :math:`\mathrm{jobu}\text{ in } (\texttt{'U'}, \texttt{'I'})`: :math:`m`; otherwise: :math:`1`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{jobu}\text{ in } (\texttt{'U'}, \texttt{'I'})`: :math:`m`; otherwise: :math:`1`.

            If :math:`\mathrm{jobu} = \texttt{'U'}`, :math:`\mathrm{u}` must contain an :math:`m\times m` matrix :math:`U_1` (usually the orthogonal matrix returned by :meth:`dggsvp3`).

        **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}\text{ in } (\texttt{'V'}, \texttt{'I'})`: :math:`p`; 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{'I'})`: :math:`p`; otherwise: :math:`1`.

            If :math:`\mathrm{jobv} = \texttt{'V'}`, :math:`\mathrm{v}` must contain an :math:`p\times p` matrix :math:`V_1` (usually the orthogonal matrix returned by :meth:`dggsvp3`).

        **q** : float, array-like, shape :math:`\left(:, :\right)`
            Note: the required extent for this argument in dimension 1 is determined as follows: if :math:`\mathrm{jobq}\text{ in } (\texttt{'Q'}, \texttt{'I'})`: :math:`n`; otherwise: :math:`1`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{jobq}\text{ in } (\texttt{'Q'}, \texttt{'I'})`: :math:`n`; otherwise: :math:`1`.

            If :math:`\mathrm{jobq} = \texttt{'Q'}`, :math:`\mathrm{q}` must contain an :math:`n\times n` matrix :math:`Q_1` (usually the orthogonal matrix returned by :meth:`dggsvp3`).

    **Returns**
        **a** : float, ndarray, shape :math:`\left(m, n\right)`
            If :math:`m-k-l\geq 0`, :math:`\mathrm{a}[0:k+l,n-k-l:n]` contains the :math:`\left(k+l\right)\times \left(k+l\right)` upper triangular matrix :math:`R`.

            If :math:`m-k-l < 0`, :math:`\mathrm{a}[0:m,n-k-l:n]` contains the first :math:`m` rows of the :math:`\left(k+l\right)\times \left(k+l\right)` upper triangular matrix :math:`R`, and the submatrix :math:`R_{33}` is returned in :math:`\mathrm{b}[m-k:l,n+m-k-l:n]`.

        **b** : float, ndarray, shape :math:`\left(p, n\right)`
            If :math:`m-k-l < 0`, :math:`\mathrm{b}[m-k:l,n+m-k-l:n]` contains the submatrix :math:`R_{33}` of :math:`R`.

        **alpha** : float, ndarray, shape :math:`\left(n\right)`
            See the description of :math:`\mathrm{beta}`.

        **beta** : float, ndarray, shape :math:`\left(n\right)`
            :math:`\mathrm{alpha}` and :math:`\mathrm{beta}` contain the generalized singular value pairs of :math:`A` and :math:`B`;

                :math:`\mathrm{alpha}[\textit{i}] = 1`, :math:`\mathrm{beta}[\textit{i}] = 0`, for :math:`\textit{i} = 0,\ldots,k-1`, and

                if :math:`m-k-l\geq 0`, :math:`\mathrm{alpha}[\textit{i}] = \alpha_{\textit{i}}`, :math:`\mathrm{beta}[\textit{i}] = \beta_{\textit{i}}`, for :math:`\textit{i} = k,\ldots,k+l-1`, or

                if :math:`m-k-l < 0`, :math:`\mathrm{alpha}[\textit{i}] = \alpha_{\textit{i}}`, :math:`\mathrm{beta}[\textit{i}] = \beta_{\textit{i}}`, for :math:`\textit{i} = k,\ldots,m-1` and :math:`\mathrm{alpha}[\textit{i}] = 0`, :math:`\mathrm{beta}[\textit{i}] = 1`, for :math:`\textit{i} = m,\ldots,k+l-1`.

            Furthermore, if :math:`k+l < n`, :math:`\mathrm{alpha}[\textit{i}] = \mathrm{beta}[\textit{i}] = 0`, for :math:`\textit{i} = k+l,\ldots,n-1`.

        **u** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobu} = \texttt{'U'}`, :math:`\mathrm{u}` contains the product :math:`U_1U`.

            If :math:`\mathrm{jobu} = \texttt{'I'}`, :math:`\mathrm{u}` contains the orthogonal matrix :math:`U`.

            If :math:`\mathrm{jobu} = \texttt{'N'}`, :math:`\mathrm{u}` is not referenced.

        **v** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobv} = \texttt{'I'}`, :math:`\mathrm{v}` contains the orthogonal matrix :math:`V`.

            If :math:`\mathrm{jobv} = \texttt{'V'}`, :math:`\mathrm{v}` contains the product :math:`V_1V`.

            If :math:`\mathrm{jobv} = \texttt{'N'}`, :math:`\mathrm{v}` is not referenced.

        **q** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobq} = \texttt{'I'}`, :math:`\mathrm{q}` contains the orthogonal matrix :math:`Q`.

            If :math:`\mathrm{jobq} = \texttt{'Q'}`, :math:`\mathrm{q}` contains the product :math:`Q_1Q`.

            If :math:`\mathrm{jobq} = \texttt{'N'}`, :math:`\mathrm{q}` is not referenced.

        **ncycle** : int
            The number of cycles required for convergence.

    .. _f08ye-py2-py-errors:

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

                Constraint: :math:`\mathrm{jobu} = \texttt{'U'}`, :math:`\texttt{'I'}` or :math:`\texttt{'N'}`.

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

                Constraint: :math:`\mathrm{jobv} = \texttt{'V'}`, :math:`\texttt{'I'}` or :math:`\texttt{'N'}`.

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

                Constraint: :math:`\mathrm{jobq} = \texttt{'Q'}`, :math:`\texttt{'I'}` 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{p}`.

                Constraint: :math:`p\geq 0`.

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

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

            (`errno` :math:`1`)
                The procedure does not converge after :math:`40` cycles.

    .. _f08ye-py2-py-notes:

    **Notes**
        ``dtgsja`` computes the GSVD of the matrices :math:`A` and :math:`B` which are assumed to have the form as returned by :meth:`dggsvp3`

        .. math::
            \begin{array}{cc}A = & \left\{\begin{array}{c} \begin{matrix}{}\\k\\l\\m-k-l\end{matrix}\begin{pmatrix}n-k-l&k&l\\0&A_{12}&A_{13}\\0&0&A_{23}\\0&0&0\end{pmatrix} \text{, if } m-k-l \geq 0; \\ \begin{matrix}{}\\k\\m-k\end{matrix}\begin{pmatrix}n-k-l&k&l\\0&A_{12}&A_{13}\\0&0&A_{23}\end{pmatrix} \text{, if } m-k-l < 0 ; \end{array}\right. \\\\B = & \begin{matrix}{}\\l\\p-l\end{matrix}\begin{pmatrix}n-k-l&k&l\\0&0&B_{13}\\0&0&0\end{pmatrix} \text{,} \end{array}

        where the :math:`k\times k` matrix :math:`A_{12}` and the :math:`l\times l` matrix :math:`B_{13}` are nonsingular upper triangular, :math:`A_{23}` is :math:`l\times l` upper triangular if :math:`m-k-l\geq 0` and is :math:`\left(m-k\right)\times l` upper trapezoidal otherwise.

        ``dtgsja`` computes orthogonal matrices :math:`Q`, :math:`U` and :math:`V`, diagonal matrices :math:`D_1` and :math:`D_2`, and an upper triangular matrix :math:`R` such that

        .. math::
            U^\mathrm{T}AQ = D_1\begin{pmatrix}0&R\end{pmatrix}\text{, }\quad V^\mathrm{T}BQ = D_2\begin{pmatrix}0&R\end{pmatrix}\text{.}

        Optionally :math:`Q`, :math:`U` and :math:`V` may or may not be computed, or they may be premultiplied by matrices :math:`Q_1`, :math:`U_1` and :math:`V_1` respectively.

        If :math:`\left(m-k-l\right)\geq 0` then :math:`D_1`, :math:`D_2` and :math:`R` have the form

        .. math::
            D_1 = \begin{matrix}{}\\k\\l\\m-k-l\end{matrix}\begin{pmatrix}k&l\\I&0\\0&C\\0&0\end{pmatrix}\text{,}

        .. math::
            D_2 = \begin{matrix}{}\\l\\p-l\end{matrix}\begin{pmatrix}k&l\\0&S\\0&0\end{pmatrix}\text{,}

        .. math::
            R = \begin{matrix}{}\\k\\l\end{matrix}\begin{pmatrix}k&l\\R_{11}&R_{12}\\0&R_{22}\end{pmatrix}\text{,}

        where :math:`C = \mathrm{diag}\left(\alpha_{{k+1}},,, \ldots,,, \alpha_{{k+l}}\right)\text{, }\quad S = \mathrm{diag}\left(\beta_{{k+1}},,, \ldots,,, \beta_{{k+l}}\right)`.

        If :math:`\left(m-k-l\right) < 0` then :math:`D_1`, :math:`D_2` and :math:`R` have the form

        .. math::
            D_1 = \begin{matrix}{}\\k\\m-k\end{matrix}\begin{pmatrix}k&m-k&k+l-m\\I&0&0\\0&C&0\end{pmatrix}\text{,}

        .. math::
            D_2 = \begin{matrix}{}\\m-k\\k+l-m\\p-l\end{matrix}\begin{pmatrix}k&m-k&k+l-m\\0&S&0\\0&0&I\\0&0&0\end{pmatrix}\text{,}

        .. math::
            R = \begin{matrix}{}\\k\\m-k\\k+l-m\end{matrix}\begin{pmatrix}k&m-k&k+l-m\\R_{11}&R_{12}&R_{13}\\0&R_{22}&R_{23}\\0&0&R_{33}\end{pmatrix}\text{,}

        where :math:`C = \mathrm{diag}\left(\alpha_{{k+1}},,, \ldots,,, \alpha_m\right)\text{, }\quad S = \mathrm{diag}\left(\beta_{{k+1}},,, \ldots,,, \beta_m\right)`.

        In both cases the diagonal matrix :math:`C` has non-negative diagonal elements, the diagonal matrix :math:`S` has positive diagonal elements, so that :math:`S` is nonsingular, and :math:`C^2+S^2 = 1`.
        See Section 2.3.5.3 of Anderson `et al.` (1999) for further information.

    .. _f08ye-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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 dtgexc(wantq, wantz, a, b, q, z, ifst, ilst):
    r"""
    ``dtgexc`` reorders the generalized Schur factorization of a matrix pair in real generalized Schur form.

    .. _f08yf-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08yff.html

    .. _f08yf-py2-py-parameters:

    **Parameters**
        **wantq** : bool
            If :math:`\mathrm{wantq} = \mathbf{True}`, update the left transformation matrix :math:`Q`.

            If :math:`\mathrm{wantq} = \mathbf{False}`, do not update :math:`Q`.

        **wantz** : bool
            If :math:`\mathrm{wantz} = \mathbf{True}`, update the right transformation matrix :math:`Z`.

            If :math:`\mathrm{wantz} = \mathbf{False}`, do not update :math:`Z`.

        **a** : float, array-like, shape :math:`\left(n, n\right)`
            The matrix :math:`S` in the pair :math:`\left(S, T\right)`.

        **b** : float, array-like, shape :math:`\left(n, n\right)`
            The matrix :math:`T`, in the pair :math:`\left(S, T\right)`.

        **q** : float, array-like, shape :math:`\left(:, :\right)`
            Note: the required extent for this argument in dimension 1 is determined as follows: if :math:`\mathrm{wantq}= \mathbf{True}`: :math:`n`; otherwise: :math:`1`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{wantq}= \mathbf{True}`: :math:`n`; otherwise: :math:`1`.

            If :math:`\mathrm{wantq} = \mathbf{True}`, the orthogonal matrix :math:`Q`.

        **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{wantz}= \mathbf{True}`: :math:`n`; otherwise: :math:`1`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{wantz}= \mathbf{True}`: :math:`n`; otherwise: :math:`1`.

            If :math:`\mathrm{wantz} = \mathbf{True}`, the orthogonal matrix :math:`Z`.

        **ifst** : int
            The indices :math:`i_1` and :math:`i_2` that specify the reordering of the diagonal blocks of :math:`\left(S, T\right)`. The block with row index :math:`\mathrm{ifst}` is moved to row :math:`\mathrm{ilst}`, by a sequence of swapping between adjacent blocks.

        **ilst** : int
            The indices :math:`i_1` and :math:`i_2` that specify the reordering of the diagonal blocks of :math:`\left(S, T\right)`. The block with row index :math:`\mathrm{ifst}` is moved to row :math:`\mathrm{ilst}`, by a sequence of swapping between adjacent blocks.

    **Returns**
        **a** : float, ndarray, shape :math:`\left(n, n\right)`
            The updated matrix :math:`\hat{S}`.

        **b** : float, ndarray, shape :math:`\left(n, n\right)`
            The updated matrix :math:`\hat{T}`

        **q** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{wantq} = \mathbf{True}`, the updated matrix :math:`Q\hat{Q}`.

            If :math:`\mathrm{wantq} = \mathbf{False}`, :math:`\mathrm{q}` is not referenced.

        **z** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{wantz} = \mathbf{True}`, the updated matrix :math:`Z\hat{Z}`.

            If :math:`\mathrm{wantz} = \mathbf{False}`, :math:`\mathrm{z}` is not referenced.

        **ifst** : int
            If :math:`\mathrm{ifst}` pointed on entry to the second row of a :math:`2\times 2` block, it is changed to point to the first row; :math:`\mathrm{ilst}` always points to the first row of the block in its final position (which may differ from its input value by :math:`+1` or :math:`-1`).

        **ilst** : int
            If :math:`\mathrm{ifst}` pointed on entry to the second row of a :math:`2\times 2` block, it is changed to point to the first row; :math:`\mathrm{ilst}` always points to the first row of the block in its final position (which may differ from its input value by :math:`+1` or :math:`-1`).

    .. _f08yf-py2-py-errors:

    **Raises**
        **NagValueError**
            (`errno` :math:`-3`)
                On entry, error in parameter :math:`\textit{n}`.

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

            (`errno` :math:`-13`)
                On entry, error in parameter :math:`\mathrm{ilst}`.

                Constraint: :math:`1\leq \mathrm{ifst}\leq n` and :math:`1\leq \mathrm{ilst}\leq n`.

            (`errno` :math:`1`)
                The transformed matrix pair would be too far from generalized Schur form; the problem is ill-conditioned. :math:`\left(S, T\right)` may have been partially reordered, and :math:`\mathrm{ilst}` points to the first row of the current position of the block being moved.

    .. _f08yf-py2-py-notes:

    **Notes**
        ``dtgexc`` reorders the generalized real :math:`n\times n` matrix pair :math:`\left(S, T\right)` in real generalized Schur form, so that the diagonal element or block of :math:`\left(S, T\right)` with row index :math:`i_1` is moved to row :math:`i_2`, using an orthogonal equivalence transformation.
        That is, :math:`S` and :math:`T` are factorized as

        .. math::
            S = \hat{Q}\hat{S}\hat{Z}^\mathrm{T}\text{, }\quad T = \hat{Q}\hat{T}\hat{Z}^\mathrm{T}\text{,}

        where :math:`\left(\hat{S}, \hat{T}\right)` are also in real generalized Schur form.

        The pair :math:`\left(S, T\right)` are in real generalized Schur form if :math:`S` is block upper triangular with :math:`1\times 1` and :math:`2\times 2` diagonal blocks and :math:`T` is upper triangular as returned, for example, by :meth:`dgges3`, or :meth:`dhgeqz` with :math:`{\textit{job}} = \texttt{'S'}`.

        If :math:`S` and :math:`T` are the result of a generalized Schur factorization of a matrix pair :math:`\left(A, B\right)`

        .. math::
            A = {QSZ^\mathrm{T}}\text{, }\quad B = {QTZ^\mathrm{T}}

        then, optionally, the matrices :math:`Q` and :math:`Z` can be updated as :math:`Q\hat{Q}` and :math:`Z\hat{Z}`.

    .. _f08yf-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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 dtgsen(ijob, wantq, wantz, select, a, b, q, z):
    r"""
    ``dtgsen`` reorders the generalized Schur factorization of a matrix pair in real generalized Schur form, so that a selected cluster of eigenvalues appears in the leading elements, or blocks on the diagonal of the generalized Schur form.
    The function also, optionally, computes the reciprocal condition numbers of the cluster of eigenvalues and/or corresponding deflating subspaces.

    .. _f08yg-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08ygf.html

    .. _f08yg-py2-py-parameters:

    **Parameters**
        **ijob** : int
            Specifies whether condition numbers are required for the cluster of eigenvalues (:math:`p` and :math:`q`) or the deflating subspaces (:math:`\mathrm{Dif}_u` and :math:`\mathrm{Dif}_l`).

            :math:`\mathrm{ijob} = 0`

                Only reorder with respect to :math:`\mathrm{select}`. No extras.

            :math:`\mathrm{ijob} = 1`

                Reciprocal of norms of 'projections' onto left and right eigenspaces with respect to the selected cluster (:math:`p` and :math:`q`).

            :math:`\mathrm{ijob} = 2`

                The upper bounds on :math:`\mathrm{Dif}_u` and :math:`\mathrm{Dif}_l`. :math:`F`-norm-based estimate (:math:`\mathrm{dif}[0:2]`).

            :math:`\mathrm{ijob} = 3`

                Estimate of :math:`\mathrm{Dif}_u` and :math:`\mathrm{Dif}_l`. :math:`1`-norm-based estimate (:math:`\mathrm{dif}[0:2]`). About five times as expensive as :math:`\mathrm{ijob} = 2`.

            :math:`\mathrm{ijob} = 4`

                Compute :math:`\mathrm{pl}`, :math:`\mathrm{pr}` and :math:`\mathrm{dif}` as in :math:`\mathrm{ijob} = 0`, :math:`1` or :math:`2`. Economic version to get it all.

            :math:`\mathrm{ijob} = 5`

                Compute :math:`\mathrm{pl}`, :math:`\mathrm{pr}` and :math:`\mathrm{dif}` as in :math:`\mathrm{ijob} = 0`, :math:`1` or :math:`3`.

        **wantq** : bool
            If :math:`\mathrm{wantq} = \mathbf{True}`, update the left transformation matrix :math:`Q`.

            If :math:`\mathrm{wantq} = \mathbf{False}`, do not update :math:`Q`.

        **wantz** : bool
            If :math:`\mathrm{wantz} = \mathbf{True}`, update the right transformation matrix :math:`Z`.

            If :math:`\mathrm{wantz} = \mathbf{False}`, do not update :math:`Z`.

        **select** : bool, array-like, shape :math:`\left(n\right)`
            Specifies the eigenvalues in the selected cluster. To select a real eigenvalue :math:`\lambda_j`, :math:`\mathrm{select}[j-1]` must be set to :math:`\mathbf{True}`.

            To select a complex conjugate pair of eigenvalues :math:`\lambda_j` and :math:`\lambda_{{j+1}}`, corresponding to a :math:`2\times 2` diagonal block, either :math:`\mathrm{select}[j-1]` or :math:`\mathrm{select}[j]` or both must be set to :math:`\mathbf{True}`; a complex conjugate pair of eigenvalues must be either both included in the cluster or both excluded.

        **a** : float, array-like, shape :math:`\left(n, n\right)`
            The matrix :math:`S` in the pair :math:`\left(S, T\right)`.

        **b** : float, array-like, shape :math:`\left(n, n\right)`
            The matrix :math:`T`, in the pair :math:`\left(S, T\right)`.

        **q** : float, array-like, shape :math:`\left(:, :\right)`
            Note: the required extent for this argument in dimension 1 is determined as follows: if :math:`\mathrm{wantq}= \mathbf{True}`: :math:`n`; otherwise: :math:`1`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{wantq}= \mathbf{True}`: :math:`n`; otherwise: :math:`1`.

            If :math:`\mathrm{wantq} = \mathbf{True}`, the :math:`n\times n` matrix :math:`Q`.

        **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{wantz}= \mathbf{True}`: :math:`n`; otherwise: :math:`1`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{wantz}= \mathbf{True}`: :math:`n`; otherwise: :math:`1`.

            If :math:`\mathrm{wantz} = \mathbf{True}`, the :math:`n\times n` matrix :math:`Z`.

    **Returns**
        **a** : float, ndarray, shape :math:`\left(n, n\right)`
            The updated matrix :math:`\hat{S}`.

        **b** : float, ndarray, shape :math:`\left(n, n\right)`
            The updated matrix :math:`\hat{T}`

        **alphar** : float, ndarray, shape :math:`\left(n\right)`
            See the description of :math:`\mathrm{beta}`.

        **alphai** : float, ndarray, shape :math:`\left(n\right)`
            See the description of :math:`\mathrm{beta}`.

        **beta** : float, ndarray, shape :math:`\left(n\right)`
            :math:`\mathrm{alphar}[\textit{j}-1]/\mathrm{beta}[\textit{j}-1]` and :math:`\mathrm{alphai}[\textit{j}-1]/\mathrm{beta}[\textit{j}-1]` are the real and imaginary parts respectively of the :math:`\textit{j}`\ th eigenvalue, for :math:`\textit{j} = 1,2,\ldots,n`.

            If :math:`\mathrm{alphai}[j-1]` is zero, then the :math:`j`\ th eigenvalue is real; if positive then :math:`\mathrm{alphai}[j]` is negative, and the :math:`j`\ th and :math:`\left(j+1\right)`\ st eigenvalues are a complex conjugate pair.

            Conjugate pairs of eigenvalues correspond to the :math:`2\times 2` diagonal blocks of :math:`\hat{S}`.

            These :math:`2\times 2` blocks can be reduced by applying complex unitary transformations to :math:`\left(\hat{S}, \hat{T}\right)` to obtain the complex Schur form :math:`\left(\tilde{S}, \tilde{T}\right)`, where :math:`\tilde{S}` is triangular (and complex).

            In this form :math:`\mathrm{alphar}+i\mathrm{alphai}` and :math:`\mathrm{beta}` are the diagonals of :math:`\tilde{S}` and :math:`\tilde{T}` respectively.

        **q** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{wantq} = \mathbf{True}`, the updated matrix :math:`Q\hat{Q}`.

            If :math:`\mathrm{wantq} = \mathbf{False}`, :math:`\mathrm{q}` is not referenced.

        **z** : float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{wantz} = \mathbf{True}`, the updated matrix :math:`Z\hat{Z}`.

            If :math:`\mathrm{wantz} = \mathbf{False}`, :math:`\mathrm{z}` is not referenced.

        **m** : int
            The dimension of the specified pair of left and right eigenspaces (deflating subspaces).

        **pl** : float
            If :math:`\mathrm{ijob} = 1`, :math:`4` or :math:`5`, :math:`\mathrm{pl}` and :math:`\mathrm{pr}` are lower bounds on the reciprocal of the norm of 'projections' :math:`p` and :math:`q` onto left and right eigenspaces with respect to the selected cluster. :math:`0 < \mathrm{pl}`, :math:`\mathrm{pr}\leq 1`.

            If :math:`\mathrm{m} = 0` or :math:`\mathrm{m} = n`, :math:`\mathrm{pl} = \mathrm{pr} = 1`.

            If :math:`\mathrm{ijob} = 0`, :math:`2` or :math:`3`, :math:`\mathrm{pl}` and :math:`\mathrm{pr}` are not referenced.

        **pr** : float
            If :math:`\mathrm{ijob} = 1`, :math:`4` or :math:`5`, :math:`\mathrm{pl}` and :math:`\mathrm{pr}` are lower bounds on the reciprocal of the norm of 'projections' :math:`p` and :math:`q` onto left and right eigenspaces with respect to the selected cluster. :math:`0 < \mathrm{pl}`, :math:`\mathrm{pr}\leq 1`.

            If :math:`\mathrm{m} = 0` or :math:`\mathrm{m} = n`, :math:`\mathrm{pl} = \mathrm{pr} = 1`.

            If :math:`\mathrm{ijob} = 0`, :math:`2` or :math:`3`, :math:`\mathrm{pl}` and :math:`\mathrm{pr}` are not referenced.

        **dif** : float, ndarray, shape :math:`\left(2\right)`
            If :math:`\mathrm{ijob}\geq 2`, :math:`\mathrm{dif}[0:2]` store the estimates of :math:`\mathrm{Dif}_u` and :math:`\mathrm{Dif}_l`.

            If :math:`\mathrm{ijob} = 2` or :math:`4`, :math:`\mathrm{dif}[0:2]` are :math:`F`-norm-based upper bounds on :math:`\mathrm{Dif}_u` and :math:`\mathrm{Dif}_l`.

            If :math:`\mathrm{ijob} = 3` or :math:`5`, :math:`\mathrm{dif}[0:2]` are :math:`1`-norm-based estimates of :math:`\mathrm{Dif}_u` and :math:`\mathrm{Dif}_l`.

            If :math:`\mathrm{m} = 0` or :math:`n`, :math:`\mathrm{dif}[0:2]` :math:`= \left\lVert \left(A, B\right)\right\rVert_F`.

            If :math:`\mathrm{ijob} = 0` or :math:`1`, :math:`\mathrm{dif}` is not referenced.

    .. _f08yg-py2-py-errors:

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

                Constraint: :math:`0\leq \mathrm{ijob}\leq 5`.

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

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

            (`errno` :math:`1`)
                Reordering of :math:`\left(S, T\right)` failed because the transformed matrix pair would be too far from generalized Schur form; the problem is very ill-conditioned. :math:`\left(S, T\right)` may have been partially reordered. If requested, :math:`0` is returned in :math:`\mathrm{dif}[0]` and :math:`\mathrm{dif}[1]`, :math:`\mathrm{pl}` and :math:`\mathrm{pr}`.

    .. _f08yg-py2-py-notes:

    **Notes**
        ``dtgsen`` factorizes the generalized real :math:`n\times n` matrix pair :math:`\left(S, T\right)` in real generalized Schur form, using an orthogonal equivalence transformation as

        .. math::
            S = \hat{Q}\hat{S}\hat{Z}^\mathrm{T}\text{, }\quad T = \hat{Q}\hat{T}\hat{Z}^\mathrm{T}\text{,}

        where :math:`\left(\hat{S}, \hat{T}\right)` are also in real generalized Schur form and have the selected eigenvalues as the leading diagonal elements, or diagonal blocks.
        The leading columns of :math:`Q` and :math:`Z` are the generalized Schur vectors corresponding to the selected eigenvalues and form orthonormal subspaces for the left and right eigenspaces (deflating subspaces) of the pair :math:`\left(S, T\right)`.

        The pair :math:`\left(S, T\right)` are in real generalized Schur form if :math:`S` is block upper triangular with :math:`1\times 1` and :math:`2\times 2` diagonal blocks and :math:`T` is upper triangular as returned, for example, by :meth:`dgges3`, or :meth:`dhgeqz` with :math:`{\textit{job}} = \texttt{'S'}`.
        The diagonal elements, or blocks, define the generalized eigenvalues :math:`\left(\alpha_{\textit{i}}, \beta_{\textit{i}}\right)`, for :math:`\textit{i} = 1,2,\ldots,n`, of the pair :math:`\left(S, T\right)`.
        The eigenvalues are given by

        .. math::
            \lambda_i = \alpha_i/\beta_i\text{,}

        but are returned as the pair :math:`\left(\alpha_i, \beta_i\right)` in order to avoid possible overflow in computing :math:`\lambda_i`.
        Optionally, the function returns reciprocals of condition number estimates for the selected eigenvalue cluster, :math:`p` and :math:`q`, the right and left projection norms, and of deflating subspaces, :math:`\mathrm{Dif}_u` and :math:`\mathrm{Dif}_l`.
        For more information see Sections 2.4.8 and 4.11 of Anderson `et al.` (1999).

        If :math:`S` and :math:`T` are the result of a generalized Schur factorization of a matrix pair :math:`\left(A, B\right)`

        .. math::
            A = {QSZ^\mathrm{T}}\text{, }\quad B = {QTZ^\mathrm{T}}

        then, optionally, the matrices :math:`Q` and :math:`Z` can be updated as :math:`Q\hat{Q}` and :math:`Z\hat{Z}`.
        Note that the condition numbers of the pair :math:`\left(S, T\right)` are the same as those of the pair :math:`\left(A, B\right)`.

    .. _f08yg-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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 dtgsyl(trans, ijob, a, b, c, d, e, f):
    r"""
    ``dtgsyl`` solves the generalized real quasi-triangular Sylvester equations.

    .. _f08yh-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08yhf.html

    .. _f08yh-py2-py-parameters:

    **Parameters**
        **trans** : str, length 1
            If :math:`\mathrm{trans} = \texttt{'N'}`, solve the generalized Sylvester equation `(1) <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08yhf.html#eqn1>`__.

            If :math:`\mathrm{trans} = \texttt{'T'}`, solve the 'transposed' system `(2) <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08yhf.html#eqn2>`__.

        **ijob** : int
            Specifies what kind of functionality is to be performed when :math:`\mathrm{trans} = \texttt{'N'}`.

            :math:`\mathrm{ijob} = 0`

                Solve `(1) <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08yhf.html#eqn1>`__ only.

            :math:`\mathrm{ijob} = 1`

                The functionality of :math:`\mathrm{ijob} = 0` or :math:`3`.

            :math:`\mathrm{ijob} = 2`

                The functionality of :math:`\mathrm{ijob} = 0` or :math:`4`.

            :math:`\mathrm{ijob} = 3`

                Only an estimate of :math:`\textit{Dif}\left[\left(A, D\right), \left(B, E\right)\right]` is computed based on the Frobenius norm.

            :math:`\mathrm{ijob} = 4`

                Only an estimate of :math:`\textit{Dif}\left[\left(A, D\right), \left(B, E\right)\right]` is computed based on the :math:`1`-norm.

            If :math:`\mathrm{trans} = \texttt{'T'}`, :math:`\mathrm{ijob}` is not referenced.

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

        **b** : float, array-like, shape :math:`\left(n, n\right)`
            The upper quasi-triangular matrix :math:`B`.

        **c** : float, array-like, shape :math:`\left(m, n\right)`
            Contains the right-hand-side matrix :math:`C`.

        **d** : float, array-like, shape :math:`\left(m, m\right)`
            The upper triangular matrix :math:`D`.

        **e** : float, array-like, shape :math:`\left(n, n\right)`
            The upper triangular matrix :math:`E`.

        **f** : float, array-like, shape :math:`\left(m, n\right)`
            Contains the right-hand side matrix :math:`F`.

    **Returns**
        **c** : float, ndarray, shape :math:`\left(m, n\right)`
            If :math:`\mathrm{ijob} = 0`, :math:`1` or :math:`2`, :math:`\mathrm{c}` is overwritten by the solution matrix :math:`R`.

            If :math:`\mathrm{trans} = \texttt{'N'}` and :math:`\mathrm{ijob} = 3` or :math:`4`, :math:`\mathrm{c}` holds :math:`R`, the solution achieved during the computation of the Dif estimate.

        **f** : float, ndarray, shape :math:`\left(m, n\right)`
            If :math:`\mathrm{ijob} = 0`, :math:`1` or :math:`2`, :math:`\mathrm{f}` is overwritten by the solution matrix :math:`L`.

            If :math:`\mathrm{trans} = \texttt{'N'}` and :math:`\mathrm{ijob} = 3` or :math:`4`, :math:`\mathrm{f}` holds :math:`L`, the solution achieved during the computation of the Dif estimate.

        **scale** : float
            :math:`\alpha`, the scaling factor in `(1) <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08yhf.html#eqn1>`__ and `(2) <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08yhf.html#eqn1>`__.

            If :math:`0 < \mathrm{scale} < 1`, :math:`\mathrm{c}` and :math:`\mathrm{f}` hold the solutions :math:`R` and :math:`L`, respectively, to a slightly perturbed system but the input arrays :math:`\mathrm{a}`, :math:`\mathrm{b}`, :math:`\mathrm{d}` and :math:`\mathrm{e}` have not been changed.

            If :math:`\mathrm{scale} = 0`, :math:`\mathrm{c}` and :math:`\mathrm{f}` hold the solutions :math:`R` and :math:`L`, respectively, to the homogeneous system with :math:`C = F = 0`.

            In this case :math:`\mathrm{dif}` is not referenced.

            Normally, :math:`\mathrm{scale} = 1`.

        **dif** : float
            The estimate of :math:`\mathrm{Dif}`. If :math:`\mathrm{ijob} = 0`, :math:`\mathrm{dif}` is not referenced.

    .. _f08yh-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:`\mathrm{ijob}`.

                Constraint: :math:`0\leq \mathrm{ijob}\leq 4`.

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

                Constraint: :math:`m > 0`.

            (`errno` :math:`-4`)
                On entry, error in parameter :math:`\textit{n}`.

                Constraint: :math:`n > 0`.

            (`errno` :math:`i > 0`)
                :math:`\left(A, D\right)` and :math:`\left(B, E\right)` have common or close eigenvalues and so no solution could be computed.

    .. _f08yh-py2-py-notes:

    **Notes**
        ``dtgsyl`` solves either the generalized real Sylvester equations

        .. math::
            \begin{array}{cc}AR-LB& = \alpha C\\DR-LE& = \alpha F\text{,}\end{array}

        or the equations

        .. math::
            \begin{array}{cc}A^\mathrm{T}R+D^\mathrm{T}L& = \alpha C\\RB^\mathrm{T}+LE^\mathrm{T}& = {-\alpha }F\text{,}\end{array}

        where the pair :math:`\left(A, D\right)` are given :math:`m\times m` matrices in real generalized Schur form, :math:`\left(B, E\right)` are given :math:`n\times n` matrices in real generalized Schur form and :math:`\left(C, F\right)` are given :math:`m\times n` matrices.
        The pair :math:`\left(R, L\right)` are the :math:`m\times n` solution matrices, and :math:`\alpha` is an output scaling factor determined by the function to avoid overflow in computing :math:`\left(R, L\right)`.

        Equations `(1) <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08yhf.html#eqn1>`__ are equivalent to equations of the form

        .. math::
            Zx = \alpha b\text{,}

        where

        .. math::
            Z = \begin{pmatrix}I⊗A-B^\mathrm{T}⊗I\\I⊗D-E^\mathrm{T}⊗I\end{pmatrix}

        and :math:`⊗` is the Kronecker product.
        Equations `(2) <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08yhf.html#eqn2>`__ are then equivalent to

        .. math::
            Z^\mathrm{T}y = \alpha b\text{.}

        The pair :math:`\left(S, T\right)` are in real generalized Schur form if :math:`S` is block upper triangular with :math:`1\times 1` and :math:`2\times 2` diagonal blocks on the diagonal and :math:`T` is upper triangular as returned, for example, by :meth:`dgges3`, or :meth:`dhgeqz` with :math:`{\textit{job}} = \texttt{'S'}`.

        Optionally, the function estimates :math:`\mathrm{Dif}\left[\left(A, D\right), \left(B, E\right)\right]`, the separation between the matrix pairs :math:`\left(A, D\right)` and :math:`\left(B, E\right)`, which is the smallest singular value of :math:`Z`.
        The estimate can be based on either the Frobenius norm, or the :math:`1`-norm.
        The :math:`1`-norm estimate can be three to ten times more expensive than the Frobenius norm estimate, but makes the condition estimation uniform with the nonsymmetric eigenproblem.
        The Frobenius norm estimate provides a low cost, but equally reliable estimate.
        For more information see Sections 2.4.8.3 and 4.11.1.3 of Anderson `et al.` (1999) and Kågström and Poromaa (1996).

    .. _f08yh-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug

        Kågström, B, 1994, `A perturbation analysis of the generalized Sylvester equation` :math:`\left({AR-LB}, {DR-LE}\right) = \left(c, F\right)`, SIAM J. Matrix Anal. Appl. (15), 1045--1060

        Kågström, B and Poromaa, P, 1996, `LAPACK-style algorithms and software for solving the generalized Sylvester equation and estimating the separation between regular matrix pairs`, ACM Trans. Math. Software (22), 78--103
    """
    raise NotImplementedError

def dtgevc(side, howmny, a, b, select=None, vl=None, vr=None):
    r"""
    ``dtgevc`` computes some or all of the right and/or left generalized eigenvectors of a pair of real matrices :math:`\left(A, B\right)` which are in generalized real Schur form.

    .. _f08yk-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08ykf.html

    .. _f08yk-py2-py-parameters:

    **Parameters**
        **side** : str, length 1
            Specifies the required sets of generalized eigenvectors.

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

                Only right eigenvectors are computed.

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

                Only left eigenvectors are computed.

            :math:`\mathrm{side} = \texttt{'B'}`

                Both left and right eigenvectors are computed.

        **howmny** : str, length 1
            Specifies further details of the required generalized eigenvectors.

            :math:`\mathrm{howmny} = \texttt{'A'}`

                All right and/or left eigenvectors are computed.

            :math:`\mathrm{howmny} = \texttt{'B'}`

                All right and/or left eigenvectors are computed; they are backtransformed using the input matrices supplied in arrays :math:`\mathrm{vr}` and/or :math:`\mathrm{vl}`.

            :math:`\mathrm{howmny} = \texttt{'S'}`

                Selected right and/or left eigenvectors, defined by the array :math:`\mathrm{select}`, are computed.

        **a** : float, array-like, shape :math:`\left(n, n\right)`
            The matrix pair :math:`\left(A, B\right)` must be in the generalized Schur form. Usually, this is the matrix :math:`A` returned by :meth:`dhgeqz`.

        **b** : float, array-like, shape :math:`\left(n, n\right)`
            The matrix pair :math:`\left(A, B\right)` must be in the generalized Schur form. If :math:`A` has a :math:`2\times 2` diagonal block then the corresponding :math:`2\times 2` block of :math:`B` must be diagonal with positive elements. Usually, this is the matrix :math:`B` returned by :meth:`dhgeqz`.

        **select** : None or bool, array-like, shape :math:`\left(:\right)`, optional
            Note: the required length for this argument is determined as follows: if :math:`\mathrm{howmny}=\texttt{'S'}`: :math:`n`; otherwise: :math:`1`.

            Specifies the eigenvectors to be computed if :math:`\mathrm{howmny} = \texttt{'S'}`. To select the generalized eigenvector corresponding to the :math:`j`\ th generalized eigenvalue, the :math:`j`\ th element of :math:`\mathrm{select}` should be set to :math:`\mathbf{True}`; if the eigenvalue corresponds to a complex conjugate pair, then real and imaginary parts of eigenvectors corresponding to the complex conjugate eigenvalue pair will be computed.

            If :math:`\mathrm{howmny} = \texttt{'A'}` or :math:`\texttt{'B'}`, :math:`\mathrm{select}` is not referenced.

        **vl** : 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{side}\text{ in } (\texttt{'L'}, \texttt{'B'})`: :math:`n`; if :math:`\mathrm{side}=\texttt{'R'}`: :math:`1`; otherwise: :math:`0`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{side}\text{ in } (\texttt{'L'}, \texttt{'B'})`: :math:`\textit{mm}`; if :math:`\mathrm{side}=\texttt{'R'}`: :math:`1`; otherwise: :math:`0`.

            If :math:`\mathrm{howmny} = \texttt{'B'}` and :math:`\mathrm{side} = \texttt{'L'}` or :math:`\texttt{'B'}`, :math:`\mathrm{vl}` must be initialized to an :math:`n\times n` matrix :math:`Q`. Usually, this is the orthogonal matrix :math:`Q` of left Schur vectors returned by :meth:`dhgeqz`.

        **vr** : 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{side}\text{ in } (\texttt{'R'}, \texttt{'B'})`: :math:`n`; if :math:`\mathrm{side}=\texttt{'L'}`: :math:`1`; otherwise: :math:`0`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{side}\text{ in } (\texttt{'R'}, \texttt{'B'})`: :math:`\textit{mm}`; if :math:`\mathrm{side}=\texttt{'L'}`: :math:`1`; otherwise: :math:`0`.

            If :math:`\mathrm{howmny} = \texttt{'B'}` and :math:`\mathrm{side} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{vr}` must be initialized to an :math:`n\times n` matrix :math:`Z`. Usually, this is the orthogonal matrix :math:`Z` of right Schur vectors returned by :meth:`dhgeqz`.

    **Returns**
        **vl** : None or float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{side} = \texttt{'L'}` or :math:`\texttt{'B'}`, :math:`\mathrm{vl}` contains:

                if :math:`\mathrm{howmny} = \texttt{'A'}`, the matrix :math:`Y` of left eigenvectors of :math:`\left(A, B\right)`;

                if :math:`\mathrm{howmny} = \texttt{'B'}`, the matrix :math:`QY`;

                if :math:`\mathrm{howmny} = \texttt{'S'}`, the left eigenvectors of :math:`\left(A, B\right)` specified by :math:`\mathrm{select}`, stored consecutively in the columns of the array :math:`\mathrm{vl}`, in the same order as their corresponding eigenvalues.

            A complex eigenvector corresponding to a complex eigenvalue is stored in two consecutive columns, the first holding the real part, and the second the imaginary part.

            If :math:`\mathrm{side} = \texttt{'R'}`, :math:`\mathrm{vl}` is not referenced.

        **vr** : None or float, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{side} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{vr}` contains:

                if :math:`\mathrm{howmny} = \texttt{'A'}`, the matrix :math:`X` of right eigenvectors of :math:`\left(A, B\right)`;

                if :math:`\mathrm{howmny} = \texttt{'B'}`, the matrix :math:`ZX`;

                if :math:`\mathrm{howmny} = \texttt{'S'}`, the right eigenvectors of :math:`\left(A, B\right)` specified by :math:`\mathrm{select}`, stored consecutively in the columns of the array :math:`\mathrm{vr}`, in the same order as their corresponding eigenvalues.

            A complex eigenvector corresponding to a complex eigenvalue is stored in two consecutive columns, the first holding the real part, and the second the imaginary part.

            If :math:`\mathrm{side} = \texttt{'L'}`, :math:`\mathrm{vr}` is not referenced.

        **m** : int
            The number of columns in the arrays :math:`\mathrm{vl}` and/or :math:`\mathrm{vr}` actually used to store the eigenvectors. If :math:`\mathrm{howmny} = \texttt{'A'}` or :math:`\texttt{'B'}`, :math:`\mathrm{m}` is set to :math:`\textit{n}`. Each selected real eigenvector occupies one column and each selected complex eigenvector occupies two columns.

    .. _f08yk-py2-py-errors:

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

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

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

                Constraint: :math:`\mathrm{howmny} = \texttt{'A'}`, :math:`\texttt{'B'}` or :math:`\texttt{'S'}`.

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

                Constraint: :math:`\mathrm{select}[\textit{j}] = \mathbf{True}` or :math:`\mathbf{False}`, for :math:`\textit{j} = 0,\ldots,n-1`.

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

            (`errno` :math:`-7`)
                On entry, error in parameter :math:`\mathrm{b}`.

            (`errno` :math:`-13`)
                On entry, error in parameter :math:`\textit{mm}`.

    **Warns**
        **NagAlgorithmicWarning**
            (`errno` :math:`i > 0`)
                The :math:`2\times 2` block :math:`\left(\langle\mathit{\boldsymbol{value}}\rangle:\langle\mathit{\boldsymbol{value}}\rangle+1\right)` does not have complex eigenvalues.

    .. _f08yk-py2-py-notes:

    **Notes**
        ``dtgevc`` computes some or all of the right and/or left generalized eigenvectors of the matrix pair :math:`\left(A, B\right)` which is assumed to be in generalized upper Schur form.
        If the matrix pair :math:`\left(A, B\right)` is not in the generalized upper Schur form, then :meth:`dhgeqz` should be called before invoking ``dtgevc``.

        The right generalized eigenvector :math:`x` and the left generalized eigenvector :math:`y` of :math:`\left(A, B\right)` corresponding to a generalized eigenvalue :math:`\lambda` are defined by

        .. math::
            \left(A-\lambda B\right)x = 0

        and

        .. math::
            y^\mathrm{H}\left(A-\lambda B\right) = 0\text{.}

        If a generalized eigenvalue is determined as :math:`0/0`, which is due to zero diagonal elements at the same locations in both :math:`A` and :math:`B`, a unit vector is returned as the corresponding eigenvector.

        Note that the generalized eigenvalues are computed using :meth:`dhgeqz` but ``dtgevc`` does not explicitly require the generalized eigenvalues to compute eigenvectors.
        The ordering of the eigenvectors is based on the ordering of the eigenvalues as computed by ``dtgevc``.

        If all eigenvectors are requested, the function may either return the matrices :math:`X` and/or :math:`Y` of right or left eigenvectors of :math:`\left(A, B\right)`, or the products :math:`ZX` and/or :math:`QY`, where :math:`Z` and :math:`Q` are two matrices supplied by you.
        Usually, :math:`Q` and :math:`Z` are chosen as the orthogonal matrices returned by :meth:`dhgeqz`.
        Equivalently, :math:`Q` and :math:`Z` are the left and right Schur vectors of the matrix pair supplied to :meth:`dhgeqz`.
        In that case, :math:`QY` and :math:`ZX` are the left and right generalized eigenvectors, respectively, of the matrix pair supplied to :meth:`dhgeqz`.

        :math:`A` must be block upper triangular; with :math:`1\times 1` and :math:`2\times 2` diagonal blocks.
        Corresponding to each :math:`2\times 2` diagonal block is a complex conjugate pair of eigenvalues and eigenvectors; only one eigenvector of the pair is computed, namely the one corresponding to the eigenvalue with positive imaginary part.
        Each :math:`1\times 1` block gives a real generalized eigenvalue and a corresponding eigenvector.

    .. _f08yk-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia

        Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore

        Moler, C B and Stewart, G W, 1973, `An algorithm for generalized matrix eigenproblems`, SIAM J. Numer. Anal. (10), 241--256

        Stewart, G W and Sun, J-G, 1990, `Matrix Perturbation Theory`, Academic Press, London
    """
    raise NotImplementedError

def dtgsna(job, howmny, a, b, mm, select=None, vl=None, vr=None):
    r"""
    ``dtgsna`` estimates condition numbers for specified eigenvalues and/or eigenvectors of a matrix pair in generalized real Schur form.

    .. _f08yl-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08ylf.html

    .. _f08yl-py2-py-parameters:

    **Parameters**
        **job** : str, length 1
            Indicates whether condition numbers are required for eigenvalues and/or eigenvectors.

            :math:`\mathrm{job} = \texttt{'E'}`

                Condition numbers for eigenvalues only are computed.

            :math:`\mathrm{job} = \texttt{'V'}`

                Condition numbers for eigenvectors only are computed.

            :math:`\mathrm{job} = \texttt{'B'}`

                Condition numbers for both eigenvalues and eigenvectors are computed.

        **howmny** : str, length 1
            Indicates how many condition numbers are to be computed.

            :math:`\mathrm{howmny} = \texttt{'A'}`

                Condition numbers for all eigenpairs are computed.

            :math:`\mathrm{howmny} = \texttt{'S'}`

                Condition numbers for selected eigenpairs (as specified by :math:`\mathrm{select}`) are computed.

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

        **b** : float, array-like, shape :math:`\left(n, n\right)`
            The upper triangular matrix :math:`T`.

        **mm** : int
            The number of elements in the arrays :math:`\mathrm{s}` and :math:`\mathrm{dif}`.

        **select** : None or bool, array-like, shape :math:`\left(:\right)`, optional
            Note: the required length for this argument is determined as follows: if :math:`\mathrm{howmny}=\texttt{'S'}`: :math:`n`; otherwise: :math:`1`.

            Specifies the eigenpairs for which condition numbers are to be computed if :math:`\mathrm{howmny} = \texttt{'S'}`. To select condition numbers for the eigenpair corresponding to the real eigenvalue :math:`\lambda_j`, :math:`\mathrm{select}[j-1]` must be set :math:`\mathbf{True}`. To select condition numbers corresponding to a complex conjugate pair of eigenvalues :math:`\lambda_j` and :math:`\lambda_{{j+1}}`, :math:`\mathrm{select}[j-1]` and/or :math:`\mathrm{select}[j]` must be set to :math:`\mathbf{True}`.

            If :math:`\mathrm{howmny} = \texttt{'A'}`, :math:`\mathrm{select}` is not referenced.

        **vl** : 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{job}\text{ in } (\texttt{'E'}, \texttt{'B'})`: :math:`n`; otherwise: :math:`1`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{job}\text{ in } (\texttt{'E'}, \texttt{'B'})`: :math:`\mathrm{mm}`; otherwise: :math:`0`.

            If :math:`\mathrm{job} = \texttt{'E'}` or :math:`\texttt{'B'}`, :math:`\mathrm{vl}` must contain left eigenvectors of :math:`\left(S, T\right)`, corresponding to the eigenpairs specified by :math:`\mathrm{howmny}` and :math:`\mathrm{select}`. The eigenvectors must be stored in consecutive columns of :math:`\mathrm{vl}`, as returned by :meth:`dggev3` or :meth:`dtgevc`.

            If :math:`\mathrm{job} = \texttt{'V'}`, :math:`\mathrm{vl}` is not referenced.

        **vr** : 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{job}\text{ in } (\texttt{'E'}, \texttt{'B'})`: :math:`n`; otherwise: :math:`1`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{job}\text{ in } (\texttt{'E'}, \texttt{'B'})`: :math:`\mathrm{mm}`; otherwise: :math:`0`.

            If :math:`\mathrm{job} = \texttt{'E'}` or :math:`\texttt{'B'}`, :math:`\mathrm{vr}` must contain right eigenvectors of :math:`\left(S, T\right)`, corresponding to the eigenpairs specified by :math:`\mathrm{howmny}` and :math:`\mathrm{select}`. The eigenvectors must be stored in consecutive columns of :math:`\mathrm{vr}`, as returned by :meth:`dggev3` or :meth:`dtgevc`.

            If :math:`\mathrm{job} = \texttt{'V'}`, :math:`\mathrm{vr}` is not referenced.

    **Returns**
        **s** : float, ndarray, shape :math:`\left(:\right)`
            If :math:`\mathrm{job} = \texttt{'E'}` or :math:`\texttt{'B'}`, the reciprocal condition numbers of the selected eigenvalues, stored in consecutive elements of the array. For a complex conjugate pair of eigenvalues two consecutive elements of :math:`\mathrm{s}` are set to the same value. Thus :math:`\mathrm{s}[j-1]`, :math:`\mathrm{dif}[j-1]`, and the :math:`j`\ th columns of :math:`\mathrm{VL}` and :math:`\mathrm{VR}` all correspond to the same eigenpair (but not in general the :math:`j`\ th eigenpair, unless all eigenpairs are selected).

            If :math:`\mathrm{job} = \texttt{'V'}`, :math:`\mathrm{s}` is not referenced.

        **dif** : float, ndarray, shape :math:`\left(:\right)`
            If :math:`\mathrm{job} = \texttt{'V'}` or :math:`\texttt{'B'}`, the estimated reciprocal condition numbers of the selected eigenvectors, stored in consecutive elements of the array. For a complex eigenvector two consecutive elements of :math:`\mathrm{dif}` are set to the same value. If the eigenvalues cannot be reordered to compute :math:`\mathrm{dif}[j-1]`, :math:`\mathrm{dif}[j-1]` is set to :math:`0`; this can only occur when the true value would be very small anyway.

            If :math:`\mathrm{job} = \texttt{'E'}`, :math:`\mathrm{dif}` is not referenced.

        **m** : int
            M, the number of elements of the arrays :math:`\mathrm{s}` and :math:`\mathrm{dif}` used to store the specified condition numbers; for each selected real eigenvalue one element is used, and for each selected complex conjugate pair of eigenvalues, two elements are used. If :math:`\mathrm{howmny} = \texttt{'A'}`, :math:`\mathrm{m}` is set to :math:`\textit{n}`.

    .. _f08yl-py2-py-errors:

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

                Constraint: :math:`\mathrm{job} = \texttt{'E'}`, :math:`\texttt{'V'}` or :math:`\texttt{'B'}`.

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

                Constraint: :math:`\mathrm{howmny} = \texttt{'A'}` or :math:`\texttt{'S'}`.

            (`errno` :math:`-4`)
                On entry, error in parameter :math:`\textit{n}`.

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

            (`errno` :math:`-15`)
                On entry, error in parameter :math:`\mathrm{mm}`.

                Constraint: :math:`\mathrm{mm}\geq n`.

            (`errno` :math:`-15`)
                On entry, error in parameter :math:`\mathrm{mm}`.

                Constraint: :math:`\mathrm{mm}\geq \textit{m}`.

    .. _f08yl-py2-py-notes:

    **Notes**
        ``dtgsna`` estimates condition numbers for specified eigenvalues and/or right eigenvectors of an :math:`n\times n` matrix pair :math:`\left(S, T\right)` in real generalized Schur form.
        The function actually returns estimates of the reciprocals of the condition numbers in order to avoid possible overflow.

        The pair :math:`\left(S, T\right)` are in real generalized Schur form if :math:`S` is block upper triangular with :math:`1\times 1` and :math:`2\times 2` diagonal blocks and :math:`T` is upper triangular as returned, for example, by :meth:`dggesx` or :meth:`dgges3`, or :meth:`dhgeqz` with :math:`{\textit{job}} = \texttt{'S'}`.
        The diagonal elements, or blocks, define the generalized eigenvalues :math:`\left(\alpha_{\textit{i}}, \beta_{\textit{i}}\right)`, for :math:`\textit{i} = 1,2,\ldots,n`, of the pair :math:`\left(S, T\right)` and the eigenvalues are given by

        .. math::
            \lambda_i = \alpha_i/\beta_i\text{,}

        so that

        .. math::
            \beta_iSx_i = \alpha_iTx_i\quad \text{ or }\quad Sx_i = \lambda_iTx_i\text{,}

        where :math:`x_i` is the corresponding (right) eigenvector.

        If :math:`S` and :math:`T` are the result of a generalized Schur factorization of a matrix pair :math:`\left(A, B\right)`

        .. math::
            A = {QSZ^\mathrm{T}}\text{, }\quad B = {QTZ^\mathrm{T}}

        then the eigenvalues and condition numbers of the pair :math:`\left(S, T\right)` are the same as those of the pair :math:`\left(A, B\right)`.

        Let :math:`\left(\alpha, \beta \right)\neq \left(0, 0\right)` be a simple generalized eigenvalue of :math:`\left(A, B\right)`.
        Then the reciprocal of the condition number of the eigenvalue :math:`\lambda = \alpha /\beta` is defined as

        .. math::
            s\left(\lambda \right) = \frac{\left(\left\lvert y^\mathrm{T}Ax\right\rvert^2+\left\lvert y^\mathrm{T}Bx\right\rvert^2\right)^{{1/2}}}{\left(\left\lVert x\right\rVert_2\left\lVert y\right\rVert_2\right)}\text{,}

        where :math:`x` and :math:`y` are the right and left eigenvectors of :math:`\left(A, B\right)` corresponding to :math:`\lambda`.
        If both :math:`\alpha` and :math:`\beta` are zero, then :math:`\left(A, B\right)` is singular and :math:`s\left(\lambda \right) = -1` is returned.

        The definition of the reciprocal of the estimated condition number of the right eigenvector :math:`x` and the left eigenvector :math:`y` corresponding to the simple eigenvalue :math:`\lambda` depends upon whether :math:`\lambda` is a real eigenvalue, or one of a complex conjugate pair.

        If the eigenvalue :math:`\lambda` is real and :math:`U` and :math:`V` are orthogonal transformations such that

        .. math::
            U^\mathrm{T}\left(A, B\right)V = \left(S, T\right) = \begin{pmatrix}\alpha &*\\0&S_{22}\end{pmatrix}\begin{pmatrix}\beta &*\\0&T_{22}\end{pmatrix}\text{,}

        where :math:`S_{22}` and :math:`T_{22}` are :math:`\left(n-1\right)\times \left(n-1\right)` matrices, then the reciprocal condition number is given by

        .. math::
            \mathrm{Dif}\left(x\right)\equiv \mathrm{Dif}\left(y\right) = \mathrm{Dif}\left(\left(\alpha, \beta \right), \left(S_{22}, T_{22}\right)\right) = \sigma_{\mathrm{min}}\left(Z\right)\text{,}

        where :math:`\sigma_{\mathrm{min}}\left(Z\right)` denotes the smallest singular value of the :math:`2\left(n-1\right)\times 2\left(n-1\right)` matrix

        .. math::
            Z = \begin{pmatrix}\alpha ⊗I&-1⊗S_{22}\\\beta ⊗I&-1⊗T_{22}\end{pmatrix}

        and :math:`⊗` is the Kronecker product.

        If :math:`\lambda` is part of a complex conjugate pair and :math:`U` and :math:`V` are orthogonal transformations such that

        .. math::
            U^\mathrm{T}\left(A, B\right)V = \left(S, T\right) = \begin{pmatrix}S_{11}&*\\0&S_{22}\end{pmatrix}\begin{pmatrix}T_{11}&*\\0&T_{22}\end{pmatrix}\text{,}

        where :math:`S_{11}` and :math:`T_{11}` are two by two matrices, :math:`S_{22}` and :math:`T_{22}` are :math:`\left(n-2\right)\times \left(n-2\right)` matrices, and :math:`\left(S_{11}, T_{11}\right)` corresponds to the complex conjugate eigenvalue pair :math:`\lambda`, :math:`\bar{\lambda }`, then there exist unitary matrices :math:`U_1` and :math:`V_1` such that

        .. math::
            U_1^HS_{11}V_1 = \begin{pmatrix}s_{11}&s_{12}\\0&s_{22}\end{pmatrix}\quad \text{ and }\quad U_1^HT_{11}V_1 = \begin{pmatrix}t_{11}&t_{12}\\0&t_{22}\end{pmatrix}\text{.}

        The eigenvalues are given by :math:`\lambda = s_{11}/t_{11}` and :math:`\bar{\lambda } = s_{22}/t_{22}`.
        Then the Frobenius norm-based, estimated reciprocal condition number is bounded by

        .. math::
            \mathrm{Dif}\left(x\right)\equiv \mathrm{Dif}\left(y\right)\leq \mathrm{min}\left(d_1, \mathrm{max}\left(1, \left\lvert \mathrm{Re}\left(s_{11}\right)/\mathrm{Re}\left(s_{22}\right)\right\rvert \right), d_2\right)

        where :math:`\mathrm{Re}\left(z\right)` denotes the real part of :math:`z`, :math:`d_1 = \mathrm{Dif}\left(\left(s_{11}, t_{11}\right), \left(s_{22}, t_{22}\right)\right) = \sigma_{\mathrm{min}}\left(Z_1\right)`, :math:`Z_1` is the complex two by two matrix

        .. math::
            Z_1 = \begin{pmatrix}s_{11}&{-s_{22}}\\t_{11}&{-t_{22}}\end{pmatrix}\text{,}

        and :math:`d_2` is an upper bound on :math:`\mathrm{Dif}\left(\left(S_{11}, T_{11}\right), \left(S_{22}, T_{22}\right)\right)`; i.e., an upper bound on :math:`\sigma_{\mathrm{min}}\left(Z_2\right)`, where :math:`Z_2` is the :math:`\left(2n-2\right)\times \left(2n-2\right)` matrix

        .. math::
            Z_2 = \begin{pmatrix}S_{11}^T⊗I&{-I}⊗S_{22}\\T_{11}^T⊗I&{-I}⊗T_{22}\end{pmatrix}\text{.}

        See Sections 2.4.8 and 4.11 of Anderson `et al.` (1999) and Kågström and Poromaa (1996) for further details and information.

    .. _f08yl-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug

        Kågström, B and Poromaa, P, 1996, `LAPACK-style algorithms and software for solving the generalized Sylvester equation and estimating the separation between regular matrix pairs`, ACM Trans. Math. Software (22), 78--103
    """
    raise NotImplementedError

def ztgsja(jobu, jobv, jobq, k, l, a, b, tola, tolb, u, v, q):
    r"""
    ``ztgsja`` computes the generalized singular value decomposition (GSVD) of two complex upper trapezoidal matrices :math:`A` and :math:`B`, where :math:`A` is an :math:`m\times n` matrix and :math:`B` is a :math:`p\times n` matrix.

    :math:`A` and :math:`B` are assumed to be in the form returned by :meth:`zggsvp3`.

    .. _f08ys-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08ysf.html

    .. _f08ys-py2-py-parameters:

    **Parameters**
        **jobu** : str, length 1
            If :math:`\mathrm{jobu} = \texttt{'U'}`, :math:`\mathrm{u}` must contain a unitary matrix :math:`U_1` on entry, and the product :math:`U_1U` is returned.

            If :math:`\mathrm{jobu} = \texttt{'I'}`, :math:`\mathrm{u}` is initialized to the unit matrix, and the unitary matrix :math:`U` is returned.

            If :math:`\mathrm{jobu} = \texttt{'N'}`, :math:`U` is not computed.

        **jobv** : str, length 1
            If :math:`\mathrm{jobv} = \texttt{'V'}`, :math:`\mathrm{v}` must contain a unitary matrix :math:`V_1` on entry, and the product :math:`V_1V` is returned.

            If :math:`\mathrm{jobv} = \texttt{'I'}`, :math:`\mathrm{v}` is initialized to the unit matrix, and the unitary matrix :math:`V` is returned.

            If :math:`\mathrm{jobv} = \texttt{'N'}`, :math:`V` is not computed.

        **jobq** : str, length 1
            If :math:`\mathrm{jobq} = \texttt{'Q'}`, :math:`\mathrm{q}` must contain a unitary matrix :math:`Q_1` on entry, and the product :math:`Q_1Q` is returned.

            If :math:`\mathrm{jobq} = \texttt{'I'}`, :math:`\mathrm{q}` is initialized to the unit matrix, and the unitary matrix :math:`Q` is returned.

            If :math:`\mathrm{jobq} = \texttt{'N'}`, :math:`Q` is not computed.

        **k** : int
            :math:`\mathrm{k}` and :math:`\mathrm{l}` specify the sizes, :math:`k` and :math:`l`, of the subblocks of :math:`A` and :math:`B`, whose GSVD is to be computed by ``ztgsja``.

        **l** : int
            :math:`\mathrm{k}` and :math:`\mathrm{l}` specify the sizes, :math:`k` and :math:`l`, of the subblocks of :math:`A` and :math:`B`, whose GSVD is to be computed by ``ztgsja``.

        **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(p, n\right)`
            The :math:`p\times n` matrix :math:`B`.

        **tola** : float
            :math:`\mathrm{tola}` and :math:`\mathrm{tolb}` are the convergence criteria for the Jacobi--Kogbetliantz iteration procedure. Generally, they should be the same as used in the preprocessing step performed by :meth:`zggsvp3`, say

            .. math::
                \begin{array}{c}\mathrm{tola} = \mathrm{max}\left(m, n\right)\left\lVert A\right\rVert \epsilon \text{,}\\\mathrm{tolb} = \mathrm{max}\left(p, n\right)\left\lVert B\right\rVert \epsilon \text{,}\end{array}

            where :math:`\epsilon` is the machine precision.

        **tolb** : float
            :math:`\mathrm{tola}` and :math:`\mathrm{tolb}` are the convergence criteria for the Jacobi--Kogbetliantz iteration procedure. Generally, they should be the same as used in the preprocessing step performed by :meth:`zggsvp3`, say

            .. math::
                \begin{array}{c}\mathrm{tola} = \mathrm{max}\left(m, n\right)\left\lVert A\right\rVert \epsilon \text{,}\\\mathrm{tolb} = \mathrm{max}\left(p, n\right)\left\lVert B\right\rVert \epsilon \text{,}\end{array}

            where :math:`\epsilon` is the machine precision.

        **u** : complex, array-like, shape :math:`\left(:, :\right)`
            Note: the required extent for this argument in dimension 1 is determined as follows: if :math:`\mathrm{jobu}\text{ in } (\texttt{'U'}, \texttt{'I'})`: :math:`m`; otherwise: :math:`1`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{jobu}\text{ in } (\texttt{'U'}, \texttt{'I'})`: :math:`m`; otherwise: :math:`1`.

            If :math:`\mathrm{jobu} = \texttt{'U'}`, :math:`\mathrm{u}` must contain an :math:`m\times m` matrix :math:`U_1` (usually the unitary matrix returned by :meth:`zggsvp3`).

        **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}\text{ in } (\texttt{'V'}, \texttt{'I'})`: :math:`p`; 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{'I'})`: :math:`p`; otherwise: :math:`1`.

            If :math:`\mathrm{jobv} = \texttt{'V'}`, :math:`\mathrm{v}` must contain an :math:`p\times p` matrix :math:`V_1` (usually the unitary matrix returned by :meth:`zggsvp3`).

        **q** : complex, array-like, shape :math:`\left(:, :\right)`
            Note: the required extent for this argument in dimension 1 is determined as follows: if :math:`\mathrm{jobq}\text{ in } (\texttt{'Q'}, \texttt{'I'})`: :math:`n`; otherwise: :math:`1`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{jobq}\text{ in } (\texttt{'Q'}, \texttt{'I'})`: :math:`n`; otherwise: :math:`1`.

            If :math:`\mathrm{jobq} = \texttt{'Q'}`, :math:`\mathrm{q}` must contain an :math:`n\times n` matrix :math:`Q_1` (usually the unitary matrix returned by :meth:`zggsvp3`).

    **Returns**
        **a** : complex, ndarray, shape :math:`\left(m, n\right)`
            If :math:`m-k-l\geq 0`, :math:`\mathrm{a}[0:k+l,n-k-l:n]` contains the :math:`\left(k+l\right)\times \left(k+l\right)` upper triangular matrix :math:`R`.

            If :math:`m-k-l < 0`, :math:`\mathrm{a}[0:m,n-k-l:n]` contains the first :math:`m` rows of the :math:`\left(k+l\right)\times \left(k+l\right)` upper triangular matrix :math:`R`, and the submatrix :math:`R_{33}` is returned in :math:`\mathrm{b}[m-k:l,n+m-k-l:n]`.

        **b** : complex, ndarray, shape :math:`\left(p, n\right)`
            If :math:`m-k-l < 0`, :math:`\mathrm{b}[m-k:l,n+m-k-l:n]` contains the submatrix :math:`R_{33}` of :math:`R`.

        **alpha** : float, ndarray, shape :math:`\left(n\right)`
            See the description of :math:`\mathrm{beta}`.

        **beta** : float, ndarray, shape :math:`\left(n\right)`
            :math:`\mathrm{alpha}` and :math:`\mathrm{beta}` contain the generalized singular value pairs of :math:`A` and :math:`B`;

                :math:`\mathrm{alpha}[\textit{i}] = 1`, :math:`\mathrm{beta}[\textit{i}] = 0`, for :math:`\textit{i} = 0,\ldots,k-1`, and

                if :math:`m-k-l\geq 0`, :math:`\mathrm{alpha}[\textit{i}] = \alpha_{\textit{i}}`, :math:`\mathrm{beta}[\textit{i}] = \beta_{\textit{i}}`, for :math:`\textit{i} = k,\ldots,k+l-1`, or

                if :math:`m-k-l < 0`, :math:`\mathrm{alpha}[\textit{i}] = \alpha_{\textit{i}}`, :math:`\mathrm{beta}[\textit{i}] = \beta_{\textit{i}}`, for :math:`\textit{i} = k,\ldots,m-1` and :math:`\mathrm{alpha}[\textit{i}] = 0`, :math:`\mathrm{beta}[\textit{i}] = 1`, for :math:`\textit{i} = m,\ldots,k+l-1`.

            Furthermore, if :math:`k+l < n`, :math:`\mathrm{alpha}[\textit{i}] = \mathrm{beta}[\textit{i}] = 0`, for :math:`\textit{i} = k+l,\ldots,n-1`.

        **u** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobu} = \texttt{'U'}`, :math:`\mathrm{u}` contains the product :math:`U_1U`.

            If :math:`\mathrm{jobu} = \texttt{'I'}`, :math:`\mathrm{u}` contains the unitary matrix :math:`U`.

            If :math:`\mathrm{jobu} = \texttt{'N'}`, :math:`\mathrm{u}` is not referenced.

        **v** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobv} = \texttt{'I'}`, :math:`\mathrm{v}` contains the unitary matrix :math:`V`.

            If :math:`\mathrm{jobv} = \texttt{'V'}`, :math:`\mathrm{v}` contains the product :math:`V_1V`.

            If :math:`\mathrm{jobv} = \texttt{'N'}`, :math:`\mathrm{v}` is not referenced.

        **q** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{jobq} = \texttt{'I'}`, :math:`\mathrm{q}` contains the unitary matrix :math:`Q`.

            If :math:`\mathrm{jobq} = \texttt{'Q'}`, :math:`\mathrm{q}` contains the product :math:`Q_1Q`.

            If :math:`\mathrm{jobq} = \texttt{'N'}`, :math:`\mathrm{q}` is not referenced.

        **ncycle** : int
            The number of cycles required for convergence.

    .. _f08ys-py2-py-errors:

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

                Constraint: :math:`\mathrm{jobu} = \texttt{'U'}`, :math:`\texttt{'I'}` or :math:`\texttt{'N'}`.

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

                Constraint: :math:`\mathrm{jobv} = \texttt{'V'}`, :math:`\texttt{'I'}` or :math:`\texttt{'N'}`.

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

                Constraint: :math:`\mathrm{jobq} = \texttt{'Q'}`, :math:`\texttt{'I'}` 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{p}`.

                Constraint: :math:`p\geq 0`.

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

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

            (`errno` :math:`1`)
                The procedure does not converge after :math:`40` cycles.

    .. _f08ys-py2-py-notes:

    **Notes**
        ``ztgsja`` computes the GSVD of the matrices :math:`A` and :math:`B` which are assumed to have the form as returned by :meth:`zggsvp3`

        .. math::
            \begin{array}{cc}A = & \left\{\begin{array}{c} \begin{matrix}{}\\k\\l\\m-k-l\end{matrix}\begin{pmatrix}n-k-l&k&l\\0&A_{12}&A_{13}\\0&0&A_{23}\\0&0&0\end{pmatrix} \text{, if } m-k-l \geq 0; \\ \begin{matrix}{}\\k\\m-k\end{matrix}\begin{pmatrix}n-k-l&k&l\\0&A_{12}&A_{13}\\0&0&A_{23}\end{pmatrix} \text{, if } m-k-l < 0 ; \end{array}\right. \\\\B = & \begin{matrix}{}\\l\\p-l\end{matrix}\begin{pmatrix}n-k-l&k&l\\0&0&B_{13}\\0&0&0\end{pmatrix} \text{,} \end{array}

        where the :math:`k\times k` matrix :math:`A_{12}` and the :math:`l\times l` matrix :math:`B_{13}` are nonsingular upper triangular, :math:`A_{23}` is :math:`l\times l` upper triangular if :math:`m-k-l\geq 0` and is :math:`\left(m-k\right)\times l` upper trapezoidal otherwise.

        ``ztgsja`` computes unitary matrices :math:`Q`, :math:`U` and :math:`V`, diagonal matrices :math:`D_1` and :math:`D_2`, and an upper triangular matrix :math:`R` such that

        .. math::
            U^\mathrm{H}AQ = D_1\begin{pmatrix}0&R\end{pmatrix}\text{, }\quad V^\mathrm{H}BQ = D_2\begin{pmatrix}0&R\end{pmatrix}\text{.}

        Optionally :math:`Q`, :math:`U` and :math:`V` may or may not be computed, or they may be premultiplied by matrices :math:`Q_1`, :math:`U_1` and :math:`V_1` respectively.

        If :math:`\left(m-k-l\right)\geq 0` then :math:`D_1`, :math:`D_2` and :math:`R` have the form

        .. math::
            D_1 = \begin{matrix}{}\\k\\l\\m-k-l\end{matrix}\begin{pmatrix}k&l\\I&0\\0&C\\0&0\end{pmatrix}\text{,}

        .. math::
            D_2 = \begin{matrix}{}\\l\\p-l\end{matrix}\begin{pmatrix}k&l\\0&S\\0&0\end{pmatrix}\text{,}

        .. math::
            R = \begin{matrix}{}\\k\\l\end{matrix}\begin{pmatrix}k&l\\R_{11}&R_{12}\\0&R_{22}\end{pmatrix}\text{,}

        where :math:`C = \mathrm{diag}\left(\alpha_{{k+1}},,, \ldots,,, \alpha_{{k+l}}\right)\text{, }\quad S = \mathrm{diag}\left(\beta_{{k+1}},,, \ldots,,, \beta_{{k+l}}\right)`.

        If :math:`\left(m-k-l\right) < 0` then :math:`D_1`, :math:`D_2` and :math:`R` have the form

        .. math::
            D_1 = \begin{matrix}{}\\k\\m-k\end{matrix}\begin{pmatrix}k&m-k&k+l-m\\I&0&0\\0&C&0\end{pmatrix}\text{,}

        .. math::
            D_2 = \begin{matrix}{}\\m-k\\k+l-m\\p-l\end{matrix}\begin{pmatrix}k&m-k&k+l-m\\0&S&0\\0&0&I\\0&0&0\end{pmatrix}\text{,}

        .. math::
            R = \begin{matrix}{}\\k\\m-k\\k+l-m\end{matrix}\begin{pmatrix}k&m-k&k+l-m\\R_{11}&R_{12}&R_{13}\\0&R_{22}&R_{23}\\0&0&R_{33}\end{pmatrix}\text{,}

        where :math:`C = \mathrm{diag}\left(\alpha_{{k+1}},,, \ldots,,, \alpha_m\right)\text{, }\quad S = \mathrm{diag}\left(\beta_{{k+1}},,, \ldots,,, \beta_m\right)`.

        In both cases the diagonal matrix :math:`C` has real non-negative diagonal elements, the diagonal matrix :math:`S` has real positive diagonal elements, so that :math:`S` is nonsingular, and :math:`C^2+S^2 = 1`.
        See Section 2.3.5.3 of Anderson `et al.` (1999) for further information.

    .. _f08ys-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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 ztgexc(wantq, wantz, a, b, q, z, ifst, ilst):
    r"""
    ``ztgexc`` reorders the generalized Schur factorization of a complex matrix pair in generalized Schur form.

    .. _f08yt-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08ytf.html

    .. _f08yt-py2-py-parameters:

    **Parameters**
        **wantq** : bool
            If :math:`\mathrm{wantq} = \mathbf{True}`, update the left transformation matrix :math:`Q`.

            If :math:`\mathrm{wantq} = \mathbf{False}`, do not update :math:`Q`.

        **wantz** : bool
            If :math:`\mathrm{wantz} = \mathbf{True}`, update the right transformation matrix :math:`Z`.

            If :math:`\mathrm{wantz} = \mathbf{False}`, do not update :math:`Z`.

        **a** : complex, array-like, shape :math:`\left(n, n\right)`
            The matrix :math:`S` in the pair :math:`\left(S, T\right)`.

        **b** : complex, array-like, shape :math:`\left(n, n\right)`
            The matrix :math:`T`, in the pair :math:`\left(S, T\right)`.

        **q** : complex, array-like, shape :math:`\left(:, :\right)`
            Note: the required extent for this argument in dimension 1 is determined as follows: if :math:`\mathrm{wantq}= \mathbf{True}`: :math:`n`; otherwise: :math:`1`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{wantq}= \mathbf{True}`: :math:`n`; otherwise: :math:`1`.

            If :math:`\mathrm{wantq} = \mathbf{True}`, the unitary matrix :math:`Q`.

        **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{wantz}= \mathbf{True}`: :math:`n`; otherwise: :math:`1`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{wantz}= \mathbf{True}`: :math:`n`; otherwise: :math:`1`.

            If :math:`\mathrm{wantz} = \mathbf{True}`, the unitary matrix :math:`Z`.

        **ifst** : int
            The indices :math:`i_1` and :math:`i_2` that specify the reordering of the diagonal elements of :math:`\left(S, T\right)`. The element with row index :math:`\mathrm{ifst}` is moved to row :math:`\mathrm{ilst}`, by a sequence of swapping between adjacent diagonal elements.

        **ilst** : int
            The indices :math:`i_1` and :math:`i_2` that specify the reordering of the diagonal elements of :math:`\left(S, T\right)`. The element with row index :math:`\mathrm{ifst}` is moved to row :math:`\mathrm{ilst}`, by a sequence of swapping between adjacent diagonal elements.

    **Returns**
        **a** : complex, ndarray, shape :math:`\left(n, n\right)`
            The updated matrix :math:`\hat{S}`.

        **b** : complex, ndarray, shape :math:`\left(n, n\right)`
            The updated matrix :math:`\hat{T}`

        **q** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{wantq} = \mathbf{True}`, the updated matrix :math:`Q\hat{Q}`.

            If :math:`\mathrm{wantq} = \mathbf{False}`, :math:`\mathrm{q}` is not referenced.

        **z** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{wantz} = \mathbf{True}`, the updated matrix :math:`Z\hat{Z}`.

            If :math:`\mathrm{wantz} = \mathbf{False}`, :math:`\mathrm{z}` is not referenced.

        **ilst** : int
            :math:`\mathrm{ilst}` points to the row in its final position.

    .. _f08yt-py2-py-errors:

    **Raises**
        **NagValueError**
            (`errno` :math:`-3`)
                On entry, error in parameter :math:`\textit{n}`.

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

            (`errno` :math:`-13`)
                On entry, error in parameter :math:`\mathrm{ilst}`.

                Constraint: :math:`1\leq \mathrm{ifst}\leq n` and :math:`1\leq \mathrm{ilst}\leq n`.

            (`errno` :math:`1`)
                The transformed matrix pair would be too far from generalized Schur form; the problem is ill-conditioned. :math:`\left(S, T\right)` may have been partially reordered, and :math:`\mathrm{ilst}` points to the first row of the current position of the block being moved.

    .. _f08yt-py2-py-notes:

    **Notes**
        ``ztgexc`` reorders the generalized complex :math:`n\times n` matrix pair :math:`\left(S, T\right)` in generalized Schur form, so that the diagonal element of :math:`\left(S, T\right)` with row index :math:`i_1` is moved to row :math:`i_2`, using a unitary equivalence transformation.
        That is, :math:`S` and :math:`T` are factorized as

        .. math::
            S = \hat{Q}\hat{S}\hat{Z}^\mathrm{H}\text{, }\quad T = \hat{Q}\hat{T}\hat{Z}^\mathrm{H}\text{,}

        where :math:`\left(\hat{S}, \hat{T}\right)` are also in generalized Schur form.

        The pair :math:`\left(S, T\right)` are in generalized Schur form if :math:`S` and :math:`T` are upper triangular as returned, for example, by :meth:`zgges3`, or :meth:`zhgeqz` with :math:`{\textit{job}} = \texttt{'S'}`.

        If :math:`S` and :math:`T` are the result of a generalized Schur factorization of a matrix pair :math:`\left(A, B\right)`

        .. math::
            A = {QSZ^\mathrm{H}}\text{, }\quad B = {QTZ^\mathrm{H}}

        then, optionally, the matrices :math:`Q` and :math:`Z` can be updated as :math:`Q\hat{Q}` and :math:`Z\hat{Z}`.

    .. _f08yt-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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 ztgsen(ijob, wantq, wantz, select, a, b, q, z):
    r"""
    ``ztgsen`` reorders the generalized Schur factorization of a complex matrix pair in generalized Schur form, so that a selected cluster of eigenvalues appears in the leading elements on the diagonal of the generalized Schur form.
    The function also, optionally, computes the reciprocal condition numbers of the cluster of eigenvalues and/or corresponding deflating subspaces.

    .. _f08yu-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08yuf.html

    .. _f08yu-py2-py-parameters:

    **Parameters**
        **ijob** : int
            Specifies whether condition numbers are required for the cluster of eigenvalues (:math:`p` and :math:`q`) or the deflating subspaces (:math:`\mathrm{Dif}_u` and :math:`\mathrm{Dif}_l`).

            :math:`\mathrm{ijob} = 0`

                Only reorder with respect to :math:`\mathrm{select}`. No extras.

            :math:`\mathrm{ijob} = 1`

                Reciprocal of norms of 'projections' onto left and right eigenspaces with respect to the selected cluster (:math:`p` and :math:`q`).

            :math:`\mathrm{ijob} = 2`

                The upper bounds on :math:`\mathrm{Dif}_u` and :math:`\mathrm{Dif}_l`. :math:`F`-norm-based estimate (:math:`\mathrm{dif}[0:2]`).

            :math:`\mathrm{ijob} = 3`

                Estimate of :math:`\mathrm{Dif}_u` and :math:`\mathrm{Dif}_l`. :math:`1`-norm-based estimate (:math:`\mathrm{dif}[0:2]`). About five times as expensive as :math:`\mathrm{ijob} = 2`.

            :math:`\mathrm{ijob} = 4`

                Compute :math:`\mathrm{pl}`, :math:`\mathrm{pr}` and :math:`\mathrm{dif}` as in :math:`\mathrm{ijob} = 0`, :math:`1` or :math:`2`. Economic version to get it all.

            :math:`\mathrm{ijob} = 5`

                Compute :math:`\mathrm{pl}`, :math:`\mathrm{pr}` and :math:`\mathrm{dif}` as in :math:`\mathrm{ijob} = 0`, :math:`1` or :math:`3`.

        **wantq** : bool
            If :math:`\mathrm{wantq} = \mathbf{True}`, update the left transformation matrix :math:`Q`.

            If :math:`\mathrm{wantq} = \mathbf{False}`, do not update :math:`Q`.

        **wantz** : bool
            If :math:`\mathrm{wantz} = \mathbf{True}`, update the right transformation matrix :math:`Z`.

            If :math:`\mathrm{wantz} = \mathbf{False}`, do not update :math:`Z`.

        **select** : bool, array-like, shape :math:`\left(n\right)`
            Specifies the eigenvalues in the selected cluster. To select an eigenvalue :math:`\lambda_j`, :math:`\mathrm{select}[j-1]` must be set to :math:`\mathbf{True}`.

        **a** : complex, array-like, shape :math:`\left(n, n\right)`
            The matrix :math:`S` in the pair :math:`\left(S, T\right)`.

        **b** : complex, array-like, shape :math:`\left(n, n\right)`
            The matrix :math:`T`, in the pair :math:`\left(S, T\right)`.

        **q** : complex, array-like, shape :math:`\left(:, :\right)`
            Note: the required extent for this argument in dimension 1 is determined as follows: if :math:`\mathrm{wantq}= \mathbf{True}`: :math:`n`; otherwise: :math:`1`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{wantq}= \mathbf{True}`: :math:`n`; otherwise: :math:`1`.

            If :math:`\mathrm{wantq} = \mathbf{True}`, the :math:`n\times n` matrix :math:`Q`.

        **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{wantz}= \mathbf{True}`: :math:`n`; otherwise: :math:`1`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{wantz}= \mathbf{True}`: :math:`n`; otherwise: :math:`1`.

            If :math:`\mathrm{wantz} = \mathbf{True}`, the :math:`n\times n` matrix :math:`Z`.

    **Returns**
        **a** : complex, ndarray, shape :math:`\left(n, n\right)`
            The updated matrix :math:`\hat{S}`.

        **b** : complex, ndarray, shape :math:`\left(n, n\right)`
            The updated matrix :math:`\hat{T}`

        **alpha** : complex, ndarray, shape :math:`\left(n\right)`
            :math:`\mathrm{alpha}` and :math:`\mathrm{beta}` contain diagonal elements of :math:`\hat{S}` and :math:`\hat{T}`, respectively, when the pair :math:`\left(S, T\right)` has been reduced to generalized Schur form. :math:`\mathrm{alpha}[\textit{i}-1]/\mathrm{beta}[\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,n`, are the eigenvalues.

        **beta** : complex, ndarray, shape :math:`\left(n\right)`
            :math:`\mathrm{alpha}` and :math:`\mathrm{beta}` contain diagonal elements of :math:`\hat{S}` and :math:`\hat{T}`, respectively, when the pair :math:`\left(S, T\right)` has been reduced to generalized Schur form. :math:`\mathrm{alpha}[\textit{i}-1]/\mathrm{beta}[\textit{i}-1]`, for :math:`\textit{i} = 1,2,\ldots,n`, are the eigenvalues.

        **q** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{wantq} = \mathbf{True}`, the updated matrix :math:`Q\hat{Q}`.

            If :math:`\mathrm{wantq} = \mathbf{False}`, :math:`\mathrm{q}` is not referenced.

        **z** : complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{wantz} = \mathbf{True}`, the updated matrix :math:`Z\hat{Z}`.

            If :math:`\mathrm{wantz} = \mathbf{False}`, :math:`\mathrm{z}` is not referenced.

        **m** : int
            The dimension of the specified pair of left and right eigenspaces (deflating subspaces), where :math:`\mathrm{m}` will be in the range :math:`0\leq \mathrm{m}\leq n`.

        **pl** : float
            If :math:`\mathrm{ijob} = 1`, :math:`4` or :math:`5`, :math:`\mathrm{pl}` and :math:`\mathrm{pr}` are lower bounds on the reciprocal of the norm of 'projections' :math:`p` and :math:`q` onto left and right eigenspace with respect to the selected cluster. :math:`0 < \mathrm{pl}`, :math:`\mathrm{pr}\leq 1`.

            If :math:`\mathrm{m} = 0` or :math:`\mathrm{m} = n`, :math:`\mathrm{pl} = \mathrm{pr} = 1`.

            If :math:`\mathrm{ijob} = 0`, :math:`2` or :math:`3`, :math:`\mathrm{pl}` and :math:`\mathrm{pr}` are not referenced.

        **pr** : float
            If :math:`\mathrm{ijob} = 1`, :math:`4` or :math:`5`, :math:`\mathrm{pl}` and :math:`\mathrm{pr}` are lower bounds on the reciprocal of the norm of 'projections' :math:`p` and :math:`q` onto left and right eigenspace with respect to the selected cluster. :math:`0 < \mathrm{pl}`, :math:`\mathrm{pr}\leq 1`.

            If :math:`\mathrm{m} = 0` or :math:`\mathrm{m} = n`, :math:`\mathrm{pl} = \mathrm{pr} = 1`.

            If :math:`\mathrm{ijob} = 0`, :math:`2` or :math:`3`, :math:`\mathrm{pl}` and :math:`\mathrm{pr}` are not referenced.

        **dif** : float, ndarray, shape :math:`\left(2\right)`
            If :math:`\mathrm{ijob}\geq 2`, :math:`\mathrm{dif}[0:2]` store the estimates of :math:`\mathrm{Dif}_u` and :math:`\mathrm{Dif}_l`.

            If :math:`\mathrm{ijob} = 2` or :math:`4`, :math:`\mathrm{dif}[0:2]` are :math:`F`-norm-based upper bounds on :math:`\mathrm{Dif}_u` and :math:`\mathrm{Dif}_l`.

            If :math:`\mathrm{ijob} = 3` or :math:`5`, :math:`\mathrm{dif}[0:2]` are :math:`1`-norm-based estimates of :math:`\mathrm{Dif}_u` and :math:`\mathrm{Dif}_l`.

            If :math:`\mathrm{m} = 0` or :math:`n`, :math:`\mathrm{dif}[0:2]` :math:`= \left\lVert \left(A, B\right)\right\rVert_F`.

            If :math:`\mathrm{ijob} = 0` or :math:`1`, :math:`\mathrm{dif}` is not referenced.

    .. _f08yu-py2-py-errors:

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

                Constraint: :math:`0\leq \mathrm{ijob}\leq 5`.

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

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

            (`errno` :math:`1`)
                Reordering of :math:`\left(S, T\right)` failed because the transformed matrix pair would be too far from generalized Schur form; the problem is very ill-conditioned. :math:`\left(S, T\right)` may have been partially reordered. If requested, :math:`0` is returned in :math:`\mathrm{dif}[0]` and :math:`\mathrm{dif}[1]`, :math:`\mathrm{pl}` and :math:`\mathrm{pr}`.

    .. _f08yu-py2-py-notes:

    **Notes**
        ``ztgsen`` factorizes the generalized complex :math:`n\times n` matrix pair :math:`\left(S, T\right)` in generalized Schur form, using a unitary equivalence transformation as

        .. math::
            S = \hat{Q}\hat{S}\hat{Z}^\mathrm{H}\text{, }\quad T = \hat{Q}\hat{T}\hat{Z}^\mathrm{H}\text{,}

        where :math:`\left(\hat{S}, \hat{T}\right)` are also in generalized Schur form and have the selected eigenvalues as the leading diagonal elements.
        The leading columns of :math:`Q` and :math:`Z` are the generalized Schur vectors corresponding to the selected eigenvalues and form orthonormal subspaces for the left and right eigenspaces (deflating subspaces) of the pair :math:`\left(S, T\right)`.

        The pair :math:`\left(S, T\right)` are in generalized Schur form if :math:`S` and :math:`T` are upper triangular as returned, for example, by :meth:`zgges3`, or :meth:`zhgeqz` with :math:`{\textit{job}} = \texttt{'S'}`.
        The diagonal elements define the generalized eigenvalues :math:`\left(\alpha_{\textit{i}}, \beta_{\textit{i}}\right)`, for :math:`\textit{i} = 1,2,\ldots,n`, of the pair :math:`\left(S, T\right)`.
        The eigenvalues are given by

        .. math::
            \lambda_i = \alpha_i/\beta_i\text{,}

        but are returned as the pair :math:`\left(\alpha_i, \beta_i\right)` in order to avoid possible overflow in computing :math:`\lambda_i`.
        Optionally, the function returns reciprocals of condition number estimates for the selected eigenvalue cluster, :math:`p` and :math:`q`, the right and left projection norms, and of deflating subspaces, :math:`\mathrm{Dif}_u` and :math:`\mathrm{Dif}_l`.
        For more information see Sections 2.4.8 and 4.11 of Anderson `et al.` (1999).

        If :math:`S` and :math:`T` are the result of a generalized Schur factorization of a matrix pair :math:`\left(A, B\right)`

        .. math::
            A = {QSZ^\mathrm{H}}\text{, }\quad B = {QTZ^\mathrm{H}}

        then, optionally, the matrices :math:`Q` and :math:`Z` can be updated as :math:`Q\hat{Q}` and :math:`Z\hat{Z}`.
        Note that the condition numbers of the pair :math:`\left(S, T\right)` are the same as those of the pair :math:`\left(A, B\right)`.

    .. _f08yu-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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 ztgsyl(trans, ijob, a, b, c, d, e, f):
    r"""
    ``ztgsyl`` solves the generalized complex triangular Sylvester equations.

    .. _f08yv-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08yvf.html

    .. _f08yv-py2-py-parameters:

    **Parameters**
        **trans** : str, length 1
            If :math:`\mathrm{trans} = \texttt{'N'}`, solve the generalized Sylvester equation `(1) <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08yvf.html#eqn1>`__.

            If :math:`\mathrm{trans} = \texttt{'C'}`, solve the 'conjugate transposed' system `(2) <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08yvf.html#eqn2>`__.

        **ijob** : int
            Specifies what kind of functionality is to be performed when :math:`\mathrm{trans} = \texttt{'N'}`.

            :math:`\mathrm{ijob} = 0`

                Solve `(1) <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08yvf.html#eqn1>`__ only.

            :math:`\mathrm{ijob} = 1`

                The functionality of :math:`\mathrm{ijob} = 0` or :math:`3`.

            :math:`\mathrm{ijob} = 2`

                The functionality of :math:`\mathrm{ijob} = 0` or :math:`4`.

            :math:`\mathrm{ijob} = 3`

                Only an estimate of :math:`\textit{Dif}\left[\left(A, D\right), \left(B, E\right)\right]` is computed based on the Frobenius norm.

            :math:`\mathrm{ijob} = 4`

                Only an estimate of :math:`\textit{Dif}\left[\left(A, D\right), \left(B, E\right)\right]` is computed based on the :math:`1`-norm.

            If :math:`\mathrm{trans} = \texttt{'C'}`, :math:`\mathrm{ijob}` is not referenced.

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

        **b** : complex, array-like, shape :math:`\left(n, n\right)`
            The upper triangular matrix :math:`B`.

        **c** : complex, array-like, shape :math:`\left(m, n\right)`
            Contains the right-hand-side matrix :math:`C`.

        **d** : complex, array-like, shape :math:`\left(m, m\right)`
            The upper triangular matrix :math:`D`.

        **e** : complex, array-like, shape :math:`\left(n, n\right)`
            The upper triangular matrix :math:`E`.

        **f** : complex, array-like, shape :math:`\left(m, n\right)`
            Contains the right-hand side matrix :math:`F`.

    **Returns**
        **c** : complex, ndarray, shape :math:`\left(m, n\right)`
            If :math:`\mathrm{ijob} = 0`, :math:`1` or :math:`2`, :math:`\mathrm{c}` is overwritten by the solution matrix :math:`R`.

            If :math:`\mathrm{trans} = \texttt{'N'}` and :math:`\mathrm{ijob} = 3` or :math:`4`, :math:`\mathrm{c}` holds :math:`R`, the solution achieved during the computation of the Dif estimate.

        **f** : complex, ndarray, shape :math:`\left(m, n\right)`
            If :math:`\mathrm{ijob} = 0`, :math:`1` or :math:`2`, :math:`\mathrm{f}` is overwritten by the solution matrix :math:`L`.

            If :math:`\mathrm{trans} = \texttt{'N'}` and :math:`\mathrm{ijob} = 3` or :math:`4`, :math:`\mathrm{f}` holds :math:`L`, the solution achieved during the computation of the Dif estimate.

        **scale** : float
            :math:`\alpha`, the scaling factor in `(1) <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08yvf.html#eqn1>`__ and `(2) <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08yvf.html#eqn1>`__.

            If :math:`0 < \mathrm{scale} < 1`, :math:`\mathrm{c}` and :math:`\mathrm{f}` hold the solutions :math:`R` and :math:`L`, respectively, to a slightly perturbed system but the input arrays :math:`\mathrm{a}`, :math:`\mathrm{b}`, :math:`\mathrm{d}` and :math:`\mathrm{e}` have not been changed.

            If :math:`\mathrm{scale} = 0`, :math:`\mathrm{c}` and :math:`\mathrm{f}` hold the solutions :math:`R` and :math:`L`, respectively, to the homogeneous system with :math:`C = F = 0`.

            In this case :math:`\mathrm{dif}` is not referenced.

            Normally, :math:`\mathrm{scale} = 1`.

        **dif** : float
            The estimate of :math:`\mathrm{Dif}`. If :math:`\mathrm{ijob} = 0`, :math:`\mathrm{dif}` is not referenced.

    .. _f08yv-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:`\mathrm{ijob}`.

                Constraint: :math:`0\leq \mathrm{ijob}\leq 4`.

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

                Constraint: :math:`m > 0`.

            (`errno` :math:`-4`)
                On entry, error in parameter :math:`\textit{n}`.

                Constraint: :math:`n > 0`.

            (`errno` :math:`i > 0`)
                :math:`\left(A, D\right)` and :math:`\left(B, E\right)` have common or close eigenvalues and so no solution could be computed.

    .. _f08yv-py2-py-notes:

    **Notes**
        ``ztgsyl`` solves either the generalized complex Sylvester equations

        .. math::
            \begin{array}{cc}AR-LB& = \alpha C\\DR-LE& = \alpha F\text{,}\end{array}

        or the equations

        .. math::
            \begin{array}{cc}A^\mathrm{H}R+D^\mathrm{H}L& = \alpha C\\RB^\mathrm{H}+LE^\mathrm{H}& = {-\alpha }F\text{,}\end{array}

        where the pair :math:`\left(A, D\right)` are given :math:`m\times m` matrices in generalized Schur form, :math:`\left(B, E\right)` are given :math:`n\times n` matrices in generalized Schur form and :math:`\left(C, F\right)` are given :math:`m\times n` matrices.
        The pair :math:`\left(R, L\right)` are the :math:`m\times n` solution matrices, and :math:`\alpha` is an output scaling factor determined by the function to avoid overflow in computing :math:`\left(R, L\right)`.

        Equations `(1) <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08yvf.html#eqn1>`__ are equivalent to equations of the form

        .. math::
            Zx = \alpha b\text{,}

        where

        .. math::
            Z = \begin{pmatrix}I⊗A-B^\mathrm{H}⊗I\\I⊗D-E^\mathrm{H}⊗I\end{pmatrix}

        and :math:`⊗` is the Kronecker product.
        Equations `(2) <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08yvf.html#eqn2>`__ are then equivalent to

        .. math::
            Z^\mathrm{H}y = \alpha b\text{.}

        The pair :math:`\left(S, T\right)` are in generalized Schur form if :math:`S` and :math:`T` are upper triangular as returned, for example, by :meth:`zgges3`, or :meth:`zhgeqz` with :math:`{\textit{job}} = \texttt{'S'}`.

        Optionally, the function estimates :math:`\mathrm{Dif}\left[\left(A, D\right), \left(B, E\right)\right]`, the separation between the matrix pairs :math:`\left(A, D\right)` and :math:`\left(B, E\right)`, which is the smallest singular value of :math:`Z`.
        The estimate can be based on either the Frobenius norm, or the :math:`1`-norm.
        The :math:`1`-norm estimate can be three to ten times more expensive than the Frobenius norm estimate, but makes the condition estimation uniform with the nonsymmetric eigenproblem.
        The Frobenius norm estimate provides a low cost, but equally reliable estimate.
        For more information see Sections 2.4.8.3 and 4.11.1.3 of Anderson `et al.` (1999) and Kågström and Poromaa (1996).

    .. _f08yv-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug

        Kågström, B, 1994, `A perturbation analysis of the generalized Sylvester equation` :math:`\left({AR-LB}, {DR-LE}\right) = \left(c, F\right)`, SIAM J. Matrix Anal. Appl. (15), 1045--1060

        Kågström, B and Poromaa, P, 1996, `LAPACK-style algorithms and software for solving the generalized Sylvester equation and estimating the separation between regular matrix pairs`, ACM Trans. Math. Software (22), 78--103
    """
    raise NotImplementedError

def ztgevc(side, howmny, a, b, select=None, vl=None, vr=None):
    r"""
    ``ztgevc`` computes some or all of the right and/or left generalized eigenvectors of a pair of complex upper triangular matrices :math:`\left(A, B\right)`.

    .. _f08yx-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08yxf.html

    .. _f08yx-py2-py-parameters:

    **Parameters**
        **side** : str, length 1
            Specifies the required sets of generalized eigenvectors.

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

                Only right eigenvectors are computed.

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

                Only left eigenvectors are computed.

            :math:`\mathrm{side} = \texttt{'B'}`

                Both left and right eigenvectors are computed.

        **howmny** : str, length 1
            Specifies further details of the required generalized eigenvectors.

            :math:`\mathrm{howmny} = \texttt{'A'}`

                All right and/or left eigenvectors are computed.

            :math:`\mathrm{howmny} = \texttt{'B'}`

                All right and/or left eigenvectors are computed; they are backtransformed using the input matrices supplied in arrays :math:`\mathrm{vr}` and/or :math:`\mathrm{vl}`.

            :math:`\mathrm{howmny} = \texttt{'S'}`

                Selected right and/or left eigenvectors, defined by the array :math:`\mathrm{select}`, are computed.

        **a** : complex, array-like, shape :math:`\left(n, n\right)`
            The matrix :math:`A` must be in upper triangular form. Usually, this is the matrix :math:`A` returned by :meth:`zhgeqz`.

        **b** : complex, array-like, shape :math:`\left(n, n\right)`
            The matrix :math:`B` must be in upper triangular form with non-negative real diagonal elements. Usually, this is the matrix :math:`B` returned by :meth:`zhgeqz`.

        **select** : None or bool, array-like, shape :math:`\left(:\right)`, optional
            Note: the required length for this argument is determined as follows: if :math:`\mathrm{howmny}=\texttt{'S'}`: :math:`n`; otherwise: :math:`1`.

            Specifies the eigenvectors to be computed if :math:`\mathrm{howmny} = \texttt{'S'}`. To select the generalized eigenvector corresponding to the :math:`j`\ th generalized eigenvalue, the :math:`j`\ th element of :math:`\mathrm{select}` should be set to :math:`\mathbf{True}`.

        **vl** : 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{side}\text{ in } (\texttt{'L'}, \texttt{'B'})`: :math:`n`; if :math:`\mathrm{side}=\texttt{'R'}`: :math:`1`; otherwise: :math:`0`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{side}\text{ in } (\texttt{'L'}, \texttt{'B'})`: :math:`\textit{mm}`; if :math:`\mathrm{side}=\texttt{'R'}`: :math:`1`; otherwise: :math:`0`.

            If :math:`\mathrm{howmny} = \texttt{'B'}` and :math:`\mathrm{side} = \texttt{'L'}` or :math:`\texttt{'B'}`, :math:`\mathrm{vl}` must be initialized to an :math:`n\times n` matrix :math:`Q`. Usually, this is the unitary matrix :math:`Q` of left Schur vectors returned by :meth:`zhgeqz`.

        **vr** : 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{side}\text{ in } (\texttt{'R'}, \texttt{'B'})`: :math:`n`; if :math:`\mathrm{side}=\texttt{'L'}`: :math:`1`; otherwise: :math:`0`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{side}\text{ in } (\texttt{'R'}, \texttt{'B'})`: :math:`\textit{mm}`; if :math:`\mathrm{side}=\texttt{'L'}`: :math:`1`; otherwise: :math:`0`.

            If :math:`\mathrm{howmny} = \texttt{'B'}` and :math:`\mathrm{side} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{vr}` must be initialized to an :math:`n\times n` matrix :math:`Z`. Usually, this is the unitary matrix :math:`Z` of right Schur vectors returned by :meth:`dhgeqz`.

    **Returns**
        **vl** : None or complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{side} = \texttt{'L'}` or :math:`\texttt{'B'}`, :math:`\mathrm{vl}` contains:

                if :math:`\mathrm{howmny} = \texttt{'A'}`, the matrix :math:`Y` of left eigenvectors of :math:`\left(A, B\right)`;

                if :math:`\mathrm{howmny} = \texttt{'B'}`, the matrix :math:`QY`;

                if :math:`\mathrm{howmny} = \texttt{'S'}`, the left eigenvectors of :math:`\left(A, B\right)` specified by :math:`\mathrm{select}`, stored consecutively in the columns of the array :math:`\mathrm{vl}`, in the same order as their corresponding eigenvalues.

        **vr** : None or complex, ndarray, shape :math:`\left(:, :\right)`
            If :math:`\mathrm{side} = \texttt{'R'}` or :math:`\texttt{'B'}`, :math:`\mathrm{vr}` contains:

                if :math:`\mathrm{howmny} = \texttt{'A'}`, the matrix :math:`X` of right eigenvectors of :math:`\left(A, B\right)`;

                if :math:`\mathrm{howmny} = \texttt{'B'}`, the matrix :math:`ZX`;

                if :math:`\mathrm{howmny} = \texttt{'S'}`, the right eigenvectors of :math:`\left(A, B\right)` specified by :math:`\mathrm{select}`, stored consecutively in the columns of the array :math:`\mathrm{vr}`, in the same order as their corresponding eigenvalues.

        **m** : int
            The number of columns in the arrays :math:`\mathrm{vl}` and/or :math:`\mathrm{vr}` actually used to store the eigenvectors. If :math:`\mathrm{howmny} = \texttt{'A'}` or :math:`\texttt{'B'}`, :math:`\mathrm{m}` is set to :math:`\textit{n}`. Each selected eigenvector occupies one column.

    .. _f08yx-py2-py-errors:

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

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

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

                Constraint: :math:`\mathrm{howmny} = \texttt{'A'}`, :math:`\texttt{'B'}` or :math:`\texttt{'S'}`.

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

                Constraint: :math:`\mathrm{select}[\textit{j}] = \mathbf{True}` or :math:`\mathbf{False}`, for :math:`\textit{j} = 0,\ldots,n-1`.

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

            (`errno` :math:`-13`)
                On entry, error in parameter :math:`\textit{mm}`.

    .. _f08yx-py2-py-notes:

    **Notes**
        ``ztgevc`` computes some or all of the right and/or left generalized eigenvectors of the matrix pair :math:`\left(A, B\right)` which is assumed to be in upper triangular form.
        If the matrix pair :math:`\left(A, B\right)` is not upper triangular then the function :meth:`zhgeqz` should be called before invoking ``ztgevc``.

        The right generalized eigenvector :math:`x` and the left generalized eigenvector :math:`y` of :math:`\left(A, B\right)` corresponding to a generalized eigenvalue :math:`\lambda` are defined by

        .. math::
            \left(A-\lambda B\right)x = 0

        and

        .. math::
            y^\mathrm{H}\left(A-\lambda B\right) = 0\text{.}

        If a generalized eigenvalue is determined as :math:`0/0`, which is due to zero diagonal elements at the same locations in both :math:`A` and :math:`B`, a unit vector is returned as the corresponding eigenvector.

        Note that the generalized eigenvalues are computed using :meth:`zhgeqz` but ``ztgevc`` does not explicitly require the generalized eigenvalues to compute eigenvectors.
        The ordering of the eigenvectors is based on the ordering of the eigenvalues as computed by ``ztgevc``.

        If all eigenvectors are requested, the function may either return the matrices :math:`X` and/or :math:`Y` of right or left eigenvectors of :math:`\left(A, B\right)`, or the products :math:`ZX` and/or :math:`QY`, where :math:`Z` and :math:`Q` are two matrices supplied by you.
        Usually, :math:`Q` and :math:`Z` are chosen as the unitary matrices returned by :meth:`zhgeqz`.
        Equivalently, :math:`Q` and :math:`Z` are the left and right Schur vectors of the matrix pair supplied to :meth:`zhgeqz`.
        In that case, :math:`QY` and :math:`ZX` are the left and right generalized eigenvectors, respectively, of the matrix pair supplied to :meth:`zhgeqz`.

    .. _f08yx-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia

        Golub, G H and Van Loan, C F, 1996, `Matrix Computations`, (3rd Edition), Johns Hopkins University Press, Baltimore

        Moler, C B and Stewart, G W, 1973, `An algorithm for generalized matrix eigenproblems`, SIAM J. Numer. Anal. (10), 241--256

        Stewart, G W and Sun, J-G, 1990, `Matrix Perturbation Theory`, Academic Press, London
    """
    raise NotImplementedError

def ztgsna(job, howmny, a, b, mm, select=None, vl=None, vr=None):
    r"""
    ``ztgsna`` estimates condition numbers for specified eigenvalues and/or eigenvectors of a complex matrix pair in generalized Schur form.

    .. _f08yy-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08yyf.html

    .. _f08yy-py2-py-parameters:

    **Parameters**
        **job** : str, length 1
            Indicates whether condition numbers are required for eigenvalues and/or eigenvectors.

            :math:`\mathrm{job} = \texttt{'E'}`

                Condition numbers for eigenvalues only are computed.

            :math:`\mathrm{job} = \texttt{'V'}`

                Condition numbers for eigenvectors only are computed.

            :math:`\mathrm{job} = \texttt{'B'}`

                Condition numbers for both eigenvalues and eigenvectors are computed.

        **howmny** : str, length 1
            Indicates how many condition numbers are to be computed.

            :math:`\mathrm{howmny} = \texttt{'A'}`

                Condition numbers for all eigenpairs are computed.

            :math:`\mathrm{howmny} = \texttt{'S'}`

                Condition numbers for selected eigenpairs (as specified by :math:`\mathrm{select}`) are computed.

        **a** : complex, array-like, shape :math:`\left(n, n\right)`
            The upper triangular matrix :math:`S`.

        **b** : complex, array-like, shape :math:`\left(n, n\right)`
            The upper triangular matrix :math:`T`.

        **mm** : int
            The number of elements in the arrays :math:`\mathrm{s}` and :math:`\mathrm{dif}`.

        **select** : None or bool, array-like, shape :math:`\left(:\right)`, optional
            Note: the required length for this argument is determined as follows: if :math:`\mathrm{howmny}=\texttt{'S'}`: :math:`n`; otherwise: :math:`1`.

            Specifies the eigenpairs for which condition numbers are to be computed if :math:`\mathrm{howmny} = \texttt{'S'}`. To select condition numbers for the eigenpair corresponding to the eigenvalue :math:`\lambda_j`, :math:`\mathrm{select}[j-1]` must be set to :math:`\mathbf{True}`.

            If :math:`\mathrm{howmny} = \texttt{'A'}`, :math:`\mathrm{select}` is not referenced.

        **vl** : 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{job}\text{ in } (\texttt{'E'}, \texttt{'B'})`: :math:`n`; otherwise: :math:`1`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{job}\text{ in } (\texttt{'E'}, \texttt{'B'})`: :math:`\mathrm{mm}`; otherwise: :math:`0`.

            If :math:`\mathrm{job} = \texttt{'E'}` or :math:`\texttt{'B'}`, :math:`\mathrm{vl}` must contain left eigenvectors of :math:`\left(S, T\right)`, corresponding to the eigenpairs specified by :math:`\mathrm{howmny}` and :math:`\mathrm{select}`. The eigenvectors must be stored in consecutive columns of :math:`\mathrm{vl}`, as returned by :meth:`zggev3` or :meth:`ztgevc`.

            If :math:`\mathrm{job} = \texttt{'V'}`, :math:`\mathrm{vl}` is not referenced.

        **vr** : 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{job}\text{ in } (\texttt{'E'}, \texttt{'B'})`: :math:`n`; otherwise: :math:`1`.

            Note: the required extent for this argument in dimension 2 is determined as follows: if :math:`\mathrm{job}\text{ in } (\texttt{'E'}, \texttt{'B'})`: :math:`\mathrm{mm}`; otherwise: :math:`0`.

            If :math:`\mathrm{job} = \texttt{'E'}` or :math:`\texttt{'B'}`, :math:`\mathrm{vr}` must contain right eigenvectors of :math:`\left(S, T\right)`, corresponding to the eigenpairs specified by :math:`\mathrm{howmny}` and :math:`\mathrm{select}`. The eigenvectors must be stored in consecutive columns of :math:`\mathrm{vr}`, as returned by :meth:`zggev3` or :meth:`ztgevc`.

            If :math:`\mathrm{job} = \texttt{'V'}`, :math:`\mathrm{vr}` is not referenced.

    **Returns**
        **s** : float, ndarray, shape :math:`\left(:\right)`
            If :math:`\mathrm{job} = \texttt{'E'}` or :math:`\texttt{'B'}`, the reciprocal condition numbers of the selected eigenvalues, stored in consecutive elements of the array.

            If :math:`\mathrm{job} = \texttt{'V'}`, :math:`\mathrm{s}` is not referenced.

        **dif** : float, ndarray, shape :math:`\left(:\right)`
            If :math:`\mathrm{job} = \texttt{'V'}` or :math:`\texttt{'B'}`, the estimated reciprocal condition numbers of the selected eigenvectors, stored in consecutive elements of the array. If the eigenvalues cannot be reordered to compute :math:`\mathrm{dif}[j-1]`, :math:`\mathrm{dif}[j-1]` is set to :math:`0`; this can only occur when the true value would be very small anyway.

            If :math:`\mathrm{job} = \texttt{'E'}`, :math:`\mathrm{dif}` is not referenced.

        **m** : int
            The number of elements of the arrays :math:`\mathrm{s}` and :math:`\mathrm{dif}` used to store the specified condition numbers; for each selected eigenvalue one element is used.

            If :math:`\mathrm{howmny} = \texttt{'A'}`, :math:`\mathrm{m}` is set to :math:`\textit{n}`.

    .. _f08yy-py2-py-errors:

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

                Constraint: :math:`\mathrm{job} = \texttt{'E'}`, :math:`\texttt{'V'}` or :math:`\texttt{'B'}`.

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

                Constraint: :math:`\mathrm{howmny} = \texttt{'A'}` or :math:`\texttt{'S'}`.

            (`errno` :math:`-4`)
                On entry, error in parameter :math:`\textit{n}`.

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

            (`errno` :math:`-15`)
                On entry, error in parameter :math:`\mathrm{mm}`.

                Constraint: :math:`\mathrm{mm}\geq n`.

            (`errno` :math:`-15`)
                On entry, error in parameter :math:`\mathrm{mm}`.

                Constraint: :math:`\mathrm{mm}\geq \text{ the number of selected eigenvalues}`.

    .. _f08yy-py2-py-notes:

    **Notes**
        ``ztgsna`` estimates condition numbers for specified eigenvalues and/or right eigenvectors of an :math:`n\times n` matrix pair :math:`\left(S, T\right)` in generalized Schur form.
        The function actually returns estimates of the reciprocals of the condition numbers in order to avoid possible overflow.

        The pair :math:`\left(S, T\right)` are in generalized Schur form if :math:`S` and :math:`T` are upper triangular as returned, for example, by :meth:`zgges3` or :meth:`zggesx`, or :meth:`zhgeqz` with :math:`{\textit{job}} = \texttt{'S'}`.
        The diagonal elements define the generalized eigenvalues :math:`\left(\alpha_{\textit{i}}, \beta_{\textit{i}}\right)`, for :math:`\textit{i} = 1,2,\ldots,n`, of the pair :math:`\left(S, T\right)` and the eigenvalues are given by

        .. math::
            \lambda_i = \alpha_i/\beta_i\text{,}

        so that

        .. math::
            \beta_iSx_i = \alpha_iTx_i\quad \text{ or }\quad Sx_i = \lambda_iTx_i\text{,}

        where :math:`x_i` is the corresponding (right) eigenvector.

        If :math:`S` and :math:`T` are the result of a generalized Schur factorization of a matrix pair :math:`\left(A, B\right)`

        .. math::
            A = {QSZ^\mathrm{H}}\text{, }\quad B = {QTZ^\mathrm{H}}

        then the eigenvalues and condition numbers of the pair :math:`\left(S, T\right)` are the same as those of the pair :math:`\left(A, B\right)`.

        Let :math:`\left(\alpha, \beta \right)\neq \left(0, 0\right)` be a simple generalized eigenvalue of :math:`\left(A, B\right)`.
        Then the reciprocal of the condition number of the eigenvalue :math:`\lambda = \alpha /\beta` is defined as

        .. math::
            s\left(\lambda \right) = \frac{\left(\left\lvert y^\mathrm{H}Ax\right\rvert^2+\left\lvert y^\mathrm{H}Bx\right\rvert^2\right)^{{1/2}}}{\left(\left\lVert x\right\rVert_2\left\lVert y\right\rVert_2\right)}\text{,}

        where :math:`x` and :math:`y` are the right and left eigenvectors of :math:`\left(A, B\right)` corresponding to :math:`\lambda`.
        If both :math:`\alpha` and :math:`\beta` are zero, then :math:`\left(A, B\right)` is singular and :math:`s\left(\lambda \right) = -1` is returned.

        If :math:`U` and :math:`V` are unitary transformations such that

        .. math::
            U^\mathrm{H}\left(A, B\right)V = \left(S, T\right) = \begin{pmatrix}\alpha &*\\0&S_{22}\end{pmatrix}\begin{pmatrix}\beta &*\\0&T_{22}\end{pmatrix}\text{,}

        where :math:`S_{22}` and :math:`T_{22}` are :math:`\left(n-1\right)\times \left(n-1\right)` matrices, then the reciprocal condition number is given by

        .. math::
            \mathrm{Dif}\left(x\right)\equiv \mathrm{Dif}\left(y\right) = \mathrm{Dif}\left(\left(\alpha, \beta \right), \left(S_{22}, T_{22}\right)\right) = \sigma_{\mathrm{min}}\left(Z\right)\text{,}

        where :math:`\sigma_{\mathrm{min}}\left(Z\right)` denotes the smallest singular value of the :math:`2\left(n-1\right)\times 2\left(n-1\right)` matrix

        .. math::
            Z = \begin{pmatrix}\alpha ⊗I&-1⊗S_{22}\\\beta ⊗I&-1⊗T_{22}\end{pmatrix}

        and :math:`⊗` is the Kronecker product.

        See Sections 2.4.8 and 4.11 of Anderson `et al.` (1999) and Kågström and Poromaa (1996) for further details and information.

    .. _f08yy-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug

        Kågström, B and Poromaa, P, 1996, `LAPACK-style algorithms and software for solving the generalized Sylvester equation and estimating the separation between regular matrix pairs`, ACM Trans. Math. Software (22), 78--103
    """
    raise NotImplementedError

def dgglse(n, a, b, c, d):
    r"""
    ``dgglse`` solves a real linear equality-constrained least squares problem.

    .. _f08za-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08zaf.html

    .. _f08za-py2-py-parameters:

    **Parameters**
        **n** : int
            :math:`n`, the number of columns of the matrices :math:`A` and :math:`B`.

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

        **b** : float, array-like, shape :math:`\left(p, \mathrm{n}\right)`
            The :math:`p\times n` matrix :math:`B`.

        **c** : float, array-like, shape :math:`\left(m\right)`
            The right-hand side vector :math:`c` for the least squares part of the LSE problem.

        **d** : float, array-like, shape :math:`\left(p\right)`
            The right-hand side vector :math:`d` for the equality constraints.

    **Returns**
        **a** : float, ndarray, shape :math:`\left(m, \mathrm{n}\right)`
            :math:`\mathrm{a}` is overwritten.

        **b** : float, ndarray, shape :math:`\left(p, \mathrm{n}\right)`
            :math:`\mathrm{b}` is overwritten.

        **c** : float, ndarray, shape :math:`\left(m\right)`
            The residual sum of squares for the solution vector :math:`x` is given by the sum of squares of elements :math:`\mathrm{c}[\mathrm{n}-p],\mathrm{c}[\mathrm{n}-p+1],\ldots,\mathrm{c}[m-1]`; the remaining elements are overwritten.

        **d** : float, ndarray, shape :math:`\left(p\right)`
            :math:`\mathrm{d}` is overwritten.

        **x** : float, ndarray, shape :math:`\left(\mathrm{n}\right)`
            The solution vector :math:`x` of the LSE problem.

    .. _f08za-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:`\mathrm{n}`.

                Constraint: :math:`\mathrm{n}\geq 0`.

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

                Constraint: :math:`0\leq p\leq \mathrm{n}\leq m+p`.

            (`errno` :math:`1`)
                The upper triangular factor :math:`R` associated with :math:`B` in the generalized :math:`RQ` factorization of the pair :math:`\left(B, A\right)` is singular, so that :math:`\mathrm{rank}\left(B\right) < p`; the least squares solution could not be computed.

            (`errno` :math:`2`)
                The :math:`\left(N-P\right)\times \left(N-P\right)` part of the upper trapezoidal factor :math:`T` associated with :math:`A` in the generalized :math:`RQ` factorization of the pair :math:`\left(B, A\right)` is singular, so that the rank of the matrix (:math:`E`) comprising the rows of :math:`A` and :math:`B` is less than :math:`n`; the least squares solutions could not be computed.

    .. _f08za-py2-py-notes:

    **Notes**
        ``dgglse`` solves the real linear equality-constrained least squares (LSE) problem

        .. math::
            \mathrm{minimize}_x\left\lVert c-Ax\right\rVert_2\quad \text{ subject to }\quad Bx = d

        where :math:`A` is an :math:`m\times n` matrix, :math:`B` is a :math:`p\times n` matrix, :math:`c` is an :math:`m` element vector and :math:`d` is a :math:`p` element vector.
        It is assumed that :math:`p\leq n\leq m+p`, :math:`\mathrm{rank}\left(B\right) = p` and :math:`\mathrm{rank}\left(E\right) = n`, where :math:`E = \begin{pmatrix}A\\B\end{pmatrix}`.
        These conditions ensure that the LSE problem has a unique solution, which is obtained using a generalized :math:`RQ` factorization of the matrices :math:`B` and :math:`A`.

    .. _f08za-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia

        Anderson, E, Bai, Z and Dongarra, J, 1992, `Generalized` :math:`QR` `factorization and its applications`, Linear Algebra Appl. (Volume 162--164), 243--271

        Eldèn, L, 1980, `Perturbation theory for the least squares problem with linear equality constraints`, SIAM J. Numer. Anal. (17), 338--350
    """
    raise NotImplementedError

def dggglm(p, a, b, d):
    r"""
    ``dggglm`` solves a real general Gauss--Markov linear (least squares) model problem.

    .. _f08zb-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08zbf.html

    .. _f08zb-py2-py-parameters:

    **Parameters**
        **p** : int
            :math:`p`, the number of columns of the matrix :math:`B`.

        **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(m, \mathrm{p}\right)`
            The :math:`m\times p` matrix :math:`B`.

        **d** : float, array-like, shape :math:`\left(m\right)`
            The left-hand side vector :math:`d` of the GLM equation.

    **Returns**
        **a** : float, ndarray, shape :math:`\left(m, n\right)`
            :math:`\mathrm{a}` is overwritten.

        **b** : float, ndarray, shape :math:`\left(m, \mathrm{p}\right)`
            :math:`\mathrm{b}` is overwritten.

        **d** : float, ndarray, shape :math:`\left(m\right)`
            :math:`\mathrm{d}` is overwritten.

        **x** : float, ndarray, shape :math:`\left(n\right)`
            The solution vector :math:`x` of the GLM problem.

        **y** : float, ndarray, shape :math:`\left(\mathrm{p}\right)`
            The solution vector :math:`y` of the GLM problem.

    .. _f08zb-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:`0\leq n\leq m`.

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

                Constraint: :math:`\mathrm{p}\geq m-n`.

            (`errno` :math:`1`)
                The upper triangular factor :math:`R` associated with :math:`A` in the generalized :math:`RQ` factorization of the pair :math:`\left(A, B\right)` is singular, so that :math:`\mathrm{rank}\left(A\right) < n`; the least squares solution could not be computed.

            (`errno` :math:`2`)
                The bottom :math:`\left(m-n\right)\times \left(m-n\right)` part of the upper trapezoidal factor :math:`T` associated with :math:`B` in the generalized :math:`QR` factorization of the pair :math:`\left(A, B\right)` is singular, so that :math:`\mathrm{rank}\begin{pmatrix}A&B\end{pmatrix} < n`; the least squares solutions could not be computed.

    .. _f08zb-py2-py-notes:

    **Notes**
        ``dggglm`` solves the real general Gauss--Markov linear model (GLM) problem

        .. math::
            \mathrm{minimize}_x\left\lVert y\right\rVert_2\quad \text{ subject to }\quad d = Ax+By

        where :math:`A` is an :math:`m\times n` matrix, :math:`B` is an :math:`m\times p` matrix and :math:`d` is an :math:`m` element vector.
        It is assumed that :math:`n\leq m\leq n+p`, :math:`\mathrm{rank}\left(A\right) = n` and :math:`\mathrm{rank}\left(E\right) = m`, where :math:`E = \begin{pmatrix}A&B\end{pmatrix}`.
        Under these assumptions, the problem has a unique solution :math:`x` and a minimal :math:`2`-norm solution :math:`y`, which is obtained using a generalized :math:`QR` factorization of the matrices :math:`A` and :math:`B`.

        In particular, if the matrix :math:`B` is square and nonsingular, then the GLM problem is equivalent to the weighted linear least squares problem

        .. math::
            \mathrm{minimize}_x\left\lVert B^{-1}\left(d-Ax\right)\right\rVert_2\text{.}

    .. _f08zb-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia

        Anderson, E, Bai, Z and Dongarra, J, 1992, `Generalized` :math:`QR` `factorization and its applications`, Linear Algebra Appl. (Volume 162--164), 243--271
    """
    raise NotImplementedError

def dggqrf(a, b):
    r"""
    ``dggqrf`` computes a generalized :math:`QR` factorization of a real matrix pair :math:`\left(A, B\right)`, where :math:`A` is an :math:`n\times m` matrix and :math:`B` is an :math:`n\times p` matrix.

    .. _f08ze-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08zef.html

    .. _f08ze-py2-py-parameters:

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

        **b** : float, array-like, shape :math:`\left(n, p\right)`
            The :math:`n\times p` matrix :math:`B`.

    **Returns**
        **a** : float, ndarray, shape :math:`\left(n, m\right)`
            The elements on and above the diagonal of the array contain the :math:`\mathrm{min}\left(n, m\right)\times m` upper trapezoidal matrix :math:`R` (:math:`R` is upper triangular if :math:`n\geq m`); the elements below the diagonal, with the array :math:`\mathrm{taua}`, represent the orthogonal matrix :math:`Q` as a product of :math:`\mathrm{min}\left(n, m\right)` elementary reflectors (see `the F08 Introduction <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08intro.html#recomm_36>`__).

        **taua** : float, ndarray, shape :math:`\left(\min\left(n,m\right)\right)`
            The scalar factors of the elementary reflectors which represent the orthogonal matrix :math:`Q`.

        **b** : float, ndarray, shape :math:`\left(n, p\right)`
            If :math:`n\leq p`, the upper triangle of the subarray :math:`\mathrm{b}[0:n,p-n:p]` contains the :math:`n\times n` upper triangular matrix :math:`T_{12}`.

            If :math:`n > p`, the elements on and above the :math:`\left(n-p\right)`\ th subdiagonal contain the :math:`n\times p` upper trapezoidal matrix :math:`T`; the remaining elements, with the array :math:`\mathrm{taub}`, represent the orthogonal matrix :math:`Z` 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>`__).

        **taub** : float, ndarray, shape :math:`\left(\min\left(n,p\right)\right)`
            The scalar factors of the elementary reflectors which represent the orthogonal matrix :math:`Z`.

    .. _f08ze-py2-py-errors:

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

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

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

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

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

                Constraint: :math:`p\geq 0`.

    .. _f08ze-py2-py-notes:

    **Notes**
        ``dggqrf`` forms the generalized :math:`QR` factorization of an :math:`n\times m` matrix :math:`A` and an :math:`n\times p` matrix :math:`B`

        .. math::
            A = QR\text{, }\quad B = QTZ\text{,}

        where :math:`Q` is an :math:`n\times n` orthogonal matrix, :math:`Z` is a :math:`p\times p` orthogonal matrix and :math:`R` and :math:`T` are of the form

        .. math::
            R = \left\{\begin{array}{c} \begin{matrix}{}\\m\\n-m\end{matrix}\begin{pmatrix}m\\R_{11}\\0\end{pmatrix} \text{, if }n\geq m; \\ \begin{matrix}{}\\n\end{matrix}\begin{pmatrix}n&m-n\\R_{11}&R_{12}\end{pmatrix} \text{, if }n < m, \end{array}\right.

        with :math:`R_{11}` upper triangular,

        .. math::
            T = \left\{\begin{array}{c} \begin{matrix}{}\\n\end{matrix}\begin{pmatrix}p-n&n\\0&T_{12}\end{pmatrix} \text{, if }n\leq p, \\ \begin{matrix}{}\\n-p\\p\end{matrix}\begin{pmatrix}p\\T_{11}\\T_{21}\end{pmatrix} \text{, if }n > p, \end{array}\right.

        with :math:`T_{12}` or :math:`T_{21}` upper triangular.

        In particular, if :math:`B` is square and nonsingular, the generalized :math:`QR` factorization of :math:`A` and :math:`B` implicitly gives the :math:`QR` factorization of :math:`B^{-1}A` as

        .. math::
            B^{-1}A = Z^\mathrm{T}\left(T^{-1}R\right)\text{.}

    .. _f08ze-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug

        Anderson, E, Bai, Z and Dongarra, J, 1992, `Generalized` :math:`QR` `factorization and its applications`, Linear Algebra Appl. (Volume 162--164), 243--271

        Hammarling, S, 1987, `The numerical solution of the general Gauss-Markov linear model`, Mathematics in Signal Processing, (eds T S Durrani, J B Abbiss, J E Hudson, R N Madan, J G McWhirter and T A Moore), 441--456, Oxford University Press

        Paige, C C, 1990, `Some aspects of generalized` :math:`{QR}` `factorizations`, . In Reliable Numerical Computation, (eds M G Cox and S Hammarling), 73--91, Oxford University Press
    """
    raise NotImplementedError

def dggrqf(a, b):
    r"""
    ``dggrqf`` computes a generalized :math:`RQ` factorization of a real matrix pair :math:`\left(A, B\right)`, where :math:`A` is an :math:`m\times n` matrix and :math:`B` is a :math:`p\times n` matrix.

    .. _f08zf-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08zff.html

    .. _f08zf-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(p, n\right)`
            The :math:`p\times n` matrix :math:`B`.

    **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_{12}`.

            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{taua}`, 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>`__).

        **taua** : float, ndarray, shape :math:`\left(\min\left(m,n\right)\right)`
            The scalar factors of the elementary reflectors which represent the orthogonal matrix :math:`Q`.

        **b** : float, ndarray, shape :math:`\left(p, n\right)`
            The elements on and above the diagonal of the array contain the :math:`\mathrm{min}\left(p, n\right)\times n` upper trapezoidal matrix :math:`T` (:math:`T` is upper triangular if :math:`p\geq n`); the elements below the diagonal, with the array :math:`\mathrm{taub}`, represent the orthogonal matrix :math:`Z` 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>`__).

        **taub** : float, ndarray, shape :math:`\left(\min\left(p,n\right)\right)`
            The scalar factors of the elementary reflectors which represent the orthogonal matrix :math:`Z`.

    .. _f08zf-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{p}`.

                Constraint: :math:`p\geq 0`.

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

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

    .. _f08zf-py2-py-notes:

    **Notes**
        ``dggrqf`` forms the generalized :math:`RQ` factorization of an :math:`m\times n` matrix :math:`A` and a :math:`p\times n` matrix :math:`B`

        .. math::
            A = RQ\text{, }\quad B = ZTQ\text{,}

        where :math:`Q` is an :math:`n\times n` orthogonal matrix, :math:`Z` is a :math:`p\times p` orthogonal matrix and :math:`R` and :math:`T` are of the form

        .. math::
            R = \left\{\begin{array}{c} \begin{matrix}{}\\m\end{matrix}\begin{pmatrix}n-m&m\\0&R_{12}\end{pmatrix} \text{; if } m\leq n, \\ \begin{matrix}{}\\m-n\\n\end{matrix}\begin{pmatrix}n\\R_{11}\\R_{21}\end{pmatrix} \text{; if } m > n, \end{array}\right.

        with :math:`R_{12}` or :math:`R_{21}` upper triangular,

        .. math::
            T = \left\{\begin{array}{c} \begin{matrix}{}\\n\\p-n\end{matrix}\begin{pmatrix}n\\T_{11}\\0\end{pmatrix} \text{; if } p\geq n, \\ \begin{matrix}{}\\p\end{matrix}\begin{pmatrix}p&n-p\\T_{11}&T_{12}\end{pmatrix} \text{; if } p < n, \end{array}\right.

        with :math:`T_{11}` upper triangular.

        In particular, if :math:`B` is square and nonsingular, the generalized :math:`RQ` factorization of :math:`A` and :math:`B` implicitly gives the :math:`RQ` factorization of :math:`AB^{-1}` as

        .. math::
            AB^{-1} = \left(RT^{-1}\right)Z^\mathrm{T}\text{.}

    .. _f08zf-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug

        Anderson, E, Bai, Z and Dongarra, J, 1992, `Generalized` :math:`QR` `factorization and its applications`, Linear Algebra Appl. (Volume 162--164), 243--271

        Hammarling, S, 1987, `The numerical solution of the general Gauss-Markov linear model`, Mathematics in Signal Processing, (eds T S Durrani, J B Abbiss, J E Hudson, R N Madan, J G McWhirter and T A Moore), 441--456, Oxford University Press

        Paige, C C, 1990, `Some aspects of generalized` :math:`{QR}` `factorizations`, . In Reliable Numerical Computation, (eds M G Cox and S Hammarling), 73--91, Oxford University Press
    """
    raise NotImplementedError

def zgglse(n, a, b, c, d):
    r"""
    ``zgglse`` solves a complex linear equality-constrained least squares problem.

    .. _f08zn-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08znf.html

    .. _f08zn-py2-py-parameters:

    **Parameters**
        **n** : int
            :math:`n`, the number of columns of the matrices :math:`A` and :math:`B`.

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

        **b** : complex, array-like, shape :math:`\left(p, \mathrm{n}\right)`
            The :math:`p\times n` matrix :math:`B`.

        **c** : complex, array-like, shape :math:`\left(m\right)`
            The right-hand side vector :math:`c` for the least squares part of the LSE problem.

        **d** : complex, array-like, shape :math:`\left(p\right)`
            The right-hand side vector :math:`d` for the equality constraints.

    **Returns**
        **a** : complex, ndarray, shape :math:`\left(m, \mathrm{n}\right)`
            :math:`\mathrm{a}` is overwritten.

        **b** : complex, ndarray, shape :math:`\left(p, \mathrm{n}\right)`
            :math:`\mathrm{b}` is overwritten.

        **c** : complex, ndarray, shape :math:`\left(m\right)`
            The residual sum of squares for the solution vector :math:`x` is given by the sum of squares of elements :math:`\mathrm{c}[\mathrm{n}-p],\mathrm{c}[\mathrm{n}-p+1],\ldots,\mathrm{c}[m-1]`; the remaining elements are overwritten.

        **d** : complex, ndarray, shape :math:`\left(p\right)`
            :math:`\mathrm{d}` is overwritten.

        **x** : complex, ndarray, shape :math:`\left(\mathrm{n}\right)`
            The solution vector :math:`x` of the LSE problem.

    .. _f08zn-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:`\mathrm{n}`.

                Constraint: :math:`\mathrm{n}\geq 0`.

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

                Constraint: :math:`0\leq p\leq \mathrm{n}\leq m+p`.

            (`errno` :math:`1`)
                The upper triangular factor :math:`R` associated with :math:`B` in the generalized :math:`RQ` factorization of the pair :math:`\left(B, A\right)` is singular, so that :math:`\mathrm{rank}\left(B\right) < p`; the least squares solution could not be computed.

            (`errno` :math:`2`)
                The :math:`\left(N-P\right)\times \left(N-P\right)` part of the upper trapezoidal factor :math:`T` associated with :math:`A` in the generalized :math:`RQ` factorization of the pair :math:`\left(B, A\right)` is singular, so that the rank of the matrix (:math:`E`) comprising the rows of :math:`A` and :math:`B` is less than :math:`n`; the least squares solutions could not be computed.

    .. _f08zn-py2-py-notes:

    **Notes**
        ``zgglse`` solves the complex linear equality-constrained least squares (LSE) problem

        .. math::
            \mathrm{minimize}_x\left\lVert c-Ax\right\rVert_2\quad \text{ subject to }\quad Bx = d

        where :math:`A` is an :math:`m\times n` matrix, :math:`B` is a :math:`p\times n` matrix, :math:`c` is an :math:`m` element vector and :math:`d` is a :math:`p` element vector.
        It is assumed that :math:`p\leq n\leq m+p`, :math:`\mathrm{rank}\left(B\right) = p` and :math:`\mathrm{rank}\left(\mathrm{E}\right) = n`, where :math:`E = \begin{pmatrix}A\\B\end{pmatrix}`.
        These conditions ensure that the LSE problem has a unique solution, which is obtained using a generalized :math:`RQ` factorization of the matrices :math:`B` and :math:`A`.

    .. _f08zn-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia

        Anderson, E, Bai, Z and Dongarra, J, 1992, `Generalized` :math:`QR` `factorization and its applications`, Linear Algebra Appl. (Volume 162--164), 243--271

        Eldèn, L, 1980, `Perturbation theory for the least squares problem with linear equality constraints`, SIAM J. Numer. Anal. (17), 338--350
    """
    raise NotImplementedError

def zggglm(p, a, b, d):
    r"""
    ``zggglm`` solves a complex general Gauss--Markov linear (least squares) model problem.

    .. _f08zp-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08zpf.html

    .. _f08zp-py2-py-parameters:

    **Parameters**
        **p** : int
            :math:`p`, the number of columns of the matrix :math:`B`.

        **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(m, \mathrm{p}\right)`
            The :math:`m\times p` matrix :math:`B`.

        **d** : complex, array-like, shape :math:`\left(m\right)`
            The left-hand side vector :math:`d` of the GLM equation.

    **Returns**
        **a** : complex, ndarray, shape :math:`\left(m, n\right)`
            :math:`\mathrm{a}` is overwritten.

        **b** : complex, ndarray, shape :math:`\left(m, \mathrm{p}\right)`
            :math:`\mathrm{b}` is overwritten.

        **d** : complex, ndarray, shape :math:`\left(m\right)`
            :math:`\mathrm{d}` is overwritten.

        **x** : complex, ndarray, shape :math:`\left(n\right)`
            The solution vector :math:`x` of the GLM problem.

        **y** : complex, ndarray, shape :math:`\left(\mathrm{p}\right)`
            The solution vector :math:`y` of the GLM problem.

    .. _f08zp-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:`0\leq n\leq m`.

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

                Constraint: :math:`\mathrm{p}\geq m-n`.

            (`errno` :math:`1`)
                The upper triangular factor :math:`R` associated with :math:`A` in the generalized :math:`RQ` factorization of the pair :math:`\left(A, B\right)` is singular, so that :math:`\mathrm{rank}\left(A\right) < n`; the least squares solution could not be computed.

            (`errno` :math:`2`)
                The bottom :math:`\left(m-n\right)\times \left(m-n\right)` part of the upper trapezoidal factor :math:`T` associated with :math:`B` in the generalized :math:`QR` factorization of the pair :math:`\left(A, B\right)` is singular, so that :math:`\mathrm{rank}\begin{pmatrix}A&B\end{pmatrix} < n`; the least squares solutions could not be computed.

    .. _f08zp-py2-py-notes:

    **Notes**
        ``zggglm`` solves the complex general Gauss--Markov linear model (GLM) problem

        .. math::
            \mathrm{minimize}_x\left\lVert y\right\rVert_2\quad \text{ subject to }\quad d = Ax+By

        where :math:`A` is an :math:`m\times n` matrix, :math:`B` is an :math:`m\times p` matrix and :math:`d` is an :math:`m` element vector.
        It is assumed that :math:`n\leq m\leq n+p`, :math:`\mathrm{rank}\left(A\right) = n` and :math:`\mathrm{rank}\left(E\right) = m`, where :math:`E = \begin{pmatrix}A&B\end{pmatrix}`.
        Under these assumptions, the problem has a unique solution :math:`x` and a minimal :math:`2`-norm solution :math:`y`, which is obtained using a generalized :math:`QR` factorization of the matrices :math:`A` and :math:`B`.

        In particular, if the matrix :math:`B` is square and nonsingular, then the GLM problem is equivalent to the weighted linear least squares problem

        .. math::
            \mathrm{minimize}_x\left\lVert B^{-1}\left(d-Ax\right)\right\rVert_2\text{.}

    .. _f08zp-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia

        Anderson, E, Bai, Z and Dongarra, J, 1992, `Generalized` :math:`QR` `factorization and its applications`, Linear Algebra Appl. (Volume 162--164), 243--271
    """
    raise NotImplementedError

def zggqrf(a, b):
    r"""
    ``zggqrf`` computes a generalized :math:`QR` factorization of a complex matrix pair :math:`\left(A, B\right)`, where :math:`A` is an :math:`n\times m` matrix and :math:`B` is an :math:`n\times p` matrix.

    .. _f08zs-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08zsf.html

    .. _f08zs-py2-py-parameters:

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

        **b** : complex, array-like, shape :math:`\left(n, p\right)`
            The :math:`n\times p` matrix :math:`B`.

    **Returns**
        **a** : complex, ndarray, shape :math:`\left(n, m\right)`
            The elements on and above the diagonal of the array contain the :math:`\mathrm{min}\left(n, m\right)\times m` upper trapezoidal matrix :math:`R` (:math:`R` is upper triangular if :math:`n\geq m`); the elements below the diagonal, with the array :math:`\mathrm{taua}`, represent the unitary matrix :math:`Q` as a product of :math:`\mathrm{min}\left(n, m\right)` elementary reflectors (see `the F08 Introduction <https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08intro.html#recomm_36>`__).

        **taua** : complex, ndarray, shape :math:`\left(\min\left(n,m\right)\right)`
            The scalar factors of the elementary reflectors which represent the unitary matrix :math:`Q`.

        **b** : complex, ndarray, shape :math:`\left(n, p\right)`
            If :math:`n\leq p`, the upper triangle of the subarray :math:`\mathrm{b}[0:n,p-n:p]` contains the :math:`n\times n` upper triangular matrix :math:`T_{12}`.

            If :math:`n > p`, the elements on and above the :math:`\left(n-p\right)`\ th subdiagonal contain the :math:`n\times p` upper trapezoidal matrix :math:`T`; the remaining elements, with the array :math:`\mathrm{taub}`, represent the unitary matrix :math:`Z` 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>`__).

        **taub** : complex, ndarray, shape :math:`\left(\min\left(n,p\right)\right)`
            The scalar factors of the elementary reflectors which represent the unitary matrix :math:`Z`.

    .. _f08zs-py2-py-errors:

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

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

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

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

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

                Constraint: :math:`p\geq 0`.

    .. _f08zs-py2-py-notes:

    **Notes**
        ``zggqrf`` forms the generalized :math:`QR` factorization of an :math:`n\times m` matrix :math:`A` and an :math:`n\times p` matrix :math:`B`

        .. math::
            A = QR\text{, }\quad B = QTZ\text{,}

        where :math:`Q` is an :math:`n\times n` unitary matrix, :math:`Z` is a :math:`p\times p` unitary matrix and :math:`R` and :math:`T` are of the form

        .. math::
            R = \left\{\begin{array}{c} \begin{matrix}{}\\m\\n-m\end{matrix}\begin{pmatrix}m\\R_{11}\\0\end{pmatrix} \text{, if }n\geq m; \\ \begin{matrix}{}\\n\end{matrix}\begin{pmatrix}n&m-n\\R_{11}&R_{12}\end{pmatrix} \text{, if }n < m, \end{array}\right.

        with :math:`R_{11}` upper triangular,

        .. math::
            T = \left\{\begin{array}{c} \begin{matrix}{}\\n\end{matrix}\begin{pmatrix}p-n&n\\0&T_{12}\end{pmatrix} \text{, if }n\leq p, \\ \begin{matrix}{}\\n-p\\p\end{matrix}\begin{pmatrix}p\\T_{11}\\T_{21}\end{pmatrix} \text{, if }n > p, \end{array}\right.

        with :math:`T_{12}` or :math:`T_{21}` upper triangular.

        In particular, if :math:`B` is square and nonsingular, the generalized :math:`QR` factorization of :math:`A` and :math:`B` implicitly gives the :math:`QR` factorization of :math:`B^{-1}A` as

        .. math::
            B^{-1}A = Z^\mathrm{H}\left(T^{-1}R\right)\text{.}

    .. _f08zs-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug

        Anderson, E, Bai, Z and Dongarra, J, 1992, `Generalized` :math:`QR` `factorization and its applications`, Linear Algebra Appl. (Volume 162--164), 243--271

        Hammarling, S, 1987, `The numerical solution of the general Gauss-Markov linear model`, Mathematics in Signal Processing, (eds T S Durrani, J B Abbiss, J E Hudson, R N Madan, J G McWhirter and T A Moore), 441--456, Oxford University Press

        Paige, C C, 1990, `Some aspects of generalized` :math:`{QR}` `factorizations`, . In Reliable Numerical Computation, (eds M G Cox and S Hammarling), 73--91, Oxford University Press
    """
    raise NotImplementedError

def zggrqf(a, b):
    r"""
    ``zggrqf`` computes a generalized :math:`RQ` factorization of a complex matrix pair :math:`\left(A, B\right)`, where :math:`A` is an :math:`m\times n` matrix and :math:`B` is a :math:`p\times n` matrix.

    .. _f08zt-py2-py-doc:

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

    https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08ztf.html

    .. _f08zt-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(p, n\right)`
            The :math:`p\times n` matrix :math:`B`.

    **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_{12}`.

            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{taua}`, 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>`__).

        **taua** : complex, ndarray, shape :math:`\left(\min\left(m,n\right)\right)`
            The scalar factors of the elementary reflectors which represent the unitary matrix :math:`Q`.

        **b** : complex, ndarray, shape :math:`\left(p, n\right)`
            The elements on and above the diagonal of the array contain the :math:`\mathrm{min}\left(p, n\right)\times n` upper trapezoidal matrix :math:`T` (:math:`T` is upper triangular if :math:`p\geq n`); the elements below the diagonal, with the array :math:`\mathrm{taub}`, represent the unitary matrix :math:`Z` 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>`__).

        **taub** : complex, ndarray, shape :math:`\left(\min\left(p,n\right)\right)`
            The scalar factors of the elementary reflectors which represent the unitary matrix :math:`Z`.

    .. _f08zt-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{p}`.

                Constraint: :math:`p\geq 0`.

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

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

    .. _f08zt-py2-py-notes:

    **Notes**
        ``zggrqf`` forms the generalized :math:`RQ` factorization of an :math:`m\times n` matrix :math:`A` and a :math:`p\times n` matrix :math:`B`

        .. math::
            A = RQ\text{, }\quad B = ZTQ\text{,}

        where :math:`Q` is an :math:`n\times n` unitary matrix, :math:`Z` is a :math:`p\times p` unitary matrix and :math:`R` and :math:`T` are of the form

        .. math::
            R = \left\{\begin{array}{c} \begin{matrix}{}\\m\end{matrix}\begin{pmatrix}n-m&m\\0&R_{12}\end{pmatrix} \text{; if } m\leq n, \\ \begin{matrix}{}\\m-n\\n\end{matrix}\begin{pmatrix}n\\R_{11}\\R_{21}\end{pmatrix} \text{; if } m > n, \end{array}\right.

        with :math:`R_{12}` or :math:`R_{21}` upper triangular,

        .. math::
            T = \left\{\begin{array}{c} \begin{matrix}{}\\n\\p-n\end{matrix}\begin{pmatrix}n\\T_{11}\\0\end{pmatrix} \text{; if } p\geq n, \\ \begin{matrix}{}\\p\end{matrix}\begin{pmatrix}p&n-p\\T_{11}&T_{12}\end{pmatrix} \text{; if } p < n, \end{array}\right.

        with :math:`T_{11}` upper triangular.

        In particular, if :math:`B` is square and nonsingular, the generalized :math:`RQ` factorization of :math:`A` and :math:`B` implicitly gives the :math:`RQ` factorization of :math:`AB^{-1}` as

        .. math::
            AB^{-1} = \left(RT^{-1}\right)Z^\mathrm{H}\text{.}

    .. _f08zt-py2-py-references:

    **References**
        Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, `LAPACK Users' Guide`, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug

        Anderson, E, Bai, Z and Dongarra, J, 1992, `Generalized` :math:`QR` `factorization and its applications`, Linear Algebra Appl. (Volume 162--164), 243--271

        Hammarling, S, 1987, `The numerical solution of the general Gauss-Markov linear model`, Mathematics in Signal Processing, (eds T S Durrani, J B Abbiss, J E Hudson, R N Madan, J G McWhirter and T A Moore), 441--456, Oxford University Press

        Paige, C C, 1990, `Some aspects of generalized` :math:`{QR}` `factorizations`, . In Reliable Numerical Computation, (eds M G Cox and S Hammarling), 73--91, Oxford University Press
    """
    raise NotImplementedError