naginterfaces.library.sparseig.real_symm_option¶
- naginterfaces.library.sparseig.real_symm_option(optstr, comm, io_manager=None)[source]¶
real_symm_option
is an option setting function in a suite of functions consisting ofreal_symm_init()
,real_symm_iter()
,real_symm_proc()
,real_symm_option
andreal_symm_monit()
, and may be used to supply individual options toreal_symm_iter()
andreal_symm_proc()
. The initialization functionreal_symm_init()
must have been called prior to callingreal_symm_option
.Note: this function uses optional algorithmic parameters, see also:
real_symm_iter()
,real_symm_proc()
,real_symm_init()
.For full information please refer to the NAG Library document for f12fd
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/f12/f12fdf.html
- Parameters
- optstrstr
A single valid option string (as described in Notes and Other Parameters).
- commdict, communication object, modified in place
Communication structure.
This argument must have been initialized by a prior call to
real_symm_init()
.- io_managerFileObjManager, optional
Manager for I/O in this routine.
- Other Parameters
- ‘Advisory’int
Default
The destination for advisory messages.
- ‘Defaults’valueless
This special keyword may be used to reset all options to their default values.
- ‘Exact Shifts’valueless
Default
During the Lanczos 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 Lanczos iterative process, you must supply shifts through array arguments of
real_symm_iter()
whenreal_symm_iter()
returns with ; the real and imaginary parts of the shifts are returned in and respectively (or in when the option 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).- ‘Supplied Shifts’valueless
During the Lanczos 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 Lanczos iterative process, you must supply shifts through array arguments of
real_symm_iter()
whenreal_symm_iter()
returns with ; the real and imaginary parts of the shifts are returned in and respectively (or in when the option 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’int
Default
The limit on the number of Lanczos iterations that can be performed before
real_symm_iter()
exits. If not all requested eigenvalues have converged to within ‘Tolerance’ and the number of Lanczos iterations has reached this limit thenreal_symm_iter()
exits with an error;real_symm_proc()
can still be called subsequently to return the number of converged eigenvalues, the converged eigenvalues and, if requested, the corresponding eigenvectors.- ‘Largest Magnitude’valueless
Default
The Lanczos iterative method converges on a number of eigenvalues with given properties. The default is for
real_symm_iter()
to compute the eigenvalues of largest magnitude using ‘Largest Magnitude’. Alternatively, eigenvalues may be chosen which have ‘Largest Algebraic’ part, ‘Smallest Magnitude’, or ‘Smallest Algebraic’ part; or eigenvalues which are from ‘Both Ends’ of the algebraic spectrum.Note that these options select the eigenvalue properties for eigenvalues of (and for ‘Generalized’ problems), the linear operator determined by the computational mode and problem type.
- ‘Both Ends’valueless
The Lanczos iterative method converges on a number of eigenvalues with given properties. The default is for
real_symm_iter()
to compute the eigenvalues of largest magnitude using ‘Largest Magnitude’. Alternatively, eigenvalues may be chosen which have ‘Largest Algebraic’ part, ‘Smallest Magnitude’, or ‘Smallest Algebraic’ part; or eigenvalues which are from ‘Both Ends’ of the algebraic spectrum.Note that these options select the eigenvalue properties for eigenvalues of (and for ‘Generalized’ problems), the linear operator determined by the computational mode and problem type.
- ‘Largest Algebraic’valueless
The Lanczos iterative method converges on a number of eigenvalues with given properties. The default is for
real_symm_iter()
to compute the eigenvalues of largest magnitude using ‘Largest Magnitude’. Alternatively, eigenvalues may be chosen which have ‘Largest Algebraic’ part, ‘Smallest Magnitude’, or ‘Smallest Algebraic’ part; or eigenvalues which are from ‘Both Ends’ of the algebraic spectrum.Note that these options select the eigenvalue properties for eigenvalues of (and for ‘Generalized’ problems), the linear operator determined by the computational mode and problem type.
- ‘Smallest Algebraic’valueless
The Lanczos iterative method converges on a number of eigenvalues with given properties. The default is for
real_symm_iter()
to compute the eigenvalues of largest magnitude using ‘Largest Magnitude’. Alternatively, eigenvalues may be chosen which have ‘Largest Algebraic’ part, ‘Smallest Magnitude’, or ‘Smallest Algebraic’ part; or eigenvalues which are from ‘Both Ends’ of the algebraic spectrum.Note that these options select the eigenvalue properties for eigenvalues of (and for ‘Generalized’ problems), the linear operator determined by the computational mode and problem type.
- ‘Smallest Magnitude’valueless
The Lanczos iterative method converges on a number of eigenvalues with given properties. The default is for
real_symm_iter()
to compute the eigenvalues of largest magnitude using ‘Largest Magnitude’. Alternatively, eigenvalues may be chosen which have ‘Largest Algebraic’ part, ‘Smallest Magnitude’, or ‘Smallest Algebraic’ part; or eigenvalues which are from ‘Both Ends’ of the algebraic spectrum.Note that these options select the eigenvalue properties for eigenvalues of (and for ‘Generalized’ problems), the linear operator determined by the computational mode and problem type.
- ‘Nolist’valueless
Default
Option ‘List’ enables printing of each option specification as it is supplied. ‘Nolist’ suppresses this printing.
- ‘List’valueless
Option ‘List’ enables printing of each option specification as it is supplied. ‘Nolist’ suppresses this printing.
- ‘Monitoring’int
Default
If , monitoring information is output to unit number (see
unit_from_fileobj()
) during the solution of each problem; this may be the same as the ‘Advisory’ unit number (seeunit_from_fileobj()
). The type of information produced is dependent on the value of ‘Print Level’, see the description of the option ‘Print Level’ for details of the information produced. Please see theFileObjManager
methodunit_from_fileobj()
to associate a file with a given unit number (seeunit_from_fileobj()
).- ‘Pointers’valueless
Default
During the iterative process and reverse communication calls to
real_symm_iter()
, required data can be communicated to and fromreal_symm_iter()
in one of two ways. When is selected (the default) then the array arguments and are used to supply you with required data and used to return computed values back toreal_symm_iter()
. For example, when ,real_symm_iter()
returns the vector in and the matrix-vector product in and expects the result or the linear operation to be returned in .If is selected then the data is passed through sections of the array argument . The section corresponding to when begins at a location given by the first element of ; similarly the section corresponding to begins at a location given by the second element of . This option allows
real_symm_iter()
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’int
Default
This controls the amount of printing produced by
real_symm_option
as follows.Output
No output except error messages. If you want to suppress all output, set .
The set of selected options.
Problem and timing statistics on final exit from
real_symm_iter()
.A single line of summary output at each Lanczos iteration.
If , then at each iteration, the length and additional steps of the current Lanczos factorization and the number of converged Ritz values; during re-orthogonalization, the norm of initial/restarted starting vector; on a final Lanczos iteration, the number of update iterations taken, the number of converged eigenvalues, the converged eigenvalues and their Ritz estimates.
Problem and timing statistics on final exit from
real_symm_iter()
. If , then at each iteration, the number of shifts being applied, the eigenvalues and estimates of the symmetric tridiagonal matrix , the size of the Lanczos basis, the wanted Ritz values and associated Ritz estimates and the shifts applied; vector norms prior to and following re-orthogonalization.If , 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 symmetric tridiagonal matrix ; during re-orthogonalization, the initial/restarted starting vector; during the Lanczos iteration loop, a restart is flagged and the number of the residual requiring iterative refinement; while applying shifts, some indices.
If , then during the Lanczos iteration loop, the Lanczos vector number and norm of the current residual; while applying shifts, key measures of progress and the order of ; while computing eigenvalues of , the last rows of the Schur and eigenvector matrices; when computing implicit shifts, the eigenvalues and Ritz estimates of .
If , then during Lanczos iteration loop: norms of key components and the active column of , norms of residuals during iterative refinement, the final symmetric tridiagonal matrix ; while applying shifts: number of shifts, shift values, block indices, updated tridiagonal matrix ; while computing eigenvalues of : the diagonals of , the computed eigenvalues and Ritz estimates.
Note that setting can result in very lengthy ‘Monitoring’ output.
- ‘Random Residual’valueless
Default
To begin the Lanczos iterative process,
real_symm_iter()
requires an initial residual vector. By defaultreal_symm_iter()
provides its own random initial residual vector; this option can also be set using option ‘Random Residual’. Alternatively, you can supply an initial residual vector (perhaps from a previous computation) toreal_symm_iter()
through the array argument ; this option can be set using option ‘Initial Residual’.- ‘Initial Residual’valueless
To begin the Lanczos iterative process,
real_symm_iter()
requires an initial residual vector. By defaultreal_symm_iter()
provides its own random initial residual vector; this option can also be set using option ‘Random Residual’. Alternatively, you can supply an initial residual vector (perhaps from a previous computation) toreal_symm_iter()
through the array argument ; this option can be set using option ‘Initial Residual’.- ‘Regular’valueless
Default
These options define the computational mode which in turn defines the form of operation to be performed when
real_symm_iter()
returns with or and the matrix-vector product whenreal_symm_iter()
returns with .Given a ‘Standard’ eigenvalue problem in the form then the following modes are available with the appropriate operator .
‘Regular’
‘Shifted Inverse’
where is real
Given a ‘Generalized’ eigenvalue problem in the form then the following modes are available with the appropriate operator .
‘Regular Inverse’
‘Shifted Inverse’
, where is real
‘Buckling’
, where is real
‘Cayley’
, where is real
- ‘Regular Inverse’valueless
These options define the computational mode which in turn defines the form of operation to be performed when
real_symm_iter()
returns with or and the matrix-vector product whenreal_symm_iter()
returns with .Given a ‘Standard’ eigenvalue problem in the form then the following modes are available with the appropriate operator .
‘Regular’
‘Shifted Inverse’
where is real
Given a ‘Generalized’ eigenvalue problem in the form then the following modes are available with the appropriate operator .
‘Regular Inverse’
‘Shifted Inverse’
, where is real
‘Buckling’
, where is real
‘Cayley’
, where is real
- ‘Shifted Inverse’valueless
These options define the computational mode which in turn defines the form of operation to be performed when
real_symm_iter()
returns with or and the matrix-vector product whenreal_symm_iter()
returns with .Given a ‘Standard’ eigenvalue problem in the form then the following modes are available with the appropriate operator .
‘Regular’
‘Shifted Inverse’
where is real
Given a ‘Generalized’ eigenvalue problem in the form then the following modes are available with the appropriate operator .
‘Regular Inverse’
‘Shifted Inverse’
, where is real
‘Buckling’
, where is real
‘Cayley’
, where is real
- ‘Buckling’valueless
These options define the computational mode which in turn defines the form of operation to be performed when
real_symm_iter()
returns with or and the matrix-vector product whenreal_symm_iter()
returns with .Given a ‘Standard’ eigenvalue problem in the form then the following modes are available with the appropriate operator .
‘Regular’
‘Shifted Inverse’
where is real
Given a ‘Generalized’ eigenvalue problem in the form then the following modes are available with the appropriate operator .
‘Regular Inverse’
‘Shifted Inverse’
, where is real
‘Buckling’
, where is real
‘Cayley’
, where is real
- ‘Cayley’valueless
These options define the computational mode which in turn defines the form of operation to be performed when
real_symm_iter()
returns with or and the matrix-vector product whenreal_symm_iter()
returns with .Given a ‘Standard’ eigenvalue problem in the form then the following modes are available with the appropriate operator .
‘Regular’
‘Shifted Inverse’
where is real
Given a ‘Generalized’ eigenvalue problem in the form then the following modes are available with the appropriate operator .
‘Regular Inverse’
‘Shifted Inverse’
, where is real
‘Buckling’
, where is real
‘Cayley’
, where is real
- ‘Standard’valueless
Default
The problem to be solved is either a standard eigenvalue problem, , or a generalized eigenvalue problem, . The option ‘Standard’ should be used when a standard eigenvalue problem is being solved and the option ‘Generalized’ should be used when a generalized eigenvalue problem is being solved.
- ‘Generalized’valueless
The problem to be solved is either a standard eigenvalue problem, , or a generalized eigenvalue problem, . The option ‘Standard’ should be used when a standard eigenvalue problem is being solved and the option ‘Generalized’ should be used when a generalized eigenvalue problem is being solved.
- ‘Tolerance’float
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’valueless
Default
The function
real_symm_proc()
can optionally compute the Schur vectors and/or the eigenvectors corresponding to the converged eigenvalues. To turn off computation of any vectors the option should be set. To compute only the Schur vectors (at very little extra cost), the option should be set and these will be returned in the array argument ofreal_symm_proc()
. To compute the eigenvectors (Ritz vectors) corresponding to the eigenvalue estimates, the option should be set and these will be returned in the array argument ofreal_symm_proc()
, if is set equal to then the Schur vectors in are overwritten by the eigenvectors computed byreal_symm_proc()
.
- Raises
- NagValueError
- (errno )
Ambiguous keyword:
- (errno )
Keyword not recognized:
- (errno )
Second keyword not recognized:
- Notes
real_symm_option
may be used to supply values for options toreal_symm_iter()
andreal_symm_proc()
. It is only necessary to callreal_symm_option
for those arguments whose values are to be different from their default values. One call toreal_symm_option
sets one argument value.Each option 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
Iteration Limit = 500
is an example of a string used to set an option. 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 int or float value. Such numbers may be up to contiguous characters in Fortran’s I, F, E or D format.
real_symm_option
does not have an equivalent function from the ARPACK package which passes options by directly setting values to scalar arguments or to specific elements of array arguments.real_symm_option
is intended to make the passing of options more transparent and follows the same principle as the single option setting functions in submoduleopt
.The setup function
real_symm_init()
must be called prior to the first call toreal_symm_option
and all calls toreal_symm_option
must precede the first call toreal_symm_iter()
, the reverse communication iterative solver.A complete list of options, their abbreviations, synonyms and default values is given in Other 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, Philadelphia