hide long namesshow long names
hide short namesshow short names
Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

NAG Toolbox: nag_sparseig_real_option (f12ad)

Purpose

nag_sparseig_real_option (f12ad) is an option setting function that may be used to supply individual optional parameters to nag_sparseig_real_iter (f12ab) and nag_sparseig_real_proc (f12ac). These are part of a suite of functions that also includes: nag_sparseig_real_init (f12aa) and nag_sparseig_real_monit (f12ae). The initialization function nag_sparseig_real_init (f12aa) must have been called prior to calling nag_sparseig_real_option (f12ad).

Syntax

[icomm, comm, ifail] = f12ad(str, icomm, comm)
[icomm, comm, ifail] = nag_sparseig_real_option(str, icomm, comm)

Description

nag_sparseig_real_option (f12ad) may be used to supply values for optional parameters to nag_sparseig_real_iter (f12ab) and nag_sparseig_real_proc (f12ac). It is only necessary to call nag_sparseig_real_option (f12ad) for those parameters whose values are to be different from their default values. One call to nag_sparseig_real_option (f12ad) sets one parameter value.
Each optional parameter is defined by a single character string consisting of one or more items. The items associated with a given option must be separated by spaces, or equals signs [ = ] [ = ] . Alphabetic characters may be upper or lower case. The string
'Vectors = None'
is an example of a string used to set an optional parameter. For each option the string contains one or more of the following items:
a mandatory keyword;
a phrase that qualifies the keyword;
a number that specifies an integer or double value. Such numbers may be up to 1616 contiguous characters in Fortran's I, F, E or D format.
nag_sparseig_real_option (f12ad) does not have an equivalent function from the ARPACK package which passes options by directly setting values to scalar parameters or to specific elements of array arguments. nag_sparseig_real_option (f12ad) is intended to make the passing of options more transparent and follows the same principle as the single option setting functions in Chapter E04.
The setup function nag_sparseig_real_init (f12aa) must be called prior to the first call to nag_sparseig_real_option (f12ad) and all calls to nag_sparseig_real_option (f12ad) must precede the first call to nag_sparseig_real_iter (f12ab), the reverse communication iterative solver.
A complete list of optional parameters, their abbreviations, synonyms and default values is given in Section [Optional Parameters].

References

Lehoucq R B (2001) Implicitly restarted Arnoldi methods and subspace iteration SIAM Journal on Matrix Analysis and Applications 23 551–562
Lehoucq R B and Scott J A (1996) An evaluation of software for computing eigenvalues of sparse nonsymmetric matrices Preprint MCS-P547-1195 Argonne National Laboratory
Lehoucq R B and Sorensen D C (1996) Deflation techniques for an implicitly restarted Arnoldi iteration SIAM Journal on Matrix Analysis and Applications 17 789–821
Lehoucq R B, Sorensen D C and Yang C (1998) ARPACK Users' Guide: Solution of Large-scale Eigenvalue Problems with Implicitly Restarted Arnoldi Methods SIAM, Philidelphia

Parameters

Compulsory Input Parameters

1:     str – string
A single valid option string (as described in Section [Description] and Section [Optional Parameters]).
2:     icomm( : :) – int64int32nag_int array
Note: the dimension of the array icomm must be at least max (1,licomm)max(1,licomm) (see nag_sparseig_real_init (f12aa)).
On initial entry: must remain unchanged following a call to the setup function nag_sparseig_real_init (f12aa).
3:     comm( : :) – double array
Note: the dimension of the array comm must be at least 6060.
On initial entry: must remain unchanged following a call to the setup function nag_sparseig_real_init (f12aa).

Optional Input Parameters

None.

Input Parameters Omitted from the MATLAB Interface

None.

Output Parameters

1:     icomm( : :) – int64int32nag_int array
Note: the dimension of the array icomm must be at least max (1,licomm)max(1,licomm) (see nag_sparseig_real_init (f12aa)).
Contains data on the current options set.
2:     comm( : :) – double array
Note: the dimension of the array comm must be at least 6060.
Contains data on the current options set.
3:     ifail – int64int32nag_int scalar
ifail = 0ifail=0 unless the function detects an error (see [Error Indicators and Warnings]).

Error Indicators and Warnings

Errors or warnings detected by the function:
  ifail = 1ifail=1
The string passed in str contains an ambiguous keyword.
  ifail = 2ifail=2
