NAG Toolbox: nag_sparseig_complex_band_solve (f12au)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{kl}$ – int64int32nag_int scalar

The number of subdiagonals of the matrices $A$ and $B$.

Constraint: $\mathbf{kl}\ge 0$.

2:     $\mathrm{ku}$ – int64int32nag_int scalar

The number of superdiagonals of the matrices $A$ and $B$.

Constraint: $\mathbf{ku}\ge 0$.

3:     $\mathrm{ab}\left(\mathit{ldab},:\right)$ – complex array

The first dimension of the array ab must be at least $2\times \mathbf{kl}+\mathbf{ku}+1$.

The second dimension of the array ab must be at least $\max \left(1,\mathbf{n}\right)$.

Must contain the matrix $A$ in LAPACK banded storage format for non-Hermitian matrices (see Band storage in the F07 Chapter Introduction).

4:     $\mathrm{mb}\left(\mathit{ldmb},:\right)$ – complex array

The first dimension of the array mb must be at least $2\times \mathbf{kl}+\mathbf{ku}+1$.

The second dimension of the array mb must be at least $\max \left(1,\mathbf{n}\right)$.

Must contain the matrix $B$ in LAPACK banded storage format for non-Hermitian matrices (see Band storage in the F07 Chapter Introduction).

5:     $\mathrm{sigma}$ – complex scalar

If the Shifted Inverse mode (see nag_sparseig_complex_option (f12ar)) has been selected then sigma must contain the shift used; otherwise sigma is not referenced. Shift and Invert Spectral Transformations in the F12 Chapter Introduction describes the use of shift and invert transformations.

6:     $\mathrm{resid}\left(\mathbf{n}\right)$ – complex array

Need not be set unless the option Initial Residual has been set in a prior call to nag_sparseig_complex_option (f12ar) in which case resid must contain an initial residual vector.

7:     $\mathrm{comm}\left(60\right)$ – complex array

Must remain unchanged from the prior call to nag_sparseig_complex_option (f12ar) and nag_sparseig_complex_band_init (f12at).

8:     $\mathrm{icomm}\left(140\right)$ – int64int32nag_int array

Must remain unchanged from the prior call to nag_sparseig_complex_option (f12ar) and nag_sparseig_complex_band_init (f12at).

Optional Input Parameters

None.

Output Parameters

1:     $\mathrm{nconv}$ – int64int32nag_int scalar

The number of converged eigenvalues.

2:     $\mathrm{d}\left(\mathbf{nev}\right)$ – complex array

The first nconv locations of the array d contain the converged approximate eigenvalues.

3:     $\mathrm{z}\left(\mathit{ldz},:\right)$ – complex array

The first dimension, $\mathit{ldz}$, of the array z will be

• if the default option $\mathbf{Vectors}=\text{Ritz}$ has been selected, $\mathit{ldz}=\mathbf{n}$;
• if the option $\mathbf{Vectors}=\text{None or Schur}$ has been selected, $\mathit{ldz}=1$.

The second dimension of the array z will be $\mathbf{n}\times \left(\mathbf{nev}+1\right)$.

