naginterfaces.library.lapackeig.dggsvp3

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

dggsvp3 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). For sufficiently large problems, a blocked algorithm is used to make best use of Level 3 BLAS.

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

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

dggsvp3 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 dtgsja(); the two steps are combined in dggsvd3().

References

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