naginterfaces.library.lapackeig.dggsvp

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

dggsvp uses orthogonal 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). dggsvp is marked as deprecated by LAPACK; the replacement routine is dggsvp3() which makes better use of Level 3 BLAS.

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

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

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

Parameters

jobustr, length 1

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

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

jobvstr, length 1

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

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

jobqstr, length 1

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

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

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

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

bfloat, 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

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

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

bfloat, 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$.

ufloat, ndarray, shape $(:,:)$

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

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

vfloat, ndarray, shape $(:,:)$

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

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

qfloat, ndarray, shape $(:,:)$

If $jobq=\text{'Q'}$, $q$ contains the orthogonal 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

dggsvp computes orthogonal matrices $U$, $V$ and $Q$ such that

$$\begin{array}{c}\begin{array}{c}{U}^{T}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^{T}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}^T& B^T\end{array}\right)}^T$.

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

References

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