If the default option $\mathbf{Vectors}=\mathrm{RITZ}$ (see nag_sparseig_complex_option (f12ar)) has been selected then z contains the final set of eigenvectors corresponding to the eigenvalues held in d, otherwise z is not referenced. The complex eigenvector associated with an eigenvalue $\mathbf{d}\left(j\right)$ is stored in the corresponding array section of z, namely $\mathbf{z}\left(\mathit{i},\mathit{j}\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{n}$ and $\mathit{j}=1,2,\dots ,\mathbf{nconv}$.

4:     $\mathrm{resid}\left(\mathbf{n}\right)$ – complex array

Contains the final residual vector. This can be used as the starting residual to improve convergence on the solution of a closely related eigenproblem. This has no relation to the error residual $Ax-\lambda x$ or $Ax-\lambda Bx$.

5:     $\mathrm{v}\left(\mathit{ldv},:\right)$ – complex array

The first dimension of the array v will be $\mathbf{n}$.

The second dimension of the array v will be $\max \left(1,\mathbf{n}\times \mathbf{ncv}\right)$.

If the option $\mathbf{Vectors}=\mathrm{SCHUR}$ or $\mathrm{RITZ}$ (see nag_sparseig_complex_option (f12ar)) has been set and a separate array z has been passed (i.e., z does not equal v), then the first nconv columns of v will contain approximate Schur vectors that span the desired invariant subspace.

The $j$th Schur vector is stored in the $i$th column of v.

6:     $\mathrm{comm}\left(60\right)$ – complex array

Communication array, used to store information between calls to nag_sparseig_complex_band_solve (f12au).

7:     $\mathrm{icomm}\left(140\right)$ – int64int32nag_int array

Communication array, used to store information between calls to nag_sparseig_complex_band_solve (f12au).

8:     $\mathrm{ifail}$ – int64int32nag_int scalar

$\mathbf{ifail}=\mathbf{0}$ unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

   $\mathbf{ifail}=1$

Constraint: $\mathbf{kl}\ge 0$.

   $\mathbf{ifail}=2$

Constraint: $\mathbf{ku}\ge 0$.

   $\mathbf{ifail}=3$

Constraint: $\mathit{ldab}\ge 2\times \mathbf{kl}+\mathbf{ku}+1$.

   $\mathbf{ifail}=5$

The maximum number of iterations $\le 0$, the option Iteration Limit has been set.

   $\mathbf{ifail}=6$

The options Generalized and Regular are incompatible.

   $\mathbf{ifail}=7$

The option Initial Residual was selected but the starting vector held in resid is zero.

   $\mathbf{ifail}=8$

Either the initialization function has not been called prior to the first call of this function or a communication array has become corrupted.

   $\mathbf{ifail}=9$

Constraint: $\mathit{ldz}\ge \mathbf{n}$.

   $\mathbf{ifail}=10$

On entry, $\mathbf{Vectors}=\text{Select}$, but this is not yet implemented.

   $\mathbf{ifail}=11$

The number of eigenvalues found to sufficient accuracy is zero.

   $\mathbf{ifail}=12$

Could not build an Arnoldi factorization.

   $\mathbf{ifail}=13$

Error in internal call to compute eigenvalues and corresponding error bounds of the current upper Hessenberg matrix. Please contact NAG.

   $\mathbf{ifail}=14$

During calculation of a Schur form, there was a failure to compute a number of eigenvalues Please contact NAG.

   $\mathbf{ifail}=15$

The computed Schur form could not be reordered by an internal call. Please contact NAG.

   $\mathbf{ifail}=16$

Error in internal call to compute eigenvectors. Please contact NAG.

   $\mathbf{ifail}=17$

Failure during internal factorization of real banded matrix. Please contact NAG.

   $\mathbf{ifail}=18$

Failure during internal solution of real banded matrix. Please contact NAG.

   $\mathbf{ifail}=19$

Failure during internal factorization of complex banded matrix. Please contact NAG.

   $\mathbf{ifail}=20$

Failure during internal solution of complex banded matrix. Please contact NAG.

   $\mathbf{ifail}=21$

The maximum number of iterations has been reached.

   $\mathbf{ifail}=22$

No shifts could be applied during a cycle of the implicitly restarted Arnoldi iteration.

   $\mathbf{ifail}=23$

Overflow occurred during transformation of Ritz values to those of the original problem.

   $\mathbf{ifail}=-99$

An unexpected error has been triggered by this routine. Please contact NAG.

   $\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

   $\mathbf{ifail}=-999$

Dynamic memory allocation failed.

Accuracy

Further Comments

Example

Open in the MATLAB editor: f12au_example

function f12au_example


fprintf('f12au example results\n\n');

nx = int64(10);
n = nx*nx;
nev = int64(4);
ncv = int64(10);
sigma = 0.4 + 0.6i;

% Construct the matrix A in banded form and store in AB.
% KU, KL are number of superdiagonals and subdiagonals within
% the band of matrices A and M.
kl = nx;
ku = nx;

% Construct ab and mb
ab = zeros(2*kl+ku+1,n);
mb = zeros(2*kl+ku+1,n);

% Main diagonal of A.
idiag = kl + ku + 1;
ab(idiag,1:n) = 4;
mb(idiag,1:n) = ab(idiag,1);

% First subdiagonal and superdiagonal of A.
isup = kl + ku;
isub = kl + ku + 2;
rho = 100;
h = 1/double(nx+1);
for i=1:nx
  lo = (i-1)*nx;
  for j=lo+1:lo+nx-1
    ab(isub,j+1) = -1 + 0.5*h*rho;
    ab(isup,j) = -1 - 0.5*h*rho;
  end
end
mb(isub,2:n)   = 1;
mb(isup,1:n-1) = 1;

% kl-th subdiagonal and ku-th super-diagonal.
isup = kl + 1;
isub = 2*kl + ku + 1;
for i = 1:nx - 1
  lo = (i-1)*nx;
  for j = lo + 1:lo + nx
    ab(isup,nx+j) = -1;
    ab(isub,j) = -1;
  end
end

resid = complex(zeros(100,1));

[icomm, comm, ifail] = f12at( ...
                              n, nev, ncv);
[icomm, comm, ifail] = f12ar( ...
                              'SHIFTED INVERSE', icomm, comm);
[icomm, comm, ifail] = f12ar( ...
                              'GENERALIZED', icomm, comm);

% Find eigenvalues closest in value to SIGMA and corresponding eigenvectors
[nconv, d, z, resid, v, comm, icomm, ifail] = ...
    f12au( ...
           kl, ku, complex(ab), complex(mb), sigma, resid, comm, icomm);

fprintf('\nRitz values closest to sigma:\n');
disp(d);

f12au example results


Ritz values closest to sigma:
   0.3610 + 0.7223i
   0.4598 + 0.7199i
   0.2868 + 0.7241i
   0.2410 + 0.7257i