The string passed in str contains a keyword that could not be recognized.
  ifail = 3ifail=3
The string passed in str contains a second keyword that could not be recognized.
  ifail = 4ifail=4
The initialization function nag_sparseig_real_init (f12aa) has not been called or a communication array has become corrupted.

Accuracy

Not applicable.

Further Comments

None.

Example

function nag_sparseig_real_option_example
n = 100;
nev = 4;
ncv = 20;

h = 1/(double(n)+1);
rho = 10;
md = repmat(4*h, double(n), 1);
me = repmat(h, double(n-1), 1);

irevcm = int64(0);
resid = zeros(n,1);
v = zeros(n, ncv);
x = zeros(n, 1);
mx = zeros(n);

dd = 2/h;
dl = -1/h - rho/2;
du = -1/h + rho/2;
y = zeros(n,1);

[icomm, comm, ifail] = nag_sparseig_real_init(int64(n), int64(nev), int64(ncv));
[icomm, comm, ifail] = nag_sparseig_real_option('REGULAR INVERSE', icomm, comm);
[icomm, comm, ifail] = nag_sparseig_real_option('GENERALIZED', icomm, comm);

% Construct m and factorise
[md, me, info] = nag_lapack_dpttrf(md, me);

while (irevcm ~= 5)
  [irevcm, resid, v, x, mx, nshift, comm, icomm, ifail] = ...
    nag_sparseig_real_iter(irevcm, resid, v, x, mx, comm, icomm);
  if (irevcm == -1 || irevcm == 1)
    y(1) = dd*x(1) + du*x(2);
    for i = 2:n-1
      y(i) = dl*x(i-1) + dd*x(i) + du*x(i+1);
    end
    y(n) = dl*x(n-1) + dd*x(n);
    [x, info] = nag_lapack_dpttrs(md, me, y);
  elseif (irevcm == 2)
    y(1) = 4*x(1) + x(2);
    for i=2:n-1
      y(i) = x(i-1) + 4*x(i) + x(i+1);
    end
    y(n) = x(n-1) + 4*x(n);
    x = h*y;
  elseif (irevcm == 4)
    [niter, nconv, ritzr, ritzi, rzest] = nag_sparseig_real_monit(icomm, comm);
    if (niter == 1)
      fprintf('\n');
    end
    fprintf('Iteration %2d No. converged = %d Norm of estimates = %16.8e\n', niter, nconv, norm(rzest));
  end
end
[nconv, dr, di, z, v, comm, icomm, ifail] = ...
    nag_sparseig_real_proc(0, 0, resid, v, comm, icomm);
 nconv, dr, di, ifail
 

Iteration  1 No. converged = 0 Norm of estimates =   5.56325675e+03
Iteration  2 No. converged = 0 Norm of estimates =   5.44836588e+03
Iteration  3 No. converged = 0 Norm of estimates =   5.30320774e+03
Iteration  4 No. converged = 0 Norm of estimates =   6.24234186e+03
Iteration  5 No. converged = 0 Norm of estimates =   7.15674705e+03
Iteration  6 No. converged = 0 Norm of estimates =   5.45460864e+03
Iteration  7 No. converged = 0 Norm of estimates =   6.43147571e+03
Iteration  8 No. converged = 0 Norm of estimates =   5.11241161e+03
Iteration  9 No. converged = 0 Norm of estimates =   7.19327824e+03
Iteration 10 No. converged = 1 Norm of estimates =   5.77945489e+03
Iteration 11 No. converged = 2 Norm of estimates =   4.73125738e+03
Iteration 12 No. converged = 3 Norm of estimates =   5.00078500e+03

nconv =

                    4


dr =

   1.0e+04 *

    2.0383
    2.0339
    2.0265
    2.0163


di =

     0
     0
     0
     0


ifail =

                    0


function f12ad_example
n = 100;
nev = 4;
ncv = 20;

h = 1/(double(n)+1);
rho = 10;
md = repmat(4*h, double(n), 1);
me = repmat(h, double(n-1), 1);

irevcm = int64(0);
resid = zeros(n,1);
v = zeros(n, ncv);
x = zeros(n, 1);
mx = zeros(n);

dd = 2/h;
dl = -1/h - rho/2;
du = -1/h + rho/2;
y = zeros(n,1);

[icomm, comm, ifail] = f12aa(int64(n), int64(nev), int64(ncv));
[icomm, comm, ifail] = f12ad('REGULAR INVERSE', icomm, comm);
[icomm, comm, ifail] = f12ad('GENERALIZED', icomm, comm);

% Construct m and factorise
[md, me, info] = f07jd(md, me);

while (irevcm ~= 5)
  [irevcm, resid, v, x, mx, nshift, comm, icomm, ifail] = ...
    f12ab(irevcm, resid, v, x, mx, comm, icomm);
  if (irevcm == -1 || irevcm == 1)
    y(1) = dd*x(1) + du*x(2);
    for i = 2:n-1
      y(i) = dl*x(i-1) + dd*x(i) + du*x(i+1);
    end
    y(n) = dl*x(n-1) + dd*x(n);
    [x, info] = f07je(md, me, y);
  elseif (irevcm == 2)
    y(1) = 4*x(1) + x(2);
    for i=2:n-1
      y(i) = x(i-1) + 4*x(i) + x(i+1);
    end
    y(n) = x(n-1) + 4*x(n);
    x = h*y;
  elseif (irevcm == 4)
    [niter, nconv, ritzr, ritzi, rzest] = f12ae(icomm, comm);
    if (niter == 1)
      fprintf('\n');
    end
    fprintf('Iteration %2d No. converged = %d Norm of estimates = %16.8e\n', ...
            niter, nconv, norm(rzest));
  end
end
[nconv, dr, di, z, v, comm, icomm, ifail] = f12ac(0, 0, resid, v, comm, icomm);
 nconv, dr, di, ifail
 

Iteration  1 No. converged = 0 Norm of estimates =   5.56325675e+03
Iteration  2 No. converged = 0 Norm of estimates =   5.44836588e+03
Iteration  3 No. converged = 0 Norm of estimates =   5.30320774e+03
Iteration  4 No. converged = 0 Norm of estimates =   6.24234186e+03
Iteration  5 No. converged = 0 Norm of estimates =   7.15674705e+03
Iteration  6 No. converged = 0 Norm of estimates =   5.45460864e+03
Iteration  7 No. converged = 0 Norm of estimates =   6.43147571e+03
Iteration  8 No. converged = 0 Norm of estimates =   5.11241161e+03
Iteration  9 No. converged = 0 Norm of estimates =   7.19327824e+03
Iteration 10 No. converged = 1 Norm of estimates =   5.77945489e+03
Iteration 11 No. converged = 2 Norm of estimates =   4.73125738e+03
Iteration 12 No. converged = 3 Norm of estimates =   5.00078500e+03

nconv =

                    4


dr =

   1.0e+04 *

    2.0383
    2.0339
    2.0265
    2.0163


di =

     0
     0
     0
     0


ifail =

                    0


Optional Parameters

Several optional parameters for the computational functions nag_sparseig_real_iter (f12ab) and nag_sparseig_real_proc (f12ac) define choices in the problem specification or the algorithm logic. In order to reduce the number of formal parameters of nag_sparseig_real_iter (f12ab) and nag_sparseig_real_proc (f12ac) these optional parameters have associated default values that are appropriate for most problems. Therefore, you need only specify those optional parameters whose values are to be different from their default values.
The remainder of this section can be skipped if you wish to use the default values for all optional parameters.
The following is a list of the optional parameters available. A full description of each optional parameter is provided in Section [Description of the Optional s].
Optional parameters may be specified by calling nag_sparseig_real_option (f12ad) before a call to nag_sparseig_real_iter (f12ab), but after a call to nag_sparseig_real_init (f12aa). One call is necessary for each optional parameter.
All optional parameters you do not specify are set to their default values. Optional parameters you specify are unaltered by nag_sparseig_real_iter (f12ab) and nag_sparseig_real_proc (f12ac) (unless they define invalid values) and so remain in effect for subsequent calls unless you alter them.

Description of the Optional Parameters

For each option, we give a summary line, a description of the optional parameter and details of constraints.
The summary line contains:
Keywords and character values are case and white space insensitive.
Advisory  ii
Default = =  the value returned by nag_file_set_unit_advisory (x04ab)
The destination for advisory messages.
Defaults  
This special keyword may be used to reset all optional parameters to their default values.
Exact Shifts  
Default
Supplied Shifts  
During the Arnoldi iterative process, shifts are applied internally as part of the implicit restarting scheme. The shift strategy used by default and selected by the Exact Shifts is strongly recommended over the alternative Supplied Shifts (see Lehoucq et al. (1998) for details of shift strategies).
If Exact Shifts are used then these are computed internally by the algorithm in the implicit restarting scheme.
If Supplied Shifts are used then, during the Arnoldi iterative process, you must supply shifts through array arguments of nag_sparseig_real_iter (f12ab) when nag_sparseig_real_iter (f12ab) returns with irevcm = 3irevcm=3; the real and imaginary parts of the shifts are supplied in x and mx respectively (or in comm when the option Pointers = YESPointers=YES is set). This option should only be used if you are an experienced user since this requires some algorithmic knowledge and because more operations are usually required than for the implicit shift scheme. Details on the use of explicit shifts and further references on shift strategies are available in Lehoucq et al. (1998).
Iteration Limit  ii
Default = 300 = 300  
The limit on the number of Arnoldi iterations that can be performed before nag_sparseig_real_iter (f12ab) exits. If not all requested eigenvalues have converged to within Tolerance and the number of Arnoldi iterations has reached this limit then nag_sparseig_real_iter (f12ab) exits with an error; nag_sparseig_real_proc (f12ac) can still be called subsequently to return the number of converged eigenvalues, the converged eigenvalues and, if requested, the corresponding eigenvectors.
Largest Magnitude  
Default
Largest Imaginary  
Largest Real  
Smallest Imaginary  
Smallest Magnitude  
Smallest Real  
The Arnoldi iterative method converges on a number of eigenvalues with given properties. The default is for nag_sparseig_real_iter (f12ab) to compute the eigenvalues of largest magnitude using Largest Magnitude. Alternatively, eigenvalues may be chosen which have Largest Real part, Largest Imaginary part,Smallest Magnitude, Smallest Real part or Smallest Imaginary part.
Note that these options select the eigenvalue properties for eigenvalues of OPOP (and BB for Generalized problems), the linear operator determined by the computational mode and problem type.
Nolist  
Default
List  
Normally each optional parameter specification is not printed to the advisory channel as it is supplied. Optional parameter List may be used to enable printing and optional parameter Nolist may be used to suppress the printing.
Monitoring  ii
Default = 1 = -1
If i > 0i>0, monitoring information is output to channel number ii during the solution of each problem; this may be the same as the Advisory channel number. The type of information produced is dependent on the value of Print Level, see the description of the optional parameter Print Level for details of the information produced. Please see nag_file_open (x04ac) to associate a file with a given channel number.
Pointers  
Default = NO = NO
During the iterative process and reverse communication calls to nag_sparseig_real_iter (f12ab), required data can be communicated to and from nag_sparseig_real_iter (f12ab) in one of two ways. When Pointers = NOPointers=NO is selected (the default) then the array arguments x and mx are used to supply you with required data and used to return computed values back to nag_sparseig_real_iter (f12ab). For example, when irevcm = 1irevcm=1, nag_sparseig_real_iter (f12ab) returns the vector xx in x and the matrix-vector product BxBx in mx and expects the result or the linear operation OP(x)OP(x) to be returned in x.
If Pointers = YESPointers=YES is selected then the data is passed through sections of the array argument comm. The section corresponding to x when Pointers = NOPointers=NO begins at a location given by the first element of icomm; similarly the section corresponding to mx begins at a location given by the second element of icomm. This option allows nag_sparseig_real_iter (f12ab) to perform fewer copy operations on each intermediate exit and entry, but can also lead to less elegant code in the calling program.
Print Level  ii
Default = 0 = 0
This controls the amount of printing produced by nag_sparseig_real_option (f12ad) as follows.
= 0=0 No output except error messages.
> 0>0 The set of selected options.
= 2=2 Problem and timing statistics on final exit from nag_sparseig_real_iter (f12ab).
55 A single line of summary output at each Arnoldi iteration.
1010 If Monitoring > 0Monitoring>0, Monitoring is set, then at each iteration, the length and additional steps of the current Arnoldi factorization and the number of converged Ritz values; during re-orthogonalization, the norm of initial/restarted starting vector.
2020 Problem and timing statistics on final exit from nag_sparseig_real_iter (f12ab). If Monitoring > 0Monitoring>0, Monitoring is set, then at each iteration, the number of shifts being applied, the eigenvalues and estimates of the Hessenberg matrix HH, the size of the Arnoldi basis, the wanted Ritz values and associated Ritz estimates and the shifts applied; vector norms prior to and following re-orthogonalization.
3030 If Monitoring > 0Monitoring>0, Monitoring is set, then on final iteration, the norm of the residual; when computing the Schur form, the eigenvalues and Ritz estimates both before and after sorting; for each iteration, the norm of residual for compressed factorization and the compressed upper Hessenberg matrix HH; during re-orthogonalization, the initial/restarted starting vector; during the Arnoldi iteration loop, a restart is flagged and the number of the residual requiring iterative refinement; while applying shifts, the indices of the shifts being applied.
4040 If Monitoring > 0Monitoring>0, Monitoring is set, then during the Arnoldi iteration loop, the Arnoldi vector number and norm of the current residual; while applying shifts, key measures of progress and the order of HH; while computing eigenvalues of HH, the last rows of the Schur and eigenvector matrices; when computing implicit shifts, the eigenvalues and Ritz estimates of HH.
5050 If Monitoring is set, then during Arnoldi iteration loop: norms of key components and the active column of HH, norms of residuals during iterative refinement, the final upper Hessenberg matrix HH; while applying shifts: number of shifts, shift values, block indices, updated matrix HH; while computing eigenvalues of HH: the matrix HH, the computed eigenvalues and Ritz estimates.
Random Residual  
Default
Initial Residual  
To begin the Arnoldi iterative process, nag_sparseig_real_iter (f12ab) requires an initial residual vector. By default nag_sparseig_real_iter (f12ab) provides its own random initial residual vector; this option can also be set using optional parameter Random Residual. Alternatively, you can supply an initial residual vector (perhaps from a previous computation) to nag_sparseig_real_iter (f12ab) through the array argument resid; this option can be set using optional parameter Initial Residual.
Regular  
Default
Regular Inverse  
Shifted Inverse Imaginary  
Shifted Inverse Real  
These options define the computational mode which in turn defines the form of operation OP(x)OP(x) to be performed when nag_sparseig_real_iter (f12ab) returns with irevcm = 1irevcm=-1 or 11 and the matrix-vector product BxBx when nag_sparseig_real_iter (f12ab) returns with irevcm = 2irevcm=2.
Given a Standard eigenvalue problem in the form Ax = λxAx=λx then the following modes are available with the appropriate operator OP(x)OP(x).
Regular OP = AOP=A
Shifted Inverse Real OP = (AσI)1OP=(A-σI)-1 where σσ is real
Given a Generalized eigenvalue problem in the form Ax = λBxAx=λBx then the following modes are available with the appropriate operator OP(x)OP(x).
Regular Inverse OP = B1AOP=B-1A
Shifted Inverse Real with real shift OP = (AσB)1BOP=(A-σB)-1B, where σσ is real
Shifted Inverse Real with complex shift OP = Real((AσB)1B)OP=Real((A-σB)-1B), where σσ is complex
Shifted Inverse Imaginary OP = Imag((AσB)1B)OP=Imag((A-σB)-1B), where σσ is complex
Standard  
Default
Generalized  
The problem to be solved is either a standard eigenvalue problem, Ax = λxAx=λx, or a generalized eigenvalue problem, Ax = λBxAx=λBx. The optional parameter Standard should be used when a standard eigenvalue problem is being solved and the optional parameter Generalized should be used when a generalized eigenvalue problem is being solved.
Tolerance  rr
Default = ε = ε  
An approximate eigenvalue has deemed to have converged when the corresponding Ritz estimate is within Tolerance relative to the magnitude of the eigenvalue.
Vectors  
Default = RITZ = RITZ
The function nag_sparseig_real_proc (f12ac) can optionally compute the Schur vectors and/or the eigenvectors corresponding to the converged eigenvalues. To turn off computation of any vectors the option Vectors = NONEVectors=NONE should be set. To compute only the Schur vectors (at very little extra cost), the option Vectors = SCHURVectors=SCHUR should be set and these will be returned in the array argument v of nag_sparseig_real_proc (f12ac). To compute the eigenvectors (Ritz vectors) ­corresponding to the eigenvalue estimates, the option Vectors = RITZVectors=RITZ should be set and these will be returned in the array argument z of nag_sparseig_real_proc (f12ac), if z is set equal to v (as in Section [Example]) then the Schur vectors in v are overwritten by the eigenvectors computed by nag_sparseig_real_proc (f12ac).

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2013