MATLAB Interface to GUPTRI.

An interface to MATLAB in terms of a MEX-file is available for the routine GUPTRI. In the following we give a brief description of the arguments and output of the guptri function and demonstrate its usage on a small numerical example.

The most general call,

$${\tt [S, T, P, Q, kstr] = guptri(A, B, EPSU, GAP, ZERO)},$$

stores the transformation matrices in P and Q and $P^{\ast}AQ$ and $P^{\ast}BQ$ in S and T, respectively. The computed Kronecker structure is revealed by kstr, as described in the example discussed later in this section.

The guptri function reduces an $m \times n$ pencil $A - \lambda B$ to generalized upper triangular form $S - \lambda T = P^{\ast}(A - \lambda B)Q$ as in (8.34)-(8.35): S= ccccc A_r & * & * & * & *
0 &A_z & * & * & *
0 & 0 &A_f & * & *
0 & 0 & 0 &A_i& *
0 & 0 & 0 & 0 & A_l ,          T= ccccc B_r & * & * & * & *
0 &B_z & * & * & *
0 &0 &B_f& * & *
0 &0 &0 &B_i & *
0 &0 &0 & 0 &B_l , where the diagonal blocks of $S$ and $T$ in staircase forms describe the Kronecker structure of $A - \lambda B$ (see §8.7.6).

Besides $\{A,B\}$, the user can optionally provide three input parameters (EPSU, GAP, and ZERO) that control the computation of the GUPTRI form. EPSU (relative uncertainty in data) and GAP (should be at least 1 and nominally 1000) are used to make rank decisions in order to determine the Kronecker structure of an input pencil (see p. ). The default value is ${\tt GAP} = 1000$, but other values may be necessary for certain examples. ZERO is used as a logical variable, which when set to true (ZERO = nonzero value) forces guptri to zero out small singular values during the reduction process so that the returned pencil really has the computed GUPTRI form (see p. ). Otherwise, the returned pencil is a true equivalence transformation of the input pencil and all zero blocks in the GUPTRI form will contain small entries (normally of size EPSU at most).