naginterfaces.library.lapackeig.zggsvp

naginterfaces.library.lapackeig.zggsvp(jobu, jobv, jobq, a, b, tola, tolb)

zggsvp uses unitary transformations to simultaneously reduce the $m\times n$ matrix $A$ and the $p\times n$ matrix $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 zggsvp3() which makes better use of Level 3 BLAS.

Deprecated since version 27.0.0.0: zggsvp is deprecated. Please use zggsvp3() instead. See also the Replacement Calls document.

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

Parameters

jobustr, length 1

If $jobu=\text{'U'}$, the unitary matrix $U$ is computed.

If $jobu=\text{'N'}$, $U$ is not computed.

jobvstr, length 1

If $jobv=\text{'V'}$, the unitary matrix $V$ is computed.

If $jobv=\text{'N'}$, $V$ is not computed.

jobqstr, length 1

If $jobq=\text{'Q'}$, the unitary matrix $Q$ is computed.

If $jobq=\text{'N'}$, $Q$ is not computed.

acomplex, array-like, shape $(m,n)$

The $m\times n$ matrix $A$.

bcomplex, array-like, shape $(p,n)$

The $p\times n$ matrix $B$.

tolafloat

$tola$ and $tolb$ are the thresholds to determine the effective numerical rank of matrix $B$ and a subblock of $A$. Generally, they are set to

$$\begin{array}{c}\begin{array}{c}tola=max(m,n)\parallel A\parallel ϵ\text{,}\\ tolb=max(p,n)\parallel B\parallel ϵ\text{,}\end{array}\end{array}$$

where $ϵ$ is the machine precision.

The size of $tola$ and $tolb$ may affect the size of backward errors of the decomposition.

tolbfloat

$tola$ and $tolb$ are the thresholds to determine the effective numerical rank of matrix $B$ and a subblock of $A$. Generally, they are set to

$$\begin{array}{c}\begin{array}{c}tola=max(m,n)\parallel A\parallel ϵ\text{,}\\ tolb=max(p,n)\parallel B\parallel ϵ\text{,}\end{array}\end{array}$$

where $ϵ$ is the machine precision.

The size of $tola$ and $tolb$ may affect the size of backward errors of the decomposition.

Returns

acomplex, ndarray, shape $(m,n)$

Contains the triangular (or trapezoidal) matrix described in Notes.

bcomplex, ndarray, shape $(p,n)$

Contains the triangular matrix described in Notes.

kint

$k$ and $l$ specify the dimension of the subblocks $k$ and $l$ as described in Notes; $(k+l)$ is the effective numerical rank of ${\left(\begin{array}{cc}{a}^T& b^T\end{array}\right)}^T$.

lint

$k$ and $l$ specify the dimension of the subblocks $k$ and $l$ as described in Notes; $(k+l)$ is the effective numerical rank of ${\left(\begin{array}{cc}{a}^T& b^T\end{array}\right)}^T$.

ucomplex, ndarray, shape $(:,:)$

If $jobu=\text{'U'}$, $u$ contains the unitary matrix $U$.

If $jobu=\text{'N'}$, $u$ is not referenced.

vcomplex, ndarray, shape $(:,:)$

If $jobv=\text{'V'}$, $v$ contains the unitary matrix $V$.

If $jobv=\text{'N'}$, $v$ is not referenced.

qcomplex, ndarray, shape $(:,:)$

If $jobq=\text{'Q'}$, $q$ contains the unitary matrix $Q$.

If $jobq=\text{'N'}$, $q$ is not referenced.

Raises

NagValueError

(errno $-1$)

On entry, error in parameter $jobu$.

Constraint: $jobu=\text{'U'}$ or $\text{'N'}$.

(errno $-2$)

On entry, error in parameter $jobv$.

Constraint: $jobv=\text{'V'}$ or $\text{'N'}$.

(errno $-3$)

On entry, error in parameter $jobq$.

Constraint: $jobq=\text{'Q'}$ or $\text{'N'}$.

(errno $-4$)

On entry, error in parameter $\text{m}$.

Constraint: $m\ge 0$.

(errno $-5$)

On entry, error in parameter $\text{p}$.

Constraint: $p\ge 0$.

(errno $-6$)

On entry, error in parameter $\text{n}$.

Constraint: $n\ge 0$.

Notes

zggsvp computes unitary matrices $U$, $V$ and $Q$ such that

$$\begin{array}{c}\begin{array}{c}{U}^{H}AQ=\{\begin{array}{c}\begin{array}{c}\\ k\\ l\\ m-k-l\end{array}\left(\begin{array}{ccc}n-k-l& k& l\\ 0& A_{12}& A_{13}\\ 0& 0& A_{23}\\ 0& 0& 0\end{array}\right)\text{, if}m-k-l\ge 0\text{;}\\ \begin{array}{c}\\ k\\ m-k\end{array}\left(\begin{array}{ccc}n-k-l& k& l\\ 0& A_{12}& A_{13}\\ 0& 0& A_{23}\end{array}\right)\text{, if}m-k-l<0\text{;}\end{array}\\ V^{H}BQ=\begin{array}{c}\\ l\\ p-l\end{array}\left(\begin{array}{ccc}n-k-l& k& l\\ 0& 0& B_{13}\\ 0& 0& 0\end{array}\right)\end{array}\end{array}$$

where the $k\times k$ matrix $A_{12}$ and $l\times l$ matrix $B_{13}$ are nonsingular upper triangular; $A_{23}$ is $l\times l$ upper triangular if $m-k-l\ge 0$ and is $(m-k)\times l$ upper trapezoidal otherwise. $(k+l)$ is the effective numerical rank of the $(m+p)\times n$ matrix ${\left(\begin{array}{cc}{A}^H& B^H\end{array}\right)}^H$.

This decomposition is usually used as the preprocessing step for computing the Generalized Singular Value Decomposition (GSVD), see function zggsvd().

References

Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J 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