From 0345245e860375a32c9a437c4a9d9cae807134e9 Mon Sep 17 00:00:00 2001 From: Shashank Date: Mon, 29 May 2017 12:40:26 +0530 Subject: CMSCOPE changed --- modules/arnoldi/help/en_US/addchapter.sce | 11 + modules/arnoldi/help/en_US/dnaupd.xml | 882 ++++++++++++++++++++++++++++++ modules/arnoldi/help/en_US/dneupd.xml | 642 ++++++++++++++++++++++ modules/arnoldi/help/en_US/dsaupd.xml | 788 ++++++++++++++++++++++++++ modules/arnoldi/help/en_US/dseupd.xml | 463 ++++++++++++++++ modules/arnoldi/help/en_US/eigs.xml | 525 ++++++++++++++++++ modules/arnoldi/help/en_US/znaupd.xml | 799 +++++++++++++++++++++++++++ modules/arnoldi/help/en_US/zneupd.xml | 525 ++++++++++++++++++ modules/arnoldi/help/fr_FR/addchapter.sce | 11 + modules/arnoldi/help/ja_JP/addchapter.sce | 11 + modules/arnoldi/help/ja_JP/dnaupd.xml | 861 +++++++++++++++++++++++++++++ modules/arnoldi/help/ja_JP/dneupd.xml | 621 +++++++++++++++++++++ modules/arnoldi/help/ja_JP/dsaupd.xml | 765 ++++++++++++++++++++++++++ modules/arnoldi/help/ja_JP/dseupd.xml | 440 +++++++++++++++ modules/arnoldi/help/ja_JP/eigs.xml | 526 ++++++++++++++++++ modules/arnoldi/help/ja_JP/znaupd.xml | 780 ++++++++++++++++++++++++++ modules/arnoldi/help/ja_JP/zneupd.xml | 506 +++++++++++++++++ modules/arnoldi/help/pt_BR/addchapter.sce | 11 + modules/arnoldi/help/ru_RU/addchapter.sce | 11 + 19 files changed, 9178 insertions(+) create mode 100755 modules/arnoldi/help/en_US/addchapter.sce create mode 100755 modules/arnoldi/help/en_US/dnaupd.xml create mode 100755 modules/arnoldi/help/en_US/dneupd.xml create mode 100755 modules/arnoldi/help/en_US/dsaupd.xml create mode 100755 modules/arnoldi/help/en_US/dseupd.xml create mode 100755 modules/arnoldi/help/en_US/eigs.xml create mode 100755 modules/arnoldi/help/en_US/znaupd.xml create mode 100755 modules/arnoldi/help/en_US/zneupd.xml create mode 100755 modules/arnoldi/help/fr_FR/addchapter.sce create mode 100755 modules/arnoldi/help/ja_JP/addchapter.sce create mode 100755 modules/arnoldi/help/ja_JP/dnaupd.xml create mode 100755 modules/arnoldi/help/ja_JP/dneupd.xml create mode 100755 modules/arnoldi/help/ja_JP/dsaupd.xml create mode 100755 modules/arnoldi/help/ja_JP/dseupd.xml create mode 100755 modules/arnoldi/help/ja_JP/eigs.xml create mode 100755 modules/arnoldi/help/ja_JP/znaupd.xml create mode 100755 modules/arnoldi/help/ja_JP/zneupd.xml create mode 100755 modules/arnoldi/help/pt_BR/addchapter.sce create mode 100755 modules/arnoldi/help/ru_RU/addchapter.sce (limited to 'modules/arnoldi/help') diff --git a/modules/arnoldi/help/en_US/addchapter.sce b/modules/arnoldi/help/en_US/addchapter.sce new file mode 100755 index 000000000..a4b9b9af5 --- /dev/null +++ b/modules/arnoldi/help/en_US/addchapter.sce @@ -0,0 +1,11 @@ +// Scilab ( http://www.scilab.org/ ) - This file is part of Scilab +// Copyright (C) 2009 - DIGITEO +// +// This file must be used under the terms of the CeCILL. +// This source file is licensed as described in the file COPYING, which +// you should have received as part of this distribution. The terms +// are also available at +// http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt + +add_help_chapter("ARnoldi PACKage (ARPACK binding)",SCI+"/modules/arnoldi/help/en_US",%T); + diff --git a/modules/arnoldi/help/en_US/dnaupd.xml b/modules/arnoldi/help/en_US/dnaupd.xml new file mode 100755 index 000000000..da217d620 --- /dev/null +++ b/modules/arnoldi/help/en_US/dnaupd.xml @@ -0,0 +1,882 @@ + + + + dnaupd + + Interface for the Implicitly Restarted Arnoldi Iteration, to + compute approximations to a few eigenpairs of a real linear + operator + + This function is obsolete. Please use eigs + + + + + Calling Sequence + [IDO, RESID, V, IPARAM, IPNTR, WORKD, WORKL, INFO] = dnaupd(ID0, BMAT, N, WHICH, NEV, TOL, RESID, NCV, V, IPARAM, IPNTR, WORKD, WORKL, INFO) + + + Arguments + + + ID0 + + + Integer. (INPUT/OUTPUT) + + + Reverse communication flag. IDO must + be zero on the first call to dnaupd. IDO will be set internally to + indicate the type of operation to be performed. Control is then + given back to the calling routine which has the responsibility to + carry out the requested operation and call dnaupd with the result. + The operand is given in WORKD(IPNTR(1)), the result must be put in + WORKD(IPNTR(2)). + + + + + IDO = 0: first call to the reverse communication + interface. + + + + + IDO = -1: compute Y = OP * X where IPNTR(1) is the pointer + into WORKD for X, IPNTR(2) is the pointer into WORKD for Y. This + is for the initialization phase to force the starting vector + into the range of OP. + + + + + IDO = 1: compute Y = OP * X where IPNTR(1) is the pointer + into WORKD for X, IPNTR(2) is the pointer into WORKD for Y. In + mode 3 and 4, the vector B * X is already available in + WORKD(ipntr(3)). It does not need to be recomputed in forming OP + * X. + + + + + IDO = 2: compute Y = B * X where IPNTR(1) is the pointer + into WORKD for X, IPNTR(2) is the pointer into WORKD for + Y. + + + + + IDO = 3: compute the IPARAM(8) real and imaginary parts of + the shifts where INPTR(14) is the pointer into WORKL for placing + the shifts. See Remark 5 below. + + + + IDO = 99: done. + + + + + + BMAT + + + Character. (INPUT) + + + specifies the type of the matrix B that defines the + semi-inner product for the operator OP. + + + + 'I' - standard eigenvalue problem A * x = lambda * x + + + + 'G' - generalized eigenvalue problem A * x = + lambda * B * x + + + + + + + N + + Integer. (INPUT) + dimension of the eigenproblem. + + + + WHICH + + + string of length 2. (INPUT) + + + Specifies which of the Ritz values of OP to + compute. + + + + + 'LM' - want the NEV eigenvalues of largest + magnitude. + + + + + 'SM' - want the NEV eigenvalues of smallest + magnitude. + + + + + 'LR' - want the NEV eigenvalues of largest real + part. + + + + + 'SR' - want the NEV eigenvalues of smallest real + part. + + + + + 'LI' - want the NEV eigenvalues of largest imaginary + part. + + + + + 'SI' - want the NEV eigenvalues of smallest imaginary + part. + + + + + + + NEV + + + Integer. (INPUT) + + + number of eigenvalues of OP to be computed. 0 < + NEV < N-1. + + + + + TOL + + + scalar. (INPUT) + + + Stopping criterion: the relative accuracy of the Ritz + value is considered acceptable if BOUNDS(I) <= TOL*ABS(RITZ(I)). + If TOL <= 0. is passed the machine precision is set. + + + + + RESID + + array of length N. (INPUT/OUTPUT) + + On INPUT: If INFO = 0, a random initial residual vector is + used, else RESID contains the initial residual vector, possibly from + a previous run. + + On OUTPUT: RESID contains the final residual vector. + + + + NCV + + + Integer. (INPUT) + + + number of columns of the matrix V. NCV must satisfy + the two inequalities 2 <= NCV - NEV and NCV <= N. + + + This will indicate how many Arnoldi vectors are generated at + each iteration. + + + After the startup phase in which NEV Arnoldi vectors are + generated, the algorithm generates approximately NCV - NEV Arnoldi + vectors at each subsequent update iteration. Most of the cost in + generating each Arnoldi vector is in the matrix-vector operation + OP * x. + + + NOTE: 2 <= NCV - NEV in order that complex conjugate pairs of + Ritz values are kept together. (See remark 4 below) + + + + + V + + + N by NCV array. (OUTPUT) + + + Contains the final set of Arnoldi basis + vectors. + + + + + IPARAM + + array of length 11. (INPUT/OUTPUT) + + + + IPARAM(1) = ISHIFT: method for selecting the implicit + shifts. The shifts selected at each iteration are used to + restart the Arnoldi iteration in an implicit fashion. + + + + + ISHIFT = 0: the shifts are provided by the user via + reverse communication. The real and imaginary parts of the + NCV eigenvalues of the Hessenberg matrix H are returned in + the part of the WORKL array corresponding to RITZR and + RITZI. See remark 5 below. + + + + + ISHIFT = 1: exact shifts with respect to the current + Hessenberg matrix H. This is equivalent to restarting the + iteration with a starting vector that is a linear + combination of approximate Schur vectors associated with the + "wanted" Ritz values. + + + + + + IPARAM(2) = LEVEC. No longer referenced. + + + IPARAM(3) = MXITER + + On INPUT: maximum number of Arnoldi update iterations + allowed. + + + On OUTPUT: actual number of Arnoldi update iterations + taken. + + + + + IPARAM(4) = NB: blocksize to be used in the recurrence. + The code currently works only for NB = 1. + + + + + IPARAM(5) = NCONV: number of "converged" Ritz values. This + represents the number of Ritz values that satisfy the + convergence criterion. + + + + + IPARAM(6) = IUPD No longer referenced. Implicit restarting + is ALWAYS used. + + + + + IPARAM(7) = MODE On INPUT determines what type of + eigenproblem is being solved. Must be 1,2,3,4; See under + Description of dnaupd for the five modes available. + + + + + IPARAM(8) = NP When ido = 3 and the user provides shifts + through reverse communication (IPARAM(1)=0), dnaupd returns NP, + the number of shifts the user is to provide. + + 0 < NP <= NCV-NEV. See Remark 5 below. + + + IPARAM(9) = NUMOP, + IPARAM(10) = NUMOPB, + IPARAM(11) = NUMREO, + + On OUTPUT: NUMOP = total number of OP*x operations, NUMOPB + = total number of B*x operations if BMAT='G', NUMREO = total + number of steps of re-orthogonalization. + + + + + + + IPNTR + + + array of length 14. (OUTPUT) + + + Pointer to mark the starting locations in + the WORKD and WORKL arrays for matrices/vectors used by the Arnoldi + iteration. + + + + + IPNTR(1): pointer to the current operand vector X in + WORKD. + + + + + IPNTR(2): pointer to the current result vector Y in + WORKD. + + + + + IPNTR(3): pointer to the vector B * X in WORKD when used + in the shift-and-invert mode. + + + + + IPNTR(4): pointer to the next available location in WORKL + that is untouched by the program. + + + + + IPNTR(5): pointer to the NCV by NCV upper Hessenberg + matrix H in WORKL. + + + + + IPNTR(6): pointer to the real part of the ritz value array + RITZR in WORKL. + + + + + IPNTR(7): pointer to the imaginary part of the ritz value + array RITZI in WORKL. + + + + + IPNTR(8): pointer to the Ritz estimates in array WORKL + associated with the Ritz values located in RITZR and RITZI in + WORKL. + + + + + IPNTR(14): pointer to the NP shifts in WORKL. See Remark 5 + below. + + + + + Note: IPNTR(9:13) is only referenced by dneupd . See Remark + 2. + + + + + IPNTR(9): pointer to the real part of the NCV RITZ values + of the original system. + + + + + IPNTR(10): pointer to the imaginary part of the NCV RITZ + values of the original system. + + + + + IPNTR(11): pointer to the NCV corresponding error + bounds. + + + + + IPNTR(12):pointer to the NCV by NCV upper quasi-triangular + Schur matrix for H. + + + + + IPNTR(13): pointer to the NCV by NCV matrix of + eigenvectors of the upper Hessenberg matrix H. Only referenced + by dneupd if RVEC = 1 See Remark 2 below. + + + + + + + WORKD + + + Double precision work array of length 3 * N. (REVERSE + COMMUNICATION) + + + Distributed array to be used in the basic Arnoldi iteration + for reverse communication. The user should not use WORKD as + temporary workspace during the iteration. Upon termination + WORKD(1:N) contains B*RESID(1:N). If an invariant subspace + associated with the converged Ritz values is desired, see remark 2 + below, subroutine dneupd uses this output. See Data Distribution + Note below. + + + + + WORKL + + + work array of length at least 3 * NCV ** 2 + 6 * NCV. + (OUTPUT/WORKSPACE) + + + Private (replicated) array on each PE or array + allocated on the front end. See Data Distribution Note below. + + + + + INFO + + Integer. (INPUT/OUTPUT) + + If INFO == 0, a randomly initial residual vector is used, else + RESID contains the initial residual vector, possibly from a previous + run. + + Error flag on output. + + + 0: Normal exit. + + + + 1: Maximum number of iterations taken. All possible + eigenvalues of OP has been found. IPARAM(5) returns the number + of wanted converged Ritz values. + + + + + 2: No longer an informational error. Deprecated starting + with release 2 of ARPACK. + + + + + 3: No shifts could be applied during a cycle of the + Implicitly restarted Arnoldi iteration. One possibility is to + increase the size of NCV relative to NEV. See remark 4 + below. + + + + -1: N must be positive. + + + -2: NEV must be positive. + + + -3: NCV-NEV >= 2 and less than or equal to N. + + + + -4: The maximum number of Arnoldi update iterations + allowed must be greater than zero. + + + + + -5: WHICH must be one of 'LM', 'SM', 'LR', 'SR', 'LI', + 'SI'. + + + + -6: BMAT must be one of 'I' or 'G'. + + + + -7: Length of private work array WORKL is not + sufficient. + + + + + -8: Error return from LAPACK eigenvalue + calculation. + + + + -9: Starting vector is zero. + + + -10: IPARAM(7) must be 1, 2, 3, 4. + + + -11: IPARAM(7) = 1 and BMAT = 'G' are incompatable. + + + -12: IPARAM(1) must be equal to 0 or 1. + + + + -9999: Could not build an Arnoldi factorization. IPARAM(5) + returns the size of the current Arnoldi factorization. The user + is advised to check that enough workspace and array storage has + been allocated. + + + + + + + + + Description + + Reverse communication interface for the Implicitly Restarted Arnoldi + iteration. This subroutine computes approximations to a few eigenpairs of + a linear operator "OP" with respect to a semi-inner product defined by a + symmetric positive semi-definite real matrix B. B may be the identity + matrix. NOTE: If the linear operator "OP" is real and symmetric with + respect to the real positive semi-definite symmetric matrix B, i.e. B*OP = + (OP`)*B, then subroutine dsaupd should be used instead. + + + The computed approximate eigenvalues are called Ritz values and the + corresponding approximate eigenvectors are called Ritz vectors. + + + dnaupd is usually called iteratively to solve one of the following + problems: + + + + + Mode 1: A*x = lambda*x. + OP = A , B = + I + + . + + + + + Mode 2: A*x = lambda*M*x, M symmetric positive definite + OP = inv[M]*A, B = M. (If M can be factored see + remark 3 below) + + + + + Mode 3: A*x = lambda*M*x, M symmetric positive semi-definite. + OP = Real_Part{ inv[A - sigma*M]*M }, B = M. + shift-and-invert mode (in real arithmetic) + + + If OP*x = amu*x, then + + + + amu = 1/2 * [ 1/(lambda-sigma) + + 1/(lambda-conjg(sigma))] + + . + + + Note: If sigma is real, i.e. imaginary part of sigma is zero; + + Real_Part{ inv[A - sigma*M]*M } == inv[A - + sigma*M]*M + + + amu == + 1/(lambda-sigma) + + . + + + + + Mode 4: A*x = lambda*M*x, M symmetric semi-definite + OP + = Imaginary_Part{ inv[A - sigma*M]*M } , B = M + + . + shift-and-invert mode (in real arithmetic) + + + If OP*x = amu*x, then + amu = 1/2i * [ + 1/(lambda-sigma) - 1/(lambda-conjg(sigma)) ] + + . + + + + + Both mode 3 and 4 give the same enhancement to eigenvalues close to + the (complex) shift sigma. However, as lambda goes to infinity, the + operator OP in mode 4 dampens the eigenvalues more strongly than does OP + defined in mode 3. + + + NOTE: The action of w <- inv[A - sigma * M] * v or w <- inv[M] * v + should be accomplished either by a direct method using a sparse matrix + factorization and solving [A - sigma * M] * w = v or + M * w = v, or through an iterative method for solving + these systems. If an iterative method is used, the convergence test must + be more stringent than the accuracy requirements for the eigenvalue + approximations. + + + + Example + + 99) + // Repeatedly call the routine DNAUPD and take actions indicated by parameter IDO until + // either convergence is indicated or maxitr has been exceeded. + + [ido, resid, v, iparam, ipntr, workd, workl, info_dnaupd] = dnaupd(ido, bmat, nx, which, nev, tol, resid, ncv, v, iparam, ipntr, workd, workl, info_dnaupd); + + if(info_dnaupd < 0) + printf('\nError with dnaupd, info = %d\n',info_dnaupd); + printf('Check the documentation of dnaupd\n\n'); + end + + if(ido == -1 | ido == 1) + // Perform matrix vector multiplication + workd(ipntr(2):ipntr(2) + nx -1) = A * workd(ipntr(1):ipntr(1) + nx - 1); + end +end + +// Post-Process using DNEUPD. +rvec = 1; +howmany = 'A'; +info_dneupd = 0; + +[dr, di, z, resid, v, iparam, ipntr, workd, workl, info_dneupd] = dneupd(rvec, howmany, _select, dr, di, z, sigmar, sigmai, workev, ... + bmat, nx, which, nev, tol, resid, ncv, v, ... + iparam, ipntr, workd, workl, info_dneupd); + +if(info_dneupd < 0) + printf('\nError with dneupd, info = %d\n', info_dneupd); + printf('Check the documentation of dneupd.\n\n'); +end + +printf('\nDNSIMP\n'); +printf('======\n'); +printf('\n'); +printf('Size of the matrix is %d\n', nx); +printf('The number of Ritz values requested is %d\n', nev); +printf('The number of Arnoldi vectors generated (NCV) is %d\n', ncv); +printf('What portion of the spectrum: %s\n', which); +printf('The number of Implicit Arnoldi update iterations taken is %d\n', iparam(3)); +printf('The number of OP*x is %d\n', iparam(9)); +printf('The convergence criterion is %d\n', tol); + +]]> + + + + Remarks + + 1. The computed Ritz values are approximate eigenvalues of OP. The + selection of WHICH should be made with this in mind when Mode = 3 and 4. + After convergence, approximate eigenvalues of the original problem may be + obtained with the ARPACK subroutine dneupd. + + + 2. If a basis for the invariant subspace corresponding to the + converged Ritz values is needed, the user must call dneupd immediately + following completion of dnaupd. This is new starting with release 2 of + ARPACK. + + + 3. If M can be factored into a Cholesky factorization M = LL` then + Mode = 2 should not be selected. Instead one should use Mode = 1 with OP = + inv(L) * A * inv(L`). Appropriate triangular linear systems should be solved + with L and L` rather than computing inverses. After convergence, an + approximate eigenvector z of the original problem is recovered by solving + L`z = x where x is a Ritz vector of OP. + + + 4. At present there is no a-priori analysis to guide the selection + of NCV relative to NEV. The only formal requirement is that NCV > NEV + + 2. However, it is recommended that NCV >= 2 * NEV + 1. If many problems of + the same type are to be solved, one should experiment with increasing NCV + while keeping NEV fixed for a given test problem. This will usually + decrease the required number of OP*x operations but it also increases the + work and storage required to maintain the orthogonal basis vectors. The + optimal "cross-over" with respect to CPU time is problem dependent and + must be determined empirically. See Chapter 8 of Reference 2 for further + information. + + + 5. When IPARAM(1) = 0, and IDO = 3, the user needs to provide the NP + = IPARAM(8) real and imaginary parts of the shifts in locations + + + real part imaginary part + ----------------------- -------------- + 1 WORKL(IPNTR(14)) WORKL(IPNTR(14) + NP) + 2 WORKL(IPNTR(14) + 1) WORKL(IPNTR(14) + NP + 1) + . . + . . + . . + NP WORKL(IPNTR(14) + NP - 1) WORKL(IPNTR(14) + 2 * NP - 1). + + + Only complex conjugate pairs of shifts may be applied and the pairs + must be placed in consecutive locations. The real part of the eigenvalues + of the current upper Hessenberg matrix are located in WORKL(IPNTR(6)) + through WORKL(IPNTR(6) + NCV - 1) and the imaginary part in WORKL(IPNTR(7)) + through WORKL(IPNTR(7) + NCV - 1). They are ordered according to the order + defined by WHICH. The complex conjugate pairs are kept together and the + associated Ritz estimates are located in WORKL(IPNTR(8)), + WORKL(IPNTR(8)+1), ... , WORKL(IPNTR(8) + NCV - 1). + + + + See Also + + + dsaupd + + + dneupd + + + + + Bibliography + + 1. D.C. Sorensen, "Implicit Application of Polynomial Filters in a + k-Step Arnoldi Method", SIAM J. Matr. Anal. Apps., 13 (1992), pp + 357-385. + + + 2. R.B. Lehoucq, "Analysis and Implementation of an Implicitly + Restarted Arnoldi Iteration", Rice University Technical Report TR95-13, + Department of Computational and Applied Mathematics. + + + 3. B.N. Parlett, "The Symmetric Eigenvalue Problem". Prentice-Hall, + 1980. + + + 4. B.N. Parlett, B. Nour-Omid, "Towards a Black Box Lanczos + Program", Computer Physics Communications, 53 (1989), pp 169-179. + + + 5. B. Nour-Omid, B.N. Parlett, T. Ericson, P.S. Jensen, "How to + Implement the Spectral Transformation", Math. Comp., 48 (1987), pp + 663-673. + + + 6. R.G. Grimes, J.G. Lewis and H.D. Simon, "A Shifted Block Lanczos + Algorithm for Solving Sparse Symmetric Generalized Eigenproblems", SIAM J. + Matr. Anal. Apps., January (1993). + + + 7. L. Reichel, W.B. Gragg, "Algorithm 686: FORTRAN Subroutines for + Updating the QR decomposition", ACM TOMS, December 1990, Volume 16 Number + 4, pp 369-377. + + + 8. R.B. Lehoucq, D.C. Sorensen, "Implementation of Some Spectral + Transformations in a k-Step Arnoldi Method". In Preparation. + + + + Used Functions + Based on ARPACK routine dnaupd + + + History + + + 5.4.0 + + Function obsolete for eigs. + + + + + diff --git a/modules/arnoldi/help/en_US/dneupd.xml b/modules/arnoldi/help/en_US/dneupd.xml new file mode 100755 index 000000000..de24bcbd5 --- /dev/null +++ b/modules/arnoldi/help/en_US/dneupd.xml @@ -0,0 +1,642 @@ + + + + dneupd + + Interface for the Implicitly Restarted Arnoldi Iteration, to + compute the converged approximations to eigenvalues of A * z = lambda * B * z + approximations to a few eigenpairs of a real linear operator + + This function is obsolete. Please use eigs + + + + + Calling Sequence + + [Dr, Di, Z, RESID, V, IPARAM, IPNTR, WORKD, WORKL, INFO] = dneupd(RVEC, HOWMANY, SELECT, Dr, Di, Z, SIGMAr, SIGMAi, WORKev, + BMAT, N, WHICH, NEV, TOL, RESID, NCV, V, IPARAM, IPNTR, WORKD, WORKL, INFO) + + + + Arguments + + + RVEC + + Integer. (INPUT) + + Specifies whether a basis for the invariant subspace + corresponding to the converged Ritz value approximations for the + eigenproblem A * z = lambda * B * z is computed. + + + + RVEC = 0 Compute Ritz values only. + + + RVEC = 1 Compute the Ritz vectors or Schur vectors. + + + See Remarks below. + + + + HOWMANY + + Character. (INPUT) + + Specifies the form of the basis for the invariant subspace + corresponding to the converged Ritz values that is to be + computed. + + + + 'A': Compute NEV Ritz vectors; + + + 'P': Compute NEV Schur vectors; + + + + 'S': compute some of the Ritz vectors, specified by the + integer array SELECT. + + + + + + + SELECT + + Integer array of dimension NCV. (INPUT) + + If HOWMANY = 'S', SELECT specifies the Ritz vectors to be + computed. To select the Ritz vector corresponding to a Ritz value + (DR(j), DI(j)), SELECT(j) must be set to 1. + + + If HOWMANY = 'A' or 'P', SELECT is used as internal + workspace. + + + + + DR + + Double precision array of dimension NEV + 1. (OUTPUT) + + If IPARAM(7) = 1, 2 or 3 and SIGMAI = 0.0 then on exit: DR + contains the real part of the Ritz approximations to the eigenvalues + of A * z = lambda * B * z. + + + If IPARAM(7) = 3, 4 and SIGMAI is not equal to zero, then on + exit: DR contains the real part of the Ritz values of OP computed by + DNAUPD. + + + A further computation must be performed by the user to + transform the Ritz values computed for OP by DNAUPD to those of the + original system A * z = lambda * B * z. See remark 3 below. + + + + + DI + + Double precision array of dimension NEV + 1. (OUTPUT) + + On exit, DI contains the imaginary part of the Ritz value + approximations to the eigenvalues of A * z = lambda * B * z associated + with DR. + + + NOTE: When Ritz values are complex, they will come in complex + conjugate pairs. If eigenvectors are requested, the corresponding + Ritz vectors will also come in conjugate pairs and the real and + imaginary parts of these are represented in two consecutive columns + of the array Z (see below). + + + + + Z + + Double precision N by NEV + 1 array + if RVEC = 1 and HOWMANY = 'A'. (OUTPUT) + + On exit, if RVEC = 1 and HOWMANY = 'A', then the columns of Z + represent approximate eigenvectors (Ritz vectors) corresponding to + the NCONV = IPARAM(5) Ritz values for eigensystem A * z = lambda * B * z. + The complex Ritz vector associated with the Ritz value with positive + imaginary part is stored in two consecutive columns. The first + column holds the real part of the Ritz vector and the second column + holds the imaginary part. The Ritz vector associated with the Ritz + value with negative imaginary part is simply the complex conjugate + of the Ritz vector associated with the positive imaginary part. + + + If RVEC = 0 or HOWMANY = 'P', then Z is not referenced. + + + NOTE: If if RVEC = 1 and a Schur basis is not required, the + array Z may be set equal to first NEV+1 columns of the Arnoldi basis + array V computed by DNAUPD . In this case the Arnoldi basis will be + destroyed and overwritten with the eigenvector basis. + + + + + SIGMAR + + Double precision (INPUT) + + If IPARAM(7) = 3 or 4, represents the real part of the + shift. + + Not referenced if IPARAM(7) = 1 or 2. + + + + SIGMAI + + Double precision (INPUT) + + If IPARAM(7) = 3 or 4, represents the imaginary part of the + shift. + + + Not referenced if IPARAM(7) = 1 or 2. See remark 3 + below. + + + + + WORKEV + + + Double precision work array of dimension 3 * NCV. + (WORKSPACE) + + + + + + NOTE: The remaining arguments BMAT, N, WHICH, NEV, TOL, RESID, NCV, + V, IPARAM, IPNTR, WORKD, WORKL, LWORKL, INFO must be passed directly to + DNEUPD following the last call to DNAUPD . + + + These arguments MUST NOT BE MODIFIED between the last call to + DNAUPD and the call to DNEUPD . + + + Three of these parameters (V, WORKL, INFO) are also output + parameters. + + + + V + + Double precision N by NCV array. (INPUT/OUTPUT) + + Upon INPUT: the NCV columns of V contain the Arnoldi basis + vectors for OP as constructed by DNAUPD. + + + Upon OUTPUT: If RVEC = 1 the first NCONV = IPARAM(5) columns + contain approximate Schur vectors that span the desired invariant + subspace. See Remark 2 below. + + + NOTE: If the array Z has been set equal to first NEV+1 columns + of the array V and RVEC = 1 and HOWMANY= 'A', then the Arnoldi basis + held by V has been overwritten by the desired Ritz vectors. If a + separate array Z has been passed then the first NCONV = IPARAM(5) + columns of V will contain approximate Schur vectors that span the + desired invariant subspace. + + + + + WORKL + + + Double precision work array of length LWORKL. + (OUTPUT/WORKSPACE) + + + WORKL(1:ncv*ncv+3*ncv) contains information obtained in dnaupd + . They are not changed by dneupd . + + + WORKL(ncv*ncv+3*ncv+1:3*ncv*ncv+6*ncv) holds the real and + imaginary part of the untransformed Ritz values, the upper + quasi-triangular matrix for H, and the associated matrix + representation of the invariant subspace for H. + + + Note: IPNTR(9:13) contains the pointer into WORKL for + addresses of the above information computed by dneupd . + + + + + IPNTR(9): pointer to the real part of the NCV RITZ values + of the original system. + + + + + IPNTR(10): pointer to the imaginary part of the NCV RITZ + values of the original system. + + + + + IPNTR(11): pointer to the NCV corresponding error + bounds. + + + + + IPNTR(12): pointer to the NCV by NCV upper + quasi-triangular Schur matrix for H. + + + + + IPNTR(13): pointer to the NCV by NCV matrix of + eigenvectors of the upper Hessenberg matrix H. Only referenced + by dneupd if RVEC = 1 See Remark 2 below. + + + + + + + INFO + + Integer. (OUTPUT). + Error flag on output. + + + 0: Normal exit. + + + + 1: The Schur form computed by LAPACK routine dlahqr could + not be reordered by LAPACK routine dtrsen . Re-enter subroutine + dneupd with IPARAM(5)=NCV and increase the size of the arrays DR + and DI to have dimension at least dimension NCV and allocate at + least NCV columns for Z. + + + NOTE: Not necessary if Z and V share the same space. + Please notify the authors if this error occurs. + + + + -1: N must be positive. + + + -2: NEV must be positive. + + + -3: NCV-NEV >= 2 and less than or equal to N. + + + + -5: WHICH must be one of 'LM', 'SM', 'LR', 'SR', 'LI', + 'SI'. + + + + -6: BMAT must be one of 'I' or 'G'. + + + + -7: Length of private work WORKL array is not + sufficient. + + + + + -8: Error return from calculation of a real Schur form. + Informational error from LAPACK routine dlahqr. + + + + + -9: Error return from calculation of eigenvectors. + Informational error from LAPACK routine dtrevc. + + + + -10: IPARAM(7) must be 1, 2, 3, 4. + + + -11: IPARAM(7) = 1 and BMAT = 'G' are incompatible. + + + -12: HOWMANY = 'S' not yet implemented. + + + -13: HOWMANY must be one of 'A' or 'P' if RVEC = 1. + + + + -14: DNAUPD did not find any eigenvalues to sufficient + accuracy. + + + + + -15: DNEUPD got a different count of the number of + converged Ritz values than DNAUPD got. This indicates the user + probably made an error in passing data from DNAUPD to DNEUPD or + that the data was modified before entering DNEUPD. + + + + + + + + + Description + + This subroutine returns the converged approximations to eigenvalues + of A * z = lambda * B * z and (optionally): + + + + The corresponding approximate eigenvectors; + + + + An orthonormal basis for the associated approximate invariant + subspace; + + + + Both. + + + + There is negligible additional cost to obtain eigenvectors. An + orthonormal basis is always computed. + + + There is an additional storage cost of n*nev if both are requested + (in this case a separate array Z must be supplied). + + + The approximate eigenvalues and eigenvectors of A * z = lambda * B * z are + derived from approximate eigenvalues and eigenvectors of of the linear + operator OP prescribed by the MODE selection in the call to DNAUPD. DNAUPD + must be called before this routine is called. + + + These approximate eigenvalues and vectors are commonly called Ritz + values and Ritz vectors respectively. They are referred to as such in the + comments that follow. + + + The computed orthonormal basis for the invariant subspace + corresponding to these Ritz values is referred to as a Schur basis. + + + See documentation in the header of the subroutine DNAUPD for + definition of OP as well as other terms and the relation of computed Ritz + values and Ritz vectors of OP with respect to the given problem A * z = + lambda * B * z. + + + For a brief description, see definitions of IPARAM(7), MODE and + WHICH in the documentation of DNAUPD . + + + + Remarks + + + Currently only HOWMNY = 'A' and 'P' are implemented. + Let trans(X) denote the transpose of X. + + + + Schur vectors are an orthogonal representation for the basis of + Ritz vectors. Thus, their numerical properties are often superior. If + RVEC = 1 then the relationship + + + A * V(:,1:IPARAM(5)) = V(:,1:IPARAM(5)) * T, and + trans(V(:,1:IPARAM(5))) * V(:,1:IPARAM(5)) = I + + are approximately satisfied. + + Here T is the leading submatrix of order IPARAM(5) of the real + upper quasi-triangular matrix stored workl(ipntr(12)). That is, T is + block upper triangular with 1-by-1 and 2-by-2 diagonal blocks; each + 2-by-2 diagonal block has its diagonal elements equal and its + off-diagonal elements of opposite sign. Corresponding to each 2-by-2 + diagonal block is a complex conjugate pair of Ritz values. The real + Ritz values are stored on the diagonal of T. + + + + + If IPARAM(7) = 3 or 4 and SIGMAI is not equal zero, then the + user must form the IPARAM(5) Rayleigh quotients in order to transform + the Ritz values computed by DNAUPD for OP to those of A * z = + lambda * B * z. Set RVEC = 1 and HOWMNY = 'A', and compute + + trans(Z(:,I)) * A * Z(:,I) if DI(I) = 0. + + If DI(I) is not equal to zero and DI(I+1) = - D(I), then the + desired real and imaginary parts of the Ritz value are + + + trans(Z(:,I)) * A * Z(:,I) + trans(Z(:,I+1)) * A * Z(:,I+1), + + + trans(Z(:,I)) * A * Z(:,I+1) - trans(Z(:,I+1)) * A * Z(:,I), + + respectively. + + Another possibility is to set RVEC = 1 and HOWMANY = 'P' and + compute + + trans(V(:,1:IPARAM(5))) * A * V(:,1:IPARAM(5)) + + and then an upper quasi-triangular matrix of order IPARAM(5) is + computed. See remark 2 above. + + + + + + Example + + 99) + // Repeatedly call the routine DNAUPD and take actions indicated by parameter IDO until + // either convergence is indicated or maxitr has been exceeded. + + [ido, resid, v, iparam, ipntr, workd, workl, info_dnaupd] = dnaupd(ido, bmat, nx, which, nev, tol, resid, ncv, v, iparam, ipntr, workd, workl, info_dnaupd); + + if(info_dnaupd < 0) + printf('\nError with dnaupd, info = %d\n',info_dnaupd); + printf('Check the documentation of dnaupd\n\n'); + end + + if(ido == -1 | ido == 1) + // Perform matrix vector multiplication + workd(ipntr(2):ipntr(2) + nx -1) = A * workd(ipntr(1):ipntr(1) + nx - 1); + end +end + +// Post-Process using DNEUPD. +rvec = 1; +howmany = 'A'; +info_dneupd = 0; + +[dr, di, z, resid, v, iparam, ipntr, workd, workl, info_dneupd] = dneupd(rvec, howmany, _select, dr, di, z, sigmar, sigmai, workev, ... + bmat, nx, which, nev, tol, resid, ncv, v, ... + iparam, ipntr, workd, workl, info_dneupd); + +if(info_dneupd < 0) + printf('\nError with dneupd, info = %d\n', info_dneupd); + printf('Check the documentation of dneupd.\n\n'); +end + +printf('\nDNSIMP\n'); +printf('======\n'); +printf('\n'); +printf('Size of the matrix is %d\n', nx); +printf('The number of Ritz values requested is %d\n', nev); +printf('The number of Arnoldi vectors generated (NCV) is %d\n', ncv); +printf('What portion of the spectrum: %s\n', which); +printf('The number of Implicit Arnoldi update iterations taken is %d\n', iparam(3)); +printf('The number of OP*x is %d\n', iparam(9)); +printf('The convergence criterion is %d\n', tol); + +]]> + + + + See Also + + + dsaupd + + + dnaupd + + + + + Bibliography + + 1. D.C. Sorensen, "Implicit Application of Polynomial Filters in a + k-Step Arnoldi Method", SIAM J. Matr. Anal. Apps., 13 (1992), pp + 357-385. + + + 2. R.B. Lehoucq, "Analysis and Implementation of an Implicitly + Restarted Arnoldi Iteration", Rice University Technical Report TR95-13, + Department of Computational and Applied Mathematics. + + + 3. B.N. Parlett, "The Symmetric Eigenvalue Problem". Prentice-Hall, + 1980. + + + 4. B.N. Parlett, B. Nour-Omid, "Towards a Black Box Lanczos + Program", Computer Physics Communications, 53 (1989), pp 169-179. + + + 5. B. Nour-Omid, B.N. Parlett, T. Ericson, P.S. Jensen, "How to + Implement the Spectral Transformation", Math. Comp., 48 (1987), pp + 663-673. + + + 6. R.G. Grimes, J.G. Lewis and H.D. Simon, "A Shifted Block Lanczos + Algorithm for Solving Sparse Symmetric Generalized Eigenproblems", SIAM J. + Matr. Anal. Apps., January (1993). + + + 7. L. Reichel, W.B. Gragg, "Algorithm 686: FORTRAN Subroutines for + Updating the QR decomposition", ACM TOMS, December 1990, Volume 16 Number + 4, pp 369-377. + + + 8. R.B. Lehoucq, D.C. Sorensen, "Implementation of Some Spectral + Transformations in a k-Step Arnoldi Method". In Preparation. + + + + Used Functions + Based on ARPACK routine dneupd + + + History + + + 5.4.0 + + Function obsolete for eigs. + + + + + diff --git a/modules/arnoldi/help/en_US/dsaupd.xml b/modules/arnoldi/help/en_US/dsaupd.xml new file mode 100755 index 000000000..a0add0bd4 --- /dev/null +++ b/modules/arnoldi/help/en_US/dsaupd.xml @@ -0,0 +1,788 @@ + + + + dsaupd + + Interface for the Implicitly Restarted Arnoldi Iteration, to + compute approximations to a few eigenpairs of a real and symmetric linear + operator + + This function is obsolete. Please use eigs + + + + + Calling Sequence + [IDO, RESID, V, IPARAM, IPNTR, WORKD, WORKL, INFO] = dsaupd(ID0, BMAT, N, WHICH, NEV, TOL, RESID, NCV, V, IPARAM, IPNTR, WORKD, WORKL, INFO) + + + Arguments + + + ID0 + + Integer. (INPUT/OUTPUT) + + Reverse communication flag. IDO must be zero on the first call + to dsaupd . IDO will be set internally to indicate the type of + operation to be performed. Control is then given back to the calling + routine which has the responsibility to carry out the requested + operation and call dsaupd with the result. + + + The operand is given in WORKD(IPNTR(1)), the result must be put + in WORKD(IPNTR(2)). (If Mode = 2 see remark 5 below) + + + + + IDO = 0: first call to the reverse communication + interface. + + + + + IDO = -1: compute Y = OP * X where IPNTR(1) is the pointer + into WORKD for X, IPNTR(2) is the pointer into WORKD for Y. This + is for the initialization phase to force the starting vector + into the range of OP. + + + + + IDO = 1: compute Y = OP * X where IPNTR(1) is the pointer + into WORKD for X, IPNTR(2) is the pointer into WORKD for Y. In + mode 3, 4 and 5, the vector B * X is already available in + WORKD(ipntr(3)). It does not need to be recomputed in forming OP + * X. + + + + + IDO = 2: compute Y = B * X where IPNTR(1) is the pointer + into WORKD for X, IPNTR(2) is the pointer into WORKD for + Y. + + + + + IDO = 3: compute the IPARAM(8) shifts where IPNTR(11) is + the pointer into WORKL for placing the shifts. See remark 6 + below. + + + + IDO = 99: done + + + + + + BMAT + + Character. (INPUT) + + Specifies the type of the matrix B that defines the semi-inner + product for the operator OP. + + + + 'I': standard eigenvalue problem A * x = lambda * x + + + + 'G': generalized eigenvalue problem A * x = + lambda * B * x + + + + + + + N + + Integer. (INPUT) + Dimension of the eigenproblem. + + + + WHICH + + String of length 2. (INPUT) + Specifies which of the Ritz values of OP to compute. + + + + 'LA' - compute the NEV largest (algebraic) + eigenvalues. + + + + + 'SA' - compute the NEV smallest (algebraic) + eigenvalues. + + + + + 'LM' - compute the NEV largest (in magnitude) + eigenvalues. + + + + + 'SM' - compute the NEV smallest (in magnitude) + eigenvalues. + + + + + 'BE' - compute NEV eigenvalues, half from each end of the + spectrum. When NEV is odd, compute one more from the high end + than from the low end. (see remark 1 below) + + + + + + + NEV + + Integer. (INPUT) + + Number of eigenvalues of OP to be computed. 0 < NEV < + N. + + + + + TOL + + scalar. (INPUT) + + Stopping criterion: the relative accuracy of the Ritz value is + considered acceptable if BOUNDS(I) <= TOL * ABS(RITZ(I)). If TOL + <= 0. is passed the machine precision is set. + + + + + RESID + + Array of length N. (INPUT/OUTPUT) + + On INPUT: If INFO = 0, a random initial residual vector is + used, else RESID contains the initial residual vector, possibly from + a previous run. + + On OUTPUT: RESID contains the final residual vector. + + + + NCV + + Integer. (INPUT) + + Number of columns of the matrix V (less than or equal to N). + + + This will indicate how many Lanczos vectors are generated at + each iteration. After the startup phase in which NEV Lanczos vectors + are generated, the algorithm generates NCV - NEV Lanczos vectors at + each subsequent update iteration. Most of the cost in generating + each Lanczos vector is in the matrix-vector product OP * x. (See + remark 4 below). + + + + + V + + N by NCV array. (OUTPUT) + The NCV columns of V contain the Lanczos basis vectors. + + + + IPARAM + + array of length 11. (INPUT/OUTPUT) + + + + IPARAM(1) = ISHIFT: method for selecting the implicit + shifts. The shifts selected at each iteration are used to + restart the Arnoldi iteration in an implicit fashion. + + + + + ISHIFT = 0: the shifts are provided by the user via + reverse communication. The NCV eigenvalues of the current + tridiagonal matrix T are returned in the part of WORKL array + corresponding to RITZ. See remark 6 below. + + + + + ISHIFT = 1: exact shifts with respect to the reduced + tridiagonal matrix T. This is equivalent to restarting the + iteration with a starting vector that is a linear + combination of Ritz vectors associated with the "wanted" + Ritz values. + + + + + + + IPARAM(2) = LEVEC. No longer referenced. See remark 2 + below. + + + + IPARAM(3) = MXITER + + On INPUT: maximum number of Arnoldi update iterations + allowed. + + + On OUTPUT: actual number of Arnoldi update iterations + taken. + + + + + IPARAM(4) = NB: blocksize to be used in the recurrence. + The code currently works only for NB = 1. + + + + + IPARAM(5) = NCONV: number of "converged" Ritz values. This + represents the number of Ritz values that satisfy the + convergence criterion. + + + + + IPARAM(6) = IUPD No longer referenced. Implicit restarting + is ALWAYS used. + + + + + IPARAM(7) = MODE On INPUT determines what type of + eigenproblem is being solved. Must be 1,2,3,4,5; See under + Description of dsaupd for the five modes available. + + + + + IPARAM(8) = NP When ido = 3 and the user provides shifts + through reverse communication (IPARAM(1)=0), dsaupd returns NP, + the number of shifts the user is to provide. 0 < NP <= + NCV-NEV. See Remark 6 below. + + + + IPARAM(9) = NUMOP, + IPARAM(10) = NUMOPB, + + IPARAM(11) = NUMREO, OUTPUT: NUMOP = total number of OP*x + operations, NUMOPB = total number of B*x operations if BMAT='G', + NUMREO = total number of steps of re-orthogonalization. + + + + + + + IPNTR + + + array of length 11. (OUTPUT) + + + Pointer to mark the starting locations in + the WORKD and WORKL arrays for matrices/vectors used by the Lanczos + iteration. + + + + + IPNTR(1): pointer to the current operand vector X in + WORKD. + + + + + IPNTR(2): pointer to the current result vector Y in + WORKD. + + + + + IPNTR(3): pointer to the vector B * X in WORKD when used + in the shift-and-invert mode. + + + + + IPNTR(4): pointer to the next available location in WORKL + that is untouched by the program. + + + + + IPNTR(5): pointer to the NCV by 2 tridiagonal matrix T in + WORKL. + + + + + IPNTR(6): pointer to the NCV RITZ values array in + WORKL. + + + + + IPNTR(7): pointer to the Ritz estimates in array WORKL + associated with the Ritz values located in RITZ in WORKL. + + + + + IPNTR(11): pointer to the NP shifts in WORKL. See Remark 6 + below. + + + + + Note: IPNTR(8:10) is only referenced by dseupd . See Remark + 2. + + + + + IPNTR(8): pointer to the NCV RITZ values of the original + system. + + + + + IPNTR(9): pointer to the NCV corresponding error + bounds. + + + + + IPNTR(10): pointer to the NCV by NCV matrix of + eigenvectors of the tridiagonal matrix T. Only referenced by + dseupd if RVEC = 1. See Remarks + + + + + + + WORKD + + work array of length 3 * N. (REVERSE COMMUNICATION) + + Distributed array to be used in the basic Arnoldi iteration + for reverse communication. The user should not use WORKD as + temporary workspace during the iteration. Upon termination + WORKD(1:N) contains B*RESID(1:N). If the Ritz vectors are desired + subroutine dseupd uses this output. See Data Distribution Note + below. + + + + + WORKL + + + work array of length at least NCV ** 2 + 8 * NCV. + (OUTPUT/WORKSPACE) + + + Private (replicated) array on each PE or array allocated on + the front end. See Data Distribution Note below. add here the + parameter description. + + + + + INFO + + Integer. (INPUT/OUTPUT) + + If INFO = 0, a randomly initial residual vector is used, else + RESID contains the initial residual vector, possibly from a previous + run. + + Error flag on output. + + + 0: Normal exit. + + + + 1: Maximum number of iterations taken. All possible + eigenvalues of OP has been found. IPARAM(5) returns the number + of wanted converged Ritz values. + + + + + 2: No longer an informational error. Deprecated starting + with release 2 of ARPACK. + + + + + 3: No shifts could be applied during a cycle of the + Implicitly restarted Arnoldi iteration. One possibility is to + increase the size of NCV relative to NEV. See remark 4 + below. + + + + -1: N must be positive. + + + -2: NEV must be positive. + + + + -3: NCV must be greater than NEV and less than or equal to + N. + + + + + -4: The maximum number of Arnoldi update iterations + allowed must be greater than zero. + + + + + -5: WHICH must be one of 'LM', 'SM', 'LA', 'SA' or + 'BE'. + + + + -6: BMAT must be one of 'I' or 'G'. + + + + -7: Length of private work array WORKL is not + sufficient. + + + + + -8: Error return from trid. eigenvalue calculation; + Informatinal error from LAPACK routine dsteqr. + + + + -9: Starting vector is zero. + + + -10: IPARAM(7) must be 1, 2, 3, 4, 5. + + + -11: IPARAM(7) = 1 and BMAT = 'G' are incompatable. + + + -12: IPARAM(1) must be equal to 0 or 1. + + + -13: NEV and WHICH = 'BE' are incompatable. + + + + -9999: Could not build an Arnoldi factorization. IPARAM(5) + returns the size of the current Arnoldi factorization. The user + is advised to check that enough workspace and array storage has + been allocated. + + + + + + + + + Description + + Reverse communication interface for the Implicitly Restarted Arnoldi + Iteration. For symmetric problems this reduces to a variant of the Lanczos + method. This method has been designed to compute approximations to a few + eigenpairs of a linear operator OP that is real and symmetric with respect + to a real positive semi-definite symmetric matrix B, i.e. + B * OP = + (OP`) * B + + . + + + Another way to express this condition is + < x,OPy > = + < OPx,y > where <z,w > = z`Bw + + . + + + In the standard eigenproblem B is the identity matrix. ( A` denotes + transpose of A) + + + The computed approximate eigenvalues are called Ritz values and the + corresponding approximate eigenvectors are called Ritz vectors. + + + dsaupd is usually called iteratively to solve one of the following + problems: + + + + + Mode 1: A * x = lambda * x, A symmetric ===> OP = A and B = + I. + + + + + Mode 2: A * x = lambda * M * x, A symmetric, M symmetric positive + definite ===> OP = inv[M] * A and B = M. ===> (If M can be + factored see remark 3 below) + + + + + Mode 3: K * x = lambda * M * x, K symmetric, M symmetric positive + semi-definite ===> OP = (inv[K - sigma * M]) * M and B = M. ===> + Shift-and-Invert mode + + + + + Mode 4: K * x = lambda * KG * x, K symmetric positive semi-definite, + KG symmetric indefinite ===> OP = (inv[K - sigma * KG]) * K and B = K. + ===> Buckling mode + + + + + Mode 5: A * x = lambda * M * x, A symmetric, M symmetric positive + semi-definite ===> OP = inv[A - sigma * M] * [A + sigma * M] and B = M. + ===> Cayley transformed mode + + + + + NOTE: The action of w <- inv[A - sigma * M] * v or w <- inv[M] * v + should be accomplished either by a direct method using a sparse matrix + factorization and solving + [A - sigma * M] * w = v or M * w = + v + + , + + + or through an iterative method for solving these systems. If an + iterative method is used, the convergence test must be more stringent than + the accuracy requirements for the eigenvalue approximations. + + + + Remarks + + 1. The converged Ritz values are always returned in ascending + algebraic order. The computed Ritz values are approximate eigenvalues of + OP. The selection of WHICH should be made with this in mind when Mode = + 3, 4, 5. After convergence, approximate eigenvalues of the original problem + may be obtained with the ARPACK subroutine dseupd . + + + 2. If the Ritz vectors corresponding to the converged Ritz values + are needed, the user must call dseupd immediately following completion of + dsaupd . This is new starting with version 2.1 of ARPACK. + + + 3. If M can be factored into a Cholesky factorization M = LL` then + Mode = 2 should not be selected. Instead one should use Mode = 1 with OP = + inv(L) * A * inv(L`). Appropriate triangular linear systems should be solved + with L and L` rather than computing inverses. After convergence, an + approximate eigenvector z of the original problem is recovered by solving + L`z = x where x is a Ritz vector of OP. + + + 4. At present there is no a-priori analysis to guide the selection + of NCV relative to NEV. The only formal requirement is that NCV > NEV. + However, it is recommended that NCV >= 2 * NEV. If many problems of the + same type are to be solved, one should experiment with increasing NCV + while keeping NEV fixed for a given test problem. This will usually + decrease the required number of OP * x operations but it also increases the + work and storage required to maintain the orthogonal basis vectors. The + optimal "cross-over" with respect to CPU time is problem dependent and + must be determined empirically. + + + 5. If IPARAM(7) = 2 then in the Reverse communication interface the + user must do the following. When IDO = 1, Y = OP * X is to be computed. + When IPARAM(7) = 2 OP = inv(B) * A. After computing A * X the user must + overwrite X with A * X. Y is then the solution to the linear set of + equations B * Y = A * X. + + + 6. When IPARAM(1) = 0, and IDO = 3, the user needs to provide the NP + = IPARAM(8) shifts in locations: 1 WORKL(IPNTR(11)) 2 WORKL(IPNTR(11) + 1) . + . . NP WORKL(IPNTR(11) + NP - 1). The eigenvalues of the current tridiagonal + matrix are located in WORKL(IPNTR(6)) through WORKL(IPNTR(6) + NCV - 1). They + are in the order defined by WHICH. The associated Ritz estimates are + located in WORKL(IPNTR(8)), WORKL(IPNTR(8) + 1), ... , + WORKL(IPNTR(8) + NCV - 1). + + + + Example + + 99) + // Repeatedly call the routine DSAUPD and take actions indicated by parameter IDO until + // either convergence is indicated or maxitr has been exceeded. + + [ido, resid, v, iparam, ipntr, workd, workl, info_dsaupd] = dsaupd(ido, bmat, nx, which, nev, tol, resid, ncv, v, iparam, ipntr, workd, workl, info_dsaupd); + + if(info_dsaupd < 0) + printf('\nError with dsaupd, info = %d\n',info_dsaupd); + printf('Check the documentation of dsaupd\n\n'); + end + + if(ido == -1 | ido == 1) + // Perform matrix vector multiplication + workd(ipntr(2):ipntr(2) + nx - 1) = A * workd(ipntr(1):ipntr(1) + nx - 1); + end +end + +// Post-Process using DSEUPD. +rvec = 1; +howmany = 'A'; +info_dseupd = 0; + +[d, z, resid, v, iparam, ipntr, workd, workl, info_dseupd] = dseupd(rvec, howmany, _select, d, z, sigma, bmat, nx, which, nev, tol, resid, ncv, v, ... + iparam, ipntr, workd, workl, info_dseupd); + +if(info_dseupd < 0) + printf('\nError with dseupd, info = %d\n', info_dseupd); + printf('Check the documentation of dseupd.\n\n'); +end + + +// Done with program dssimp. +printf('\nDSSIMP\n'); +printf('======\n'); +printf('\n'); +printf('Size of the matrix is %d\n', nx); +printf('The number of Ritz values requested is %d\n', nev); +printf('The number of Arnoldi vectors generated (NCV) is %d\n', ncv); +printf('What portion of the spectrum: %s\n', which); +printf('The number of Implicit Arnoldi update iterations taken is %d\n', iparam(3)); +printf('The number of OP*x is %d\n', iparam(9)); +printf('The convergence criterion is %d\n', tol); + +]]> + + + + See Also + + + dnaupd + + + dseupd + + + + + Bibliography + + 1. D.C. Sorensen, "Implicit Application of Polynomial Filters in a + k-Step Arnoldi Method", SIAM J. Matr. Anal. Apps., 13 (1992), pp + 357-385. + + + 2. R.B. Lehoucq, "Analysis and Implementation of an Implicitly + Restarted Arnoldi Iteration", Rice University Technical Report TR95-13, + Department of Computational and Applied Mathematics. + + + 3. B.N. Parlett and Y. Saad, "Complex Shift and Invert Strategies + for Real Matrices", Linear Algebra and its Applications, vol 88/89, pp + 575-595, (1987). + + + + Used Functions + Based on ARPACK routine dsaupd + + + History + + + 5.4.0 + + Function obsolete for eigs. + + + + + diff --git a/modules/arnoldi/help/en_US/dseupd.xml b/modules/arnoldi/help/en_US/dseupd.xml new file mode 100755 index 000000000..b29edb314 --- /dev/null +++ b/modules/arnoldi/help/en_US/dseupd.xml @@ -0,0 +1,463 @@ + + + + dseupd + + Interface for the Implicitly Restarted Arnoldi Iteration, to + compute approximations to the converged approximations to eigenvalues of + A * z = lambda * B * z + + This function is obsolete. Please use eigs + + + + + Calling Sequence + + [D, Z, RESID, V, IPARAM, IPNTR, WORKD, WORKL, INFO] = dseupd(RVEC, HOWMANY, SELECT, D, Z, SIGMA, BMAT, N, WHICH, + NEV, TOL, RESID, NCV, V, IPARAM, IPNTR, WORKD, WORKL, INFO) + + + + Arguments + + + RVEC + + Integer. (INPUT) + + Specifies whether Ritz vectors corresponding to the Ritz value + approximations to the eigenproblem A * z = lambda * B * z are + computed. + + + + RVEC = 0 Compute Ritz values only. + + + RVEC = 1 Compute Ritz vectors. + + + + + + HOWMNY + + Character*1. (INPUT) + + Specifies how many Ritz vectors are wanted and the form of Z + the matrix of Ritz vectors. See remark 1 below. + + + + 'A': compute NEV Ritz vectors; + + + + 'S': compute some of the Ritz vectors, specified by the + integer array SELECT. + + + + + + + SELECT + + Integer array of dimension NCV. (INPUT/WORKSPACE) + + If HOWMANY = 'S', SELECT specifies the Ritz vectors to be + computed. To select the Ritz vector corresponding to a Ritz value + D(j), SELECT(j) must be set to 1. + + + If HOWMANY = 'A' , SELECT is used as a workspace for + reordering the Ritz values. + + + + + D + + Double precision array of dimension NEV. (OUTPUT) + + On exit, D contains the Ritz value approximations to the + eigenvalues of A * z = lambda * B * z. The values are returned in + ascending order. + + + If IPARAM(7) = 3, 4, 5 then D represents the Ritz values of OP + computed by dsaupd transformed to those of the original eigensystem + A * z = lambda * B * z. + + + If IPARAM(7) = 1, 2 then the Ritz values of OP are the same as + the those of A * z = lambda * B * z. + + + + + Z + + Double precision N by NEV array. + + If HOWMNY = 'A'. (OUTPUT) On exit, Z contains the + B-orthonormal Ritz vectors of the eigensystemA * z = lambda * B * z + corresponding to the Ritz value approximations. + + If RVEC = 0 then Z is not referenced. + + NOTE: The array Z may be set equal to first NEV columns of the + Arnoldi/Lanczos basis array V computed by DSAUPD . + + + + + SIGMA + + Double precision (INPUT) + + If IPARAM(7) = 3, 4, 5 represents the shift. Not referenced if + IPARAM(7) = 1 or 2. + + + + + + NOTE: The remaining arguments BMAT, N, WHICH, NEV, TOL, RESID, NCV, + V, IPARAM, IPNTR, WORKD, WORKL, LWORKL, INFO must be passed directly to + DSEUPD following the last call to DSAUPD . + + + These arguments MUST NOT BE MODIFIED between the last call to + DSAUPD and the call to DSEUPD. + + + Two of these parameters (WORKL, INFO) are also output + parameters. + + + + WORKL + + + Double precision work array of length LWORKL. + (OUTPUT/WORKSPACE) + + + WORKL(1:4*ncv) contains information obtained in dsaupd. They + are not changed by dseupd. + + + WORKL(4*ncv+1:ncv*ncv+8*ncv) holds the untransformed Ritz + values, the computed error estimates, and the associated eigenvector + matrix of H. + + + Note: IPNTR(8:10) contains the pointer into WORKL for + addresses of the above information computed by dseupd . + + + + + IPNTR(8): pointer to the NCV RITZ values of the original + system. + + + + + IPNTR(9): pointer to the NCV corresponding error bounds. + + + + + IPNTR(10): pointer to the NCV by NCV matrix of + eigenvectors of the tridiagonal matrix T. Only referenced by + dseupd if RVEC = 1 See Remarks. + + + + + + + INFO + + Integer. (OUTPUT) + Error flag on output. + + + 0: Normal exit. + + + -1: N must be positive. + + + -2: NEV must be positive. + + + + -3: NCV must be greater than NEV and less than or equal to + N. + + + + + -5: WHICH must be one of 'LM', 'SM', 'LA', 'SA' or + 'BE'. + + + + -6: BMAT must be one of 'I' or 'G'. + + + + -7: Length of private work WORKL array is not + sufficient. + + + + + -8: Error return from trid. eigenvalue calculation; + Information error from LAPACK routine dsteqr. + + + + -9: Starting vector is zero. + + + -10: IPARAM(7) must be 1, 2, 3, 4, 5. + + + -11: IPARAM(7) = 1 and BMAT = 'G' are incompatible. + + + -12: NEV and WHICH = 'BE' are incompatible. + + + + -14: DSAUPD did not find any eigenvalues to sufficient + accuracy. + + + + -15: HOWMNY must be one of 'A' or 'S' if RVEC = 1. + + + -16: HOWMNY = 'S' not yet implemented. + + + + -17: DSEUPD got a different count of the number of + converged Ritz values than DSAUPD got. This indicates the user + probably made an error in passing data from DSAUPD to DSEUPD or + that the data was modified before entering DSEUPD. + + + + + + + + + Description + + This subroutine returns the converged approximations to eigenvalues + of A * z = lambda * B * z and (optionally): + + + + the corresponding approximate eigenvectors, + + + + an orthonormal (Lanczos) basis for the associated approximate + invariant subspace, + + + + Both. + + + + There is negligible additional cost to obtain eigenvectors. An + orthonormal (Lanczos) basis is always computed. There is an additional + storage cost of n*nev if both are requested (in this case a separate array + Z must be supplied). + + + These quantities are obtained from the Lanczos factorization + computed by DSAUPD for the linear operator OP prescribed by the MODE + selection (see IPARAM(7) in DSAUPD documentation.) DSAUPD must be called + before this routine is called. + + + These approximate eigenvalues and vectors are commonly called Ritz + values and Ritz vectors respectively. They are referred to as such in the + comments that follow. + + + The computed orthonormal basis for the invariant subspace + corresponding to these Ritz values is referred to as a Lanczos basis. + + + See documentation in the header of the subroutine DSAUPD for a + definition of OP as well as other terms and the relation of computed Ritz + values and vectors of OP with respect to the given problem A * z = lambda * B * z. + + + The approximate eigenvalues of the original problem are returned in + ascending algebraic order. + + + The user may elect to call this routine once for each desired Ritz + vector and store it peripherally if desired. There is also the option of + computing a selected set of these vectors with a single call. + + + + Remarks + + 1. The converged Ritz values are always returned in increasing + (algebraic) order. c 2. Currently only HOWMNY = 'A' is implemented. It is + included at this stage for the user who wants to incorporate it. + + + + Example + + 99) + // Repeatedly call the routine DSAUPD and take actions indicated by parameter IDO until + // either convergence is indicated or maxitr has been exceeded. + + [ido, resid, v, iparam, ipntr, workd, workl, info_dsaupd] = dsaupd(ido, bmat, nx, which, nev, tol, resid, ncv, v, iparam, ipntr, workd, workl, info_dsaupd); + + if(info_dsaupd < 0) + printf('\nError with dsaupd, info = %d\n',info_dsaupd); + printf('Check the documentation of dsaupd\n\n'); + end + + if(ido == -1 | ido == 1) + // Perform matrix vector multiplication + workd(ipntr(2):ipntr(2) + nx - 1) = A * workd(ipntr(1):ipntr(1) + nx - 1); + end +end + +// Post-Process using DSEUPD. +rvec = 1; +howmany = 'A'; +info_dseupd = 0; + +[d, z, resid, v, iparam, ipntr, workd, workl, info_dseupd] = dseupd(rvec, howmany, _select, d, z, sigma, bmat, nx, which, nev, tol, resid, ncv, v, ... + iparam, ipntr, workd, workl, info_dseupd); + +if(info_dseupd < 0) + printf('\nError with dseupd, info = %d\n', info_dseupd); + printf('Check the documentation of dseupd.\n\n'); +end + + +// Done with program dssimp. +printf('\nDSSIMP\n'); +printf('======\n'); +printf('\n'); +printf('Size of the matrix is %d\n', nx); +printf('The number of Ritz values requested is %d\n', nev); +printf('The number of Arnoldi vectors generated (NCV) is %d\n', ncv); +printf('What portion of the spectrum: %s\n', which); +printf('The number of Implicit Arnoldi update iterations taken is %d\n', iparam(3)); +printf('The number of OP*x is %d\n', iparam(9)); +printf('The convergence criterion is %d\n', tol); + +]]> + + + + See Also + + + dsaupd + + + dneupd + + + + + Bibliography + + 1. D.C. Sorensen, "Implicit Application of Polynomial Filters in + k-Step Arnoldi Method", SIAM J. Matr. Anal. Apps., 13 (1992), pp + 357-385. + + + 2. R.B. Lehoucq, "Analysis and Implementation of an Implicitly + Restarted Arnoldi Iteration", Rice University Technical Report TR95-13, + Department of Computational and Applied Mathematics. + + + 3. B.N. Parlett and Y. Saad, "Complex Shift and Invert Strategies + for Real Matrices", Linear Algebra and its Applications, vol 88/89, pp + 575-595, (1987). + + + + Used Functions + Based on ARPACK routine dseupd + + + History + + + 5.4.0 + + Function obsolete for eigs. + + + + + diff --git a/modules/arnoldi/help/en_US/eigs.xml b/modules/arnoldi/help/en_US/eigs.xml new file mode 100755 index 000000000..f2a86255e --- /dev/null +++ b/modules/arnoldi/help/en_US/eigs.xml @@ -0,0 +1,525 @@ + + + + + eigs + calculates largest eigenvalues and eigenvectors of matrices + + + Calling Sequence + + d = eigs(A [,B [,k [,sigma [,opts]]]]) + [d, v] = eigs(A [,B [,k [,sigma [,opts]]]]) + + d = eigs(Af, n [,B [,k [,sigma [,opts]]]]) + [d, v] = eigs(Af, n [,B [,k [,sigma [,opts]]]]) + + + + Arguments + + + A + + a full or sparse, real or complex, symmetric or non-symmetric square matrix + + + + Af + + a function + + + + n + + + a scalar, defined only if A is a function + + + + + B + + + a sparse, real or complex, square matrix with same dimensions as + A + + + + + k + + an integer, number of eigenvalues to be computed + + + + sigma + + a real scalar or a string of length 2 + + + + opts + + a structure + + + + d + + a real or complex eigenvalues vector or diagonal matrix (eigenvalues along the diagonal) + + + + v + + + real or complex eigenvector matrix + + + + + + + Description + + The purpose of the eigs function is to compute the largest eigenvalues of sparse, large matrices. + + + + d = eigs(A) or d = eigs(Af, n) + + + solves the eigenvalue problem A * v = lambda * v. This calling returns a vector d containing the six largest magnitude eigenvalues. + A is either a square matrix, which can be symmetric or non-symmetric, real or complex, full or sparse. + + + A should be represented by a function Af. In this instance, a scalar n designating + the length of the vector argument, must be defined. It must have the following header : + + + + + + This function Af must return one of the four following expressions : + + + A * x + if sigma is not given or is a string other than 'SM'. + + + A \ x + if sigma is 0 or 'SM'. + + + (A - sigma * I) \ x + for the standard eigenvalue problem, where I is the identity matrix. + + + (A - sigma * B) \ x + for the generalized eigenvalue problem. + + + + + + + [d, v] = eigs(A) or [d, v] = eigs(Af, n) + + + returns a diagonal matrix d containing the six largest magnitude eigenvalues on the diagonal. + v is a n by six matrix whose columns are the six eigenvectors corresponding to the returned eigenvalues. + + + + + d = eigs(A, B) + + + solves the generalized eigenvalue problem A * v = lambda * B * v with positive, definite matrix B. + + + + + if B is not specified, B = [] is used. + + + + + if B is specified, B must be the same size as A. + + + + + + + d = eigs(A, B, k) + + + returns in vector d the k eigenvalues. + If k is not specified, k = min(n, 6), where n is the row number of A. + + + + + d = eigs(A, B, k, sigma) + + + returns in vector d the k eigenvalues determined by sigma. + sigma can be either a real or complex including 0 scalar or string. + If sigma is a string of length 2, it takes one of the following values : + + + + + 'LM' compute the k largest in magnitude eigenvalues (by default). + + + + + 'SM' compute the k smallest in magnitude eigenvalues (same as sigma = 0). + + + + + 'LA' compute the k Largest Algebraic eigenvalues, only for real symmetric problems. + + + + + 'SA' compute the k Smallest Algebraic eigenvalues, only for real symmetric problems. + + + + + 'BE' compute k eigenvalues, half from each end of the spectrum, only for real + symmetric problems. + + + + + 'LR' compute the k eigenvalues of Largest Real part, only for real non-symmetric or + complex problems. + + + + + 'SR' compute the k eigenvalues of Smallest Real part, only for real non-symmetric or + complex problems. + + + + + 'LI' compute the k eigenvalues of Largest Imaginary part, only for real non-symmetric + or complex problems. + + + + + 'SI' compute the k eigenvalues of Smallest Imaginary part, only for real non-symmetric + or complex problems. + + + + + + + d = eigs(A, B, k, sigma, opts) + + + If the opts structure is specified, different options can be used to compute the k eigenvalues : + + + + + tol + + required convergence tolerance. By default, tol = %eps. + + + + + + maxiter + + maximum number of iterations. By default, maxiter = 300. + + + + + + ncv + + number of Lanzcos basis vectors to use. For real non-symmetric problems, the ncv value must be greater or equal than 2 * k + 1 and, by default, ncv = min(max(2 * k + 1, 20), nA) . For real symmetric or complex problems, ncv must be greater or equal 2 * k and, by default, ncv = min(max(2 * k, 20), nA) with nA = size(A, 2) . + + + + + + resid + + starting vector whose contains the initial residual vector, possibly from a previous run. By default, + resid is a random initial vector. + + + + + + cholB + + if chol(B) is passed rather than B. By default, cholB is %f. + + + + + + isreal + + if Af is given, isreal can be defined. By default, isreal is %t. + This argument must not be indicated if A is a matrix. + + + + + + issym + + if Af is given, issym can be defined. By default, issym is %f. + This argument must not be indicated if A is a matrix. + + + + + + + + + + References + + This function is based on the ARPACK package written by R. Lehoucq, K. Maschhoff, D. Sorensen, and C. Yang. + + + + DSAUPD and DSEUPD routines for real symmetric problems, + + + DNAUPD and DNEUPD routines for real non-symmetric problems. + + + ZNAUPD and ZNEUPD routines for complex problems. + + + + + Example for real symmetric problems + + + + + + Example for real non-symmetric problems + + + + + + Example for complex problems + + + + + + See Also + + + spec + + + + + History + + + 5.4.0 + Function introduced. Deprecates dnaupd, dneupd, dsaupd, dseupd, znaupd and zneupd. + + + + diff --git a/modules/arnoldi/help/en_US/znaupd.xml b/modules/arnoldi/help/en_US/znaupd.xml new file mode 100755 index 000000000..62172c4b4 --- /dev/null +++ b/modules/arnoldi/help/en_US/znaupd.xml @@ -0,0 +1,799 @@ + + + + znaupd + + Interface for the Implicitly Restarted Arnoldi Iteration, to + compute a few eigenpairs of a complex linear operator OP with respect to a + semi-inner product defined by a hermitian positive semi-definite real + matrix B. + + This function is obsolete. Please use eigs + + + + + Calling Sequence + [IDO, RESID, V, IPARAM, IPNTR, WORKD, WORKL, RWORK, INFO] = znaupd(ID0, BMAT, N, WHICH, NEV, TOL, RESID, NCV, V, IPARAM, IPNTR, WORKD, WORKL, RWORK, INFO) + + + Arguments + + + IDO + + Integer. (INPUT/OUTPUT) + + Reverse communication flag. IDO must be zero on the first call + to znaupd. IDO will be set internally to indicate the type of + operation to be performed. Control is then given back to the calling + routine which has the responsibility to carry out the requested + operation and call znaupd with the result. + + + The operand is given in WORKD(IPNTR(1)), the result must be + put in WORKD(IPNTR(2)). + + + + + IDO = 0: first call to the reverse communication interface + + + + + IDO = -1: compute Y = OP * X where IPNTR(1) is the pointer + into WORKD for X, IPNTR(2) is the pointer into WORKD for Y. + + + This is for the initialization phase to force the starting + vector into the range of OP. + + + + + IDO = 1: compute Y = OP * X where IPNTR(1) is the pointer + into WORKD for X, IPNTR(2) is the pointer into WORKD for Y. + + + In mode 3, the vector B * X is already available in + WORKD(ipntr(3)). It does not need to be recomputed in forming OP + * X. + + + + + IDO = 2: compute Y = M * X where IPNTR(1) is the pointer + into WORKD for X, IPNTR(2) is the pointer into WORKD for + Y. + + + + + IDO = 3: compute and return the shifts in the first NP + locations of WORKL. + + + + IDO = 99: done + + + + After the initialization phase, when the routine is used in + the "shift-and-invert" mode, the vector M * X is already available + and does not need to be recomputed in forming OP*X. + + + + + BMAT + + Character. (INPUT) + + specifies the type of the matrix B that defines the + semi-inner product for the operator OP. + + + + 'I': standard eigenvalue problem A * x = lambda * x + + + + 'G': generalized eigenvalue problem A * x = + lambda * M * x + + + + + + + N + + Integer. (INPUT) + Dimension of the eigenproblem. + + + + WHICH + + string of length 2. (INPUT) + + + + 'LM': want the NEV eigenvalues of largest + magnitude. + + + + + 'SM': want the NEV eigenvalues of smallest + magnitude. + + + + + 'LR': want the NEV eigenvalues of largest real + part. + + + + + 'SR': want the NEV eigenvalues of smallest real part. + + + + + 'LI': want the NEV eigenvalues of largest imaginary + part. + + + + + 'SI': want the NEV eigenvalues of smallest imaginary + part. + + + + + + + NEV + + Integer. (INPUT) + + Number of eigenvalues of OP to be computed. 0 < NEV < + N - 1. + + + + + TOL + + Double precision scalar. (INPUT) + + Stopping criteria: the relative accuracy of the Ritz value is + considered acceptable if BOUNDS(I) .LE. TOL * ABS(RITZ(I)) where + ABS(RITZ(I)) is the magnitude when RITZ(I) is complex. DEFAULT = + dlamch('EPS') (machine precision as computed by the LAPACK auxiliary + subroutine dlamch). + + + + + RESID + + Complex*16 array of length N. (INPUT/OUTPUT) + + On INPUT: If INFO .EQ. 0, a random initial residual vector is + used. If INFO .NE. 0, RESID contains the initial residual vector, + possibly from a previous run. + + On OUTPUT: RESID contains the final residual vector. + + + + NCV + + Integer. (INPUT) + + Number of columns of the matrix V. NCV must satisfy the two + inequalities 2 <= NCV - NEV and NCV <= N. + + + This will indicate how many Arnoldi vectors are generated at + each iteration. After the startup phase in which NEV Arnoldi vectors + are generated, the algorithm generates approximately NCV - NEV Arnoldi + vectors at each subsequent update iteration. Most of the cost in + generating each Arnoldi vector is in the matrix-vector operation + OP * x. (See remark 4 below.) + + + + + V + + Complex*16 array N by NCV. (OUTPUT) + Contains the final set of Arnoldi basis vectors. + + + + IPARAM + + Integer array of length 11. (INPUT/OUTPUT) + + + + IPARAM(1) = ISHIFT: method for selecting the implicit + shifts. The shifts selected at each iteration are used to filter + out the components of the unwanted eigenvector. + + + + + ISHIFT = 0: the shifts are to be provided by the user + via reverse communication. The NCV eigenvalues of the + Hessenberg matrix H are returned in the part of WORKL array + corresponding to RITZ. + + + + + ISHIFT = 1: exact shifts with respect to the current + Hessenberg matrix H. This is equivalent to restarting the + iteration from the beginning after updating the starting + vector with a linear combination of Ritz vectors associated + with the "wanted" eigenvalues. + + + + + ISHIFT = 2: other choice of internal shift to be + defined. + + + + + + IPARAM(2) = No longer referenced + + + IPARAM(3) = MXITER + + On INPUT: maximum number of Arnoldi update iterations + allowed. + + + On OUTPUT: actual number of Arnoldi update iterations + taken. + + + + + IPARAM(4) = NB: blocksize to be used in the recurrence. + The code currently works only for NB = 1. + + + + + IPARAM(5) = NCONV: number of "converged" Ritz values. This + represents the number of Ritz values that satisfy the + convergence criterion. + + + + + IPARAM(6) = IUPD No longer referenced. Implicit restarting + is ALWAYS used. + + + + + IPARAM(7) = MODE On INPUT determines what type of + eigenproblem is being solved. Must be 1,2,3; See under + Description of znaupd for the four modes available. + + + + + IPARAM(8) = NP When ido = 3 and the user provides shifts + through reverse communication (IPARAM(1)=0), _naupd returns NP, + the number of shifts the user is to provide. 0 < NP < + NCV-NEV. + + + + IPARAM(9) = NUMOP, + IPARAM(10) = NUMOPB, + + IPARAM(11) = NUMREO, OUTPUT: NUMOP = total number of OP*x + operations, NUMOPB = total number of B*x operations if BMAT='G', + NUMREO = total number of steps of re-orthogonalization. + + + + + + + IPNTR + + Integer array of length 14. (OUTPUT) + + Pointer to mark the starting locations in the WORKD and WORKL + arrays for matrices/vectors used by the Arnoldi iteration. + + + + + IPNTR(1): pointer to the current operand vector X in + WORKD. + + + + + IPNTR(2): pointer to the current result vector Y in + WORKD. + + + + + IPNTR(3): pointer to the vector B * X in WORKD when used + in the shift-and-invert mode. + + + + + IPNTR(4): pointer to the next available location in WORKL + that is untouched by the program. + + + + + IPNTR(5): pointer to the NCV by NCV upper Hessenberg + matrix H in WORKL. + + + + IPNTR(6): pointer to the ritz value array RITZ + + + + IPNTR(7): pointer to the (projected) ritz vector array Q + + + + + IPNTR(8): pointer to the error BOUNDS array in WORKL. + + + + + IPNTR(14): pointer to the NP shifts in WORKL. See Remark 5 + below. + + + + + Note: IPNTR(9:13) is only referenced by zneupd. See Remark 2 + below. + + + + + IPNTR(9): pointer to the NCV RITZ values of the original + system. + + + + IPNTR(10): Not Used + + + + IPNTR(11): pointer to the NCV corresponding error + bounds. + + + + + IPNTR(12): pointer to the NCV by NCV upper triangular + Schur matrix for H. + + + + + IPNTR(13): pointer to the NCV by NCV matrix of + eigenvectors of the upper Hessenberg matrix H. Only referenced + by zneupd if RVEC = 1 See Remark 2 below. + + + + + + + WORKD + + + Complex*16 work array of length 3 * N. (REVERSE COMMUNICATION) + + + Distributed array to be used in the basic Arnoldi iteration + for reverse communication. + + + The user should not use WORKD as temporary workspace during + the iteration !!!!!!!!!! + + See Data Distribution Note below. + + + + WORKL + + + Complex*16 work array of length 3 * NCV ** 2 + 5 * NCV. (OUTPUT/WORKSPACE) + + + Private (replicated) array on each PE or array allocated on + the front end. See Data Distribution Note below. + + + + + RWORK + + + Double precision work array of length NCV (WORKSPACE) Private + (replicated) array on each PE or array allocated on the front + end. + + + + + INFO + + Integer. (INPUT/OUTPUT) + + If INFO == 0, a randomly initial residual vector is used. + + + If INFO ~= 0, RESID contains the initial residual vector, + possibly from a previous run. + + Error flag on output. + + + 0: Normal exit. + + + + 1: Maximum number of iterations taken. All possible + eigenvalues of OP has been found. IPARAM(5) returns the number + of wanted converged Ritz values. + + + + + 2: No longer an informational error. Deprecated starting + with release 2 of ARPACK. + + + + + 3: No shifts could be applied during a cycle of the + Implicitly restarted Arnoldi iteration. One possibility is to + increase the size of NCV relative to NEV. See remark 4 + below. + + + + -1: N must be positive. + + + -2: NEV must be positive. + + + -3: NCV-NEV >= 1 and less than or equal to N. + + + + -4: The maximum number of Arnoldi update iteration must be + greater than zero. + + + + + -5: WHICH must be one of 'LM', 'SM', 'LR', 'SR', 'LI', + 'SI'. + + + + -6: BMAT must be one of 'I' or 'G'. + + + -7: Length of private work array is not sufficient. + + + + -8: Error return from LAPACK eigenvalue + calculation. + + + + -9: Starting vector is zero. + + + -10: IPARAM(7) must be 1, 2, 3. + + + -11: IPARAM(7) = 1 and BMAT = 'G' are incompatible. + + + -12: IPARAM(1) must be equal to 0 or 1. + + + + -9999: Could not build an Arnoldi factorization. User + input error highly likely. Please check actual array dimensions + and layout. IPARAM(5) returns the size of the current Arnoldi + factorization. + + + + + + + + + Description + + Reverse communication interface for the Implicitly Restarted Arnoldi + iteration. This is intended to be used to find a few eigenpairs of a + complex linear operator OP with respect to a semi-inner product defined by + a hermitian positive semi-definite real matrix B. B may be the identity + matrix. + + + NOTE: if both OP and B are real, then dsaupd or dnaupd should be + used. + + + The computed approximate eigenvalues are called Ritz values and the + corresponding approximate eigenvectors are called Ritz vectors. znaupd is + usually called iteratively to solve one of the following problems: + + + + Mode 1: A * x = lambda * x. + ===> OP = A and B = I. + + + Mode 2: A * x = lambda * M * x, M hermitian positive definite + ===> OP = inv[M] * A and B = M. + ===> (If M can be factored see remark 3 below) + + + Mode 3: A * x = lambda * M * x, M hermitian semi-definite + ===> OP = inv[A - sigma * M] * M and B = M. + + ===> shift-and-invert mode If OP * x = amu * x, then lambda = + sigma + 1/amu. + + + + + NOTE: The action of w <- inv[A - sigma * M] * v or w <- inv[M] * v + should be accomplished either by a direct method using a sparse matrix + factorization and solving + + [A - sigma * M] * w = v or M * w = v, + + or through an iterative method for solving these systems. If an + iterative method is used, the convergence test must be more stringent than + the accuracy requirements for the eigenvalue approximations. + + + + Remarks + + + + The computed Ritz values are approximate eigenvalues of OP. The + selection of WHICH should be made with this in mind when using Mode = + 3. When operating in Mode = 3 setting WHICH = 'LM' will compute the + NEV eigenvalues of the original problem that are closest to the shift + SIGMA . After convergence, approximate eigenvalues of the original + problem may be obtained with the ARPACK subroutine zneupd. + + + + + If a basis for the invariant subspace corresponding to the + converged Ritz values is needed, the user must call zneupd immediately + following completion of znaupd. This is new starting with release 2 of + ARPACK. + + + + + If M can be factored into a Cholesky factorization M = LL` then + Mode = 2 should not be selected. Instead one should use Mode = 1 with + OP = inv(L) * A * inv(L`). Appropriate triangular linear systems should be + solved with L and L` rather than computing inverses. After + convergence, an approximate eigenvector z of the original problem is + recovered by solving L`z = x where x is a Ritz vector of OP. + + + + + At present there is no a-priori analysis to guide the selection + of NCV relative to NEV. The only formal requirement is that NCV > + NEV + 1. However, it is recommended that NCV .ge. 2 * NEV. If many + problems of the same type are to be solved, one should experiment with + increasing NCV while keeping NEV fixed for a given test problem. This + will usually decrease the required number of OP*x operations but it + also increases the work and storage required to maintain the + orthogonal basis vectors. The optimal "cross-over" with respect to CPU + time is problem dependent and must be determined empirically. See + Chapter 8 of Reference 2 for further information. + + + + + When IPARAM(1) = 0, and IDO = 3, the user needs to provide the + NP = IPARAM(8) complex shifts in locations + + + WORKL(IPNTR(14)), WORKL(IPNTR(14)+1), ... , WORKL(IPNTR(14)+NP). + + + Eigenvalues of the current upper Hessenberg matrix are located + in WORKL(IPNTR(6)) through WORKL(IPNTR(6)+NCV-1). They are ordered + according to the order defined by WHICH. The associated Ritz estimates + are located in + + + WORKL(IPNTR(8)), WORKL(IPNTR(8)+1), ... , + WORKL(IPNTR(8)+NCV-1). + + + + + + Example + + 99) + // Repeatedly call the routine ZNAUPD and take actions indicated by parameter IDO until + // either convergence is indicated or maxitr has been exceeded. + + [ido, resid, v, iparam, ipntr, workd, workl, rwork, info_znaupd] = znaupd(ido, bmat, nx, which, nev, tol, resid, ncv, v, iparam, ipntr, workd, workl, rwork, info_znaupd); + + if(info_znaupd < 0) + printf('\nError with znaupd, info = %d\n', info_znaupd); + printf('Check the documentation of znaupd\n\n'); + end + + if(ido == -1 | ido == 1) + // Perform matrix vector multiplication + workd(ipntr(2):ipntr(2) + nx - 1) = A * workd(ipntr(1):ipntr(1) + nx - 1); + end +end + +// Post-Process using ZNEUPD. + +rvec = 1; +howmany = 'A'; +info_zneupd = 0; + +[d, z, resid, iparam, ipntr, workd, workl, rwork, info_zneupd] = zneupd(rvec, howmany, _select, d, z, sigma, workev, bmat, nx, which, nev, tol, resid, ncv, v, ... + iparam, ipntr, workd, workl, rwork, info_zneupd); + +if(info_zneupd < 0) + printf('\nError with zneupd, info = %d\n', info_zneupd); + printf('Check the documentation of zneupd.\n\n'); +end + +// Done with program znsimp. +printf('\nZNSIMP\n'); +printf('======\n'); +printf('\n'); +printf('Size of the matrix is %d\n', nx); +printf('The number of Ritz values requested is %d\n', nev); +printf('The number of Arnoldi vectors generated (NCV) is %d\n', ncv); +printf('What portion of the spectrum: %s\n', which); +printf('The number of Implicit Arnoldi update iterations taken is %d\n', iparam(3)); +printf('The number of OP*x is %d\n', iparam(9)); +printf('The convergence criterion is %d\n', tol); + +]]> + + + + See Also + + + dnaupd + + + dneupd + + + zneupd + + + + + Bibliography + + 1. D.C. Sorensen, "Implicit Application of Polynomial Filters in a + k-Step Arnoldi Method", SIAM J. Matr. Anal. Apps., 13 (1992), pp + 357-385. + + + 2. R.B. Lehoucq, "Analysis and Implementation of an Implicitly + Restarted Arnoldi Iteration", Rice University Technical Report TR95-13, + Department of Computational and Applied Mathematics. + + + 3. B.N. Parlett and Y. Saad, "Complex Shift and Invert Strategies + for Real Matrices", Linear Algebra and its Applications, vol 88/89, pp + 575-595, (1987). + + + + Used Functions + Based on ARPACK routine znaupd + + + History + + + 5.4.0 + + Function obsolete for eigs. + + + + + diff --git a/modules/arnoldi/help/en_US/zneupd.xml b/modules/arnoldi/help/en_US/zneupd.xml new file mode 100755 index 000000000..f35717ca1 --- /dev/null +++ b/modules/arnoldi/help/en_US/zneupd.xml @@ -0,0 +1,525 @@ + + + + zneupd + + Interface for the Implicitly Restarted Arnoldi Iteration, to + compute approximations to the converged approximations to eigenvalues of + A * z = lambda * B * z + + This function is obsolete. Please use eigs + + + + + Calling Sequence + + [D, Z, RESID, IPARAM, IPNTR, WORKD, WORKL, RWORK, INFO] = zneupd(RVEC, HOWMANY, SELECT, D, Z, SIGMA, WORKev, + BMAT, N, WHICH, NEV, TOL, RESID, NCV, V, IPARAM, IPNTR, WORKD, WORKL, RWORK, INFO) + + + + Arguments + + + RVEC + + Integer. (INPUT) + + Specifies whether a basis for the invariant subspace + corresponding to the converged Ritz value approximations for the + eigenproblem A * z = lambda * B * z is computed. + + + + RVEC = 0 Compute Ritz values only. + + + + RVEC = 1 Compute Ritz vectors or Schur vectors. See + Remarks below. + + + + + + + HOWMANY + + Character. (INPUT) + + Specifies the form of the basis for the invariant subspace + corresponding to the converged Ritz values that is to be computed. + + + + 'A': Compute NEV Ritz vectors; + + + 'P': Compute NEV Schur vectors; + + + + 'S': compute some of the Ritz vectors, specified by the + integer array SELECT. + + + + + + + SELECT + + Integer array of dimension NCV. (INPUT) + + If HOWMANY = 'S', SELECT specifies the Ritz vectors to be + computed. To select the Ritz vector corresponding to a Ritz value + D(j), SELECT(j) must be set to 1. + + + If HOWMANY = 'A' or 'P', SELECT need not be initialized but it + is used as internal workspace. + + + + + D + + Complex*16 array of dimension NEV + 1. (OUTPUT) + + On exit, D contains the Ritz approximations to the eigenvalues + lambda for A * z = lambda * B * z. + + + + + Z + + Complex*16 N by NEV array. (OUTPUT) + On exit, + + If RVEC = 1 and HOWMANY = 'A', then the columns of Z + represents approximate eigenvectors (Ritz vectors) corresponding to + the NCONV = IPARAM(5) Ritz values for eigensystem A * z = lambda * B * z. + + + If RVEC = 0 or HOWMANY = 'P', then Z is NOT REFERENCED. + + + NOTE: If if RVEC = 1 and a Schur basis is not required, the + array Z may be set equal to first NEV+1 columns of the Arnoldi basis + array V computed by ZNAUPD. In this case the Arnoldi basis will be + destroyed and overwritten with the eigenvector basis. + + + + + SIGMA + + Complex*16. (INPUT) + If IPARAM(7) = 3 then SIGMA represents the shift. + Not referenced if IPARAM(7) = 1 or 2. + + + + WORKev + + Complex*16 work array of dimension 2 * NCV. (WORKSPACE) + + + + + NOTE: The remaining arguments BMAT, N, WHICH, NEV, TOL, RESID, NCV, + V, IPARAM, IPNTR, WORKD, WORKL, LWORKL, RWORK, INFO must be passed + directly to ZNEUPD following the last call to ZNAUPD. + + + These arguments MUST NOT BE MODIFIED between the last call to + ZNAUPD and the call to ZNEUPD. + + + Three of these parameters (V, WORKL and INFO) are also output + parameters. + + + + V + + Complex*16 N by NCV array. (INPUT/OUTPUT) + + Upon INPUT: the NCV columns of V contain the Arnoldi basis + vectors for OP as constructed by ZNAUPD. + + + Upon OUTPUT: If RVEC = 1 the first NCONV = IPARAM(5) columns + contain approximate Schur vectors that span the desired invariant + subspace. + + + NOTE: If the array Z has been set equal to first NEV+1 columns + of the array V and RVEC = 1 and HOWMANY = 'A', then the Arnoldi basis + held by V has been overwritten by the desired Ritz vectors. If a + separate array Z has been passed then the first NCONV=IPARAM(5) + columns of V will contain approximate Schur vectors that span the + desired invariant subspace. + + + + + WORKL + + + Double precision work array of length LWORKL. + (OUTPUT/WORKSPACE) + + + WORKL(1:ncv * ncv + 2 * ncv) contains information obtained in + znaupd. They are not changed by zneupd. + + + WORKL(ncv * ncv + 2 * ncv + 1:3 * ncv * ncv + 4 * ncv) holds the untransformed + Ritz values, the untransformed error estimates of the Ritz values, + the upper triangular matrix for H, and the associated matrix + representation of the invariant subspace for H. + + + Note: IPNTR(9:13) contains the pointer into WORKL for + addresses of the above information computed by zneupd. + + + + + IPNTR(9): pointer to the NCV RITZ values of the original + system. + + + + IPNTR(10): Not used + + + + IPNTR(11): pointer to the NCV corresponding error + estimates. + + + + + IPNTR(12): pointer to the NCV by NCV upper triangular + Schur matrix for H. + + + + + IPNTR(13): pointer to the NCV by NCV matrix of + eigenvectors of the upper Hessenberg matrix H. Only referenced + by zneupd if RVEC = 1 See Remark 2 below. + + + + + + + INFO + + Integer. (OUTPUT) + Error flag on output. + + + 0: Normal exit. + + + + 1: The Schur form computed by LAPACK routine csheqr could + not be reordered by LAPACK routine ztrsen. Re-enter subroutine + zneupd with IPARAM(5) = NCV and increase the size of the array D + to have dimension at least dimension NCV and allocate at least + NCV columns for Z. + + + NOTE: Not necessary if Z and V share the same space. + Please notify the authors if this error occurs. + + + + -1: N must be positive. + + + -2: NEV must be positive. + + + -3: NCV-NEV >= 1 and less than or equal to N. + + + + -5: WHICH must be one of 'LM', 'SM', 'LR', 'SR', 'LI', + 'SI'. + + + + -6: BMAT must be one of 'I' or 'G'. + + + + -7: Length of private work WORKL array is not + sufficient. + + + + + -8: Error return from LAPACK eigenvalue calculation. This + should never happened. + + + + + -9: Error return from calculation of eigenvectors. + Informational error from LAPACK routine ztrevc. + + + + -10: IPARAM(7) must be 1, 2, 3. + + + -11: IPARAM(7) = 1 and BMAT = 'G' are incompatible. + + + -12: HOWMANY = 'S' not yet implemented. + + + + -13: HOWMANY must be one of 'A' or 'P' if RVEC = .true. + + + + + -14: ZNAUPD did not find any eigenvalues to sufficient + accuracy. + + + + + -15: ZNEUPD got a different count of the number of + converged Ritz values than ZNAUPD got. This indicates the user + probably made an error in passing data from ZNAUPD to ZNEUPD or + that the data was modified before entering ZNEUPD. + + + + + + + + + Description + + This subroutine returns the converged approximations to eigenvalues + of A * z = lambda * B * z and (optionally): + + + + The corresponding approximate eigenvectors; + + + + An orthonormal basis for the associated approximate invariant + subspace; + + + + Both. + + + + There is negligible additional cost to obtain eigenvectors. An + orthonormal basis is always computed. + + + There is an additional storage cost of n*nev if both are requested + (in this case a separate array Z must be supplied). + + + The approximate eigenvalues and eigenvectors of A * z = lambda * B * z are + derived from approximate eigenvalues and eigenvectors of of the linear + operator OP prescribed by the MODE selection in the call to ZNAUPD. + + ZNAUPD must be called before this routine is called. + + These approximate eigenvalues and vectors are commonly called Ritz + values and Ritz vectors respectively. They are referred to as such in the + comments that follow. + + + The computed orthonormal basis for the invariant subspace + corresponding to these Ritz values is referred to as a Schur basis. + + + The definition of OP as well as other terms and the relation of + computed Ritz values and vectors of OP with respect to the given problem + A*z = lambda*B*z may be found in the header of ZNAUPD. For a brief + description, see definitions of IPARAM(7), MODE and WHICH in the + documentation of ZNAUPD. + + + + Remarks + + + Currently only HOWMNY = 'A' and 'P' are implemented. + + + + Schur vectors are an orthogonal representation for the basis of + Ritz vectors. Thus, their numerical properties are often superior. + + If RVEC = 1 then the relationship + A * V(:,1:IPARAM(5)) = V(:,1:IPARAM(5)) * T, + and + transpose( V(:,1:IPARAM(5)) ) * V(:,1:IPARAM(5)) = I + + are approximately satisfied. Here T is the leading submatrix of + order IPARAM(5) of the upper triangular matrix stored + workl(ipntr(12)). + + + + + + Example + + 99) + // Repeatedly call the routine ZNAUPD and take actions indicated by parameter IDO until + // either convergence is indicated or maxitr has been exceeded. + + [ido, resid, v, iparam, ipntr, workd, workl, rwork, info_znaupd] = znaupd(ido, bmat, nx, which, nev, tol, resid, ncv, v, iparam, ipntr, workd, workl, rwork, info_znaupd); + + if(info_znaupd < 0) + printf('\nError with znaupd, info = %d\n', info_znaupd); + printf('Check the documentation of znaupd\n\n'); + end + + if(ido == -1 | ido == 1) + // Perform matrix vector multiplication + workd(ipntr(2):ipntr(2) + nx - 1) = A * workd(ipntr(1):ipntr(1) + nx - 1); + end +end + +// Post-Process using ZNEUPD. + +rvec = 1; +howmany = 'A'; +info_zneupd = 0; + +[d, z, resid, iparam, ipntr, workd, workl, rwork, info_zneupd] = zneupd(rvec, howmany, _select, d, z, sigma, workev, bmat, nx, which, nev, tol, resid, ncv, v, ... + iparam, ipntr, workd, workl, rwork, info_zneupd); + +if(info_zneupd < 0) + printf('\nError with zneupd, info = %d\n', info_zneupd); + printf('Check the documentation of zneupd.\n\n'); +end + +// Done with program znsimp. +printf('\nZNSIMP\n'); +printf('======\n'); +printf('\n'); +printf('Size of the matrix is %d\n', nx); +printf('The number of Ritz values requested is %d\n', nev); +printf('The number of Arnoldi vectors generated (NCV) is %d\n', ncv); +printf('What portion of the spectrum: %s\n', which); +printf('The number of Implicit Arnoldi update iterations taken is %d\n', iparam(3)); +printf('The number of OP*x is %d\n', iparam(9)); +printf('The convergence criterion is %d\n', tol); + +]]> + + + + See Also + + + znaupd + + + dnaupd + + + dneupd + + + + + Bibliography + + 1. D.C. Sorensen, "Implicit Application of Polynomial Filters in a + k-Step Arnoldi Method", SIAM J. Matr. Anal. Apps., 13 (1992), pp + 357-385. + + + 2. R.B. Lehoucq, "Analysis and Implementation of an Implicitly + Restarted Arnoldi Iteration", Rice University Technical Report TR95-13, + Department of Computational and Applied Mathematics. + + + 3. B.N. Parlett and Y. Saad, "Complex Shift and Invert Strategies + for Real Matrices", Linear Algebra and its Applications, vol 88/89, pp + 575-595, (1987). + + + + Used Functions + Based on ARPACK routine zneupd + + + History + + + 5.4.0 + + Function obsolete for eigs. + + + + + diff --git a/modules/arnoldi/help/fr_FR/addchapter.sce b/modules/arnoldi/help/fr_FR/addchapter.sce new file mode 100755 index 000000000..7399d511a --- /dev/null +++ b/modules/arnoldi/help/fr_FR/addchapter.sce @@ -0,0 +1,11 @@ +// Scilab ( http://www.scilab.org/ ) - This file is part of Scilab +// Copyright (C) 2009 - DIGITEO +// +// This file must be used under the terms of the CeCILL. +// This source file is licensed as described in the file COPYING, which +// you should have received as part of this distribution. The terms +// are also available at +// http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt + +add_help_chapter("ARnoldi PACKage (binding de ARPACK)",SCI+"/modules/arnoldi/help/fr_FR",%T); + diff --git a/modules/arnoldi/help/ja_JP/addchapter.sce b/modules/arnoldi/help/ja_JP/addchapter.sce new file mode 100755 index 000000000..fcfdec114 --- /dev/null +++ b/modules/arnoldi/help/ja_JP/addchapter.sce @@ -0,0 +1,11 @@ +// Scilab ( http://www.scilab.org/ ) - This file is part of Scilab +// Copyright (C) 2009 - DIGITEO +// +// This file must be used under the terms of the CeCILL. +// This source file is licensed as described in the file COPYING, which +// you should have received as part of this distribution. The terms +// are also available at +// http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt + +add_help_chapter("ARnoldi PACKage",SCI+"/modules/arnoldi/help/ja_JP",%T); + diff --git a/modules/arnoldi/help/ja_JP/dnaupd.xml b/modules/arnoldi/help/ja_JP/dnaupd.xml new file mode 100755 index 000000000..1e3ca2f46 --- /dev/null +++ b/modules/arnoldi/help/ja_JP/dnaupd.xml @@ -0,0 +1,861 @@ + + + + dnaupd + + 暗黙のうちに再開されるArnoldi反復へのインターフェイスで, + 実線形演算子の小数の固有値/ベクトルの組を近似的に計算します. + + この関数は廃止されました. eigsを使用してください + + + + + Calling Sequence + [IDO, RESID, V, IPARAM, IPNTR, WORKD, WORKL, INFO] = dnaupd(ID0, BMAT, N, WHICH, NEV, TOL, RESID, NCV, V, IPARAM, IPNTR, WORKD, WORKL, INFO) + + + Arguments + + + ID0 + + + Integer. (INPUT/OUTPUT) + + + Reverse communication flag. IDO must + be zero on the first call to dnaupd. IDO will be set internally to + indicate the type of operation to be performed. Control is then + given back to the calling routine which has the responsibility to + carry out the requested operation and call dnaupd with the result. + The operand is given in WORKD(IPNTR(1)), the result must be put in + WORKD(IPNTR(2)). + + + + + IDO = 0: first call to the reverse communication + interface. + + + + + IDO = -1: compute Y = OP * X where IPNTR(1) is the pointer + into WORKD for X, IPNTR(2) is the pointer into WORKD for Y. This + is for the initialization phase to force the starting vector + into the range of OP. + + + + + IDO = 1: compute Y = OP * X where IPNTR(1) is the pointer + into WORKD for X, IPNTR(2) is the pointer into WORKD for Y. In + mode 3 and 4, the vector B * X is already available in + WORKD(ipntr(3)). It does not need to be recomputed in forming OP + * X. + + + + + IDO = 2: compute Y = B * X where IPNTR(1) is the pointer + into WORKD for X, IPNTR(2) is the pointer into WORKD for + Y. + + + + + IDO = 3: compute the IPARAM(8) real and imaginary parts of + the shifts where INPTR(14) is the pointer into WORKL for placing + the shifts. See Remark 5 below. + + + + IDO = 99: done. + + + + + + BMAT + + + Character. (INPUT) + + + specifies the type of the matrix B that defines the + semi-inner product for the operator OP. + + + + 'I' - standard eigenvalue problem A * x = lambda * x + + + + 'G' - generalized eigenvalue problem A * x = + lambda * B * x + + + + + + + N + + Integer. (INPUT) + dimension of the eigenproblem. + + + + WHICH + + + string of length 2. (INPUT) + + + Specifies which of the Ritz values of OP to + compute. + + + + + 'LM' - want the NEV eigenvalues of largest + magnitude. + + + + + 'SM' - want the NEV eigenvalues of smallest + magnitude. + + + + + 'LR' - want the NEV eigenvalues of largest real + part. + + + + + 'SR' - want the NEV eigenvalues of smallest real + part. + + + + + 'LI' - want the NEV eigenvalues of largest imaginary + part. + + + + + 'SI' - want the NEV eigenvalues of smallest imaginary + part. + + + + + + + NEV + + + Integer. (INPUT) + + + number of eigenvalues of OP to be computed. 0 < + NEV < N-1. + + + + + TOL + + + scalar. (INPUT) + + + Stopping criterion: the relative accuracy of the Ritz + value is considered acceptable if BOUNDS(I) <= TOL*ABS(RITZ(I)). + If TOL <= 0. is passed the machine precision is set. + + + + + RESID + + array of length N. (INPUT/OUTPUT) + + On INPUT: If INFO = 0, a random initial residual vector is + used, else RESID contains the initial residual vector, possibly from + a previous run. + + On OUTPUT: RESID contains the final residual vector. + + + + NCV + + + Integer. (INPUT) + + + number of columns of the matrix V. NCV must satisfy + the two inequalities 2 <= NCV - NEV and NCV <= N. + + + This will indicate how many Arnoldi vectors are generated at + each iteration. + + + After the startup phase in which NEV Arnoldi vectors are + generated, the algorithm generates approximately NCV - NEV Arnoldi + vectors at each subsequent update iteration. Most of the cost in + generating each Arnoldi vector is in the matrix-vector operation + OP * x. + + + NOTE: 2 <= NCV - NEV in order that complex conjugate pairs of + Ritz values are kept together. (See remark 4 below) + + + + + V + + + N by NCV array. (OUTPUT) + + + Contains the final set of Arnoldi basis + vectors. + + + + + IPARAM + + array of length 11. (INPUT/OUTPUT) + + + + IPARAM(1) = ISHIFT: method for selecting the implicit + shifts. The shifts selected at each iteration are used to + restart the Arnoldi iteration in an implicit fashion. + + + + + ISHIFT = 0: the shifts are provided by the user via + reverse communication. The real and imaginary parts of the + NCV eigenvalues of the Hessenberg matrix H are returned in + the part of the WORKL array corresponding to RITZR and + RITZI. See remark 5 below. + + + + + ISHIFT = 1: exact shifts with respect to the current + Hessenberg matrix H. This is equivalent to restarting the + iteration with a starting vector that is a linear + combination of approximate Schur vectors associated with the + "wanted" Ritz values. + + + + + + IPARAM(2) = LEVEC. No longer referenced. + + + IPARAM(3) = MXITER + + On INPUT: maximum number of Arnoldi update iterations + allowed. + + + On OUTPUT: actual number of Arnoldi update iterations + taken. + + + + + IPARAM(4) = NB: blocksize to be used in the recurrence. + The code currently works only for NB = 1. + + + + + IPARAM(5) = NCONV: number of "converged" Ritz values. This + represents the number of Ritz values that satisfy the + convergence criterion. + + + + + IPARAM(6) = IUPD No longer referenced. Implicit restarting + is ALWAYS used. + + + + + IPARAM(7) = MODE On INPUT determines what type of + eigenproblem is being solved. Must be 1,2,3,4; See under + Description of dnaupd for the five modes available. + + + + + IPARAM(8) = NP When ido = 3 and the user provides shifts + through reverse communication (IPARAM(1)=0), dnaupd returns NP, + the number of shifts the user is to provide. + + 0 < NP <= NCV-NEV. See Remark 5 below. + + + IPARAM(9) = NUMOP, + IPARAM(10) = NUMOPB, + IPARAM(11) = NUMREO, + + On OUTPUT: NUMOP = total number of OP*x operations, NUMOPB + = total number of B*x operations if BMAT='G', NUMREO = total + number of steps of re-orthogonalization. + + + + + + + IPNTR + + + array of length 14. (OUTPUT) + + + Pointer to mark the starting locations in + the WORKD and WORKL arrays for matrices/vectors used by the Arnoldi + iteration. + + + + + IPNTR(1): pointer to the current operand vector X in + WORKD. + + + + + IPNTR(2): pointer to the current result vector Y in + WORKD. + + + + + IPNTR(3): pointer to the vector B * X in WORKD when used + in the shift-and-invert mode. + + + + + IPNTR(4): pointer to the next available location in WORKL + that is untouched by the program. + + + + + IPNTR(5): pointer to the NCV by NCV upper Hessenberg + matrix H in WORKL. + + + + + IPNTR(6): pointer to the real part of the ritz value array + RITZR in WORKL. + + + + + IPNTR(7): pointer to the imaginary part of the ritz value + array RITZI in WORKL. + + + + + IPNTR(8): pointer to the Ritz estimates in array WORKL + associated with the Ritz values located in RITZR and RITZI in + WORKL. + + + + + IPNTR(14): pointer to the NP shifts in WORKL. See Remark 5 + below. + + + + + Note: IPNTR(9:13) is only referenced by dneupd . See Remark + 2. + + + + + IPNTR(9): pointer to the real part of the NCV RITZ values + of the original system. + + + + + IPNTR(10): pointer to the imaginary part of the NCV RITZ + values of the original system. + + + + + IPNTR(11): pointer to the NCV corresponding error + bounds. + + + + + IPNTR(12):pointer to the NCV by NCV upper quasi-triangular + Schur matrix for H. + + + + + IPNTR(13): pointer to the NCV by NCV matrix of + eigenvectors of the upper Hessenberg matrix H. Only referenced + by dneupd if RVEC = 1 See Remark 2 below. + + + + + + + WORKD + + + Double precision work array of length 3 * N. (REVERSE + COMMUNICATION) + + + Distributed array to be used in the basic Arnoldi iteration + for reverse communication. The user should not use WORKD as + temporary workspace during the iteration. Upon termination + WORKD(1:N) contains B*RESID(1:N). If an invariant subspace + associated with the converged Ritz values is desired, see remark 2 + below, subroutine dneupd uses this output. See Data Distribution + Note below. + + + + + WORKL + + + work array of length at least 3 * NCV ** 2 + 6 * NCV. + (OUTPUT/WORKSPACE) + + + Private (replicated) array on each PE or array + allocated on the front end. See Data Distribution Note below. + + + + + INFO + + Integer. (INPUT/OUTPUT) + + If INFO == 0, a randomly initial residual vector is used, else + RESID contains the initial residual vector, possibly from a previous + run. + + Error flag on output. + + + 0: Normal exit. + + + + 1: Maximum number of iterations taken. All possible + eigenvalues of OP has been found. IPARAM(5) returns the number + of wanted converged Ritz values. + + + + + 2: No longer an informational error. Deprecated starting + with release 2 of ARPACK. + + + + + 3: No shifts could be applied during a cycle of the + Implicitly restarted Arnoldi iteration. One possibility is to + increase the size of NCV relative to NEV. See remark 4 + below. + + + + -1: N must be positive. + + + -2: NEV must be positive. + + + -3: NCV-NEV >= 2 and less than or equal to N. + + + + -4: The maximum number of Arnoldi update iterations + allowed must be greater than zero. + + + + + -5: WHICH must be one of 'LM', 'SM', 'LR', 'SR', 'LI', + 'SI'. + + + + -6: BMAT must be one of 'I' or 'G'. + + + + -7: Length of private work array WORKL is not + sufficient. + + + + + -8: Error return from LAPACK eigenvalue + calculation. + + + + -9: Starting vector is zero. + + + -10: IPARAM(7) must be 1, 2, 3, 4. + + + -11: IPARAM(7) = 1 and BMAT = 'G' are incompatable. + + + -12: IPARAM(1) must be equal to 0 or 1. + + + + -9999: Could not build an Arnoldi factorization. IPARAM(5) + returns the size of the current Arnoldi factorization. The user + is advised to check that enough workspace and array storage has + been allocated. + + + + + + + + + Description + + Reverse communication interface for the Implicitly Restarted Arnoldi + iteration. This subroutine computes approximations to a few eigenpairs of + a linear operator "OP" with respect to a semi-inner product defined by a + symmetric positive semi-definite real matrix B. B may be the identity + matrix. NOTE: If the linear operator "OP" is real and symmetric with + respect to the real positive semi-definite symmetric matrix B, i.e. B*OP = + (OP`)*B, then subroutine dsaupd should be used instead. + + + The computed approximate eigenvalues are called Ritz values and the + corresponding approximate eigenvectors are called Ritz vectors. + + + dnaupd is usually called iteratively to solve one of the following + problems: + + + + + Mode 1: A*x = lambda*x. + OP = A , B = + I + + . + + + + + Mode 2: A*x = lambda*M*x, M symmetric positive definite + OP = inv[M]*A, B = M. (If M can be factored see + remark 3 below) + + + + + Mode 3: A*x = lambda*M*x, M symmetric positive semi-definite. + OP = Real_Part{ inv[A - sigma*M]*M }, B = M. + shift-and-invert mode (in real arithmetic) + + + If OP*x = amu*x, then + + + + amu = 1/2 * [ 1/(lambda-sigma) + + 1/(lambda-conjg(sigma))] + + . + + + Note: If sigma is real, i.e. imaginary part of sigma is zero; + + Real_Part{ inv[A - sigma*M]*M } == inv[A - + sigma*M]*M + + + amu == + 1/(lambda-sigma) + + . + + + + + Mode 4: A*x = lambda*M*x, M symmetric semi-definite + OP + = Imaginary_Part{ inv[A - sigma*M]*M } , B = M + + . + shift-and-invert mode (in real arithmetic) + + + If OP*x = amu*x, then + amu = 1/2i * [ + 1/(lambda-sigma) - 1/(lambda-conjg(sigma)) ] + + . + + + + + Both mode 3 and 4 give the same enhancement to eigenvalues close to + the (complex) shift sigma. However, as lambda goes to infinity, the + operator OP in mode 4 dampens the eigenvalues more strongly than does OP + defined in mode 3. + + + NOTE: The action of w <- inv[A - sigma * M] * v or w <- inv[M] * v + should be accomplished either by a direct method using a sparse matrix + factorization and solving [A - sigma * M] * w = v or + M * w = v, or through an iterative method for solving + these systems. If an iterative method is used, the convergence test must + be more stringent than the accuracy requirements for the eigenvalue + approximations. + + + + Example + + 99) + // Repeatedly call the routine DNAUPD and take actions indicated by parameter IDO until + // either convergence is indicated or maxitr has been exceeded. + [ido, resid, v, iparam, ipntr, workd, workl, info_dnaupd] = dnaupd(ido, bmat, nx, which, nev, tol, resid, ncv, v, iparam, ipntr, workd, workl, info_dnaupd); + if(info_dnaupd < 0) + printf('\nError with dnaupd, info = %d\n',info_dnaupd); + printf('Check the documentation of dnaupd\n\n'); + end + if(ido == -1 | ido == 1) + // Perform matrix vector multiplication + workd(ipntr(2):ipntr(2) + nx -1) = A * workd(ipntr(1):ipntr(1) + nx - 1); + end +end +// Post-Process using DNEUPD. +rvec = 1; +howmany = 'A'; +info_dneupd = 0; +[dr, di, z, resid, v, iparam, ipntr, workd, workl, info_dneupd] = dneupd(rvec, howmany, _select, dr, di, z, sigmar, sigmai, workev, ... + bmat, nx, which, nev, tol, resid, ncv, v, ... + iparam, ipntr, workd, workl, info_dneupd); +if(info_dneupd < 0) + printf('\nError with dneupd, info = %d\n', info_dneupd); + printf('Check the documentation of dneupd.\n\n'); +end +printf('\nDNSIMP\n'); +printf('======\n'); +printf('\n'); +printf('Size of the matrix is %d\n', nx); +printf('The number of Ritz values requested is %d\n', nev); +printf('The number of Arnoldi vectors generated (NCV) is %d\n', ncv); +printf('What portion of the spectrum: %s\n', which); +printf('The number of Implicit Arnoldi update iterations taken is %d\n', iparam(3)); +printf('The number of OP*x is %d\n', iparam(9)); +printf('The convergence criterion is %d\n', tol); +]]> + + + + Remarks + + 1. The computed Ritz values are approximate eigenvalues of OP. The + selection of WHICH should be made with this in mind when Mode = 3 and 4. + After convergence, approximate eigenvalues of the original problem may be + obtained with the ARPACK subroutine dneupd. + + + 2. If a basis for the invariant subspace corresponding to the + converged Ritz values is needed, the user must call dneupd immediately + following completion of dnaupd. This is new starting with release 2 of + ARPACK. + + + 3. If M can be factored into a Cholesky factorization M = LL` then + Mode = 2 should not be selected. Instead one should use Mode = 1 with OP = + inv(L) * A * inv(L`). Appropriate triangular linear systems should be solved + with L and L` rather than computing inverses. After convergence, an + approximate eigenvector z of the original problem is recovered by solving + L`z = x where x is a Ritz vector of OP. + + + 4. At present there is no a-priori analysis to guide the selection + of NCV relative to NEV. The only formal requirement is that NCV > NEV + + 2. However, it is recommended that NCV >= 2 * NEV + 1. If many problems of + the same type are to be solved, one should experiment with increasing NCV + while keeping NEV fixed for a given test problem. This will usually + decrease the required number of OP*x operations but it also increases the + work and storage required to maintain the orthogonal basis vectors. The + optimal "cross-over" with respect to CPU time is problem dependent and + must be determined empirically. See Chapter 8 of Reference 2 for further + information. + + + 5. When IPARAM(1) = 0, and IDO = 3, the user needs to provide the NP + = IPARAM(8) real and imaginary parts of the shifts in locations + + + real part imaginary part + ----------------------- -------------- + 1 WORKL(IPNTR(14)) WORKL(IPNTR(14) + NP) + 2 WORKL(IPNTR(14) + 1) WORKL(IPNTR(14) + NP + 1) + . . + . . + . . + NP WORKL(IPNTR(14) + NP - 1) WORKL(IPNTR(14) + 2 * NP - 1). + + + Only complex conjugate pairs of shifts may be applied and the pairs + must be placed in consecutive locations. The real part of the eigenvalues + of the current upper Hessenberg matrix are located in WORKL(IPNTR(6)) + through WORKL(IPNTR(6) + NCV - 1) and the imaginary part in WORKL(IPNTR(7)) + through WORKL(IPNTR(7) + NCV - 1). They are ordered according to the order + defined by WHICH. The complex conjugate pairs are kept together and the + associated Ritz estimates are located in WORKL(IPNTR(8)), + WORKL(IPNTR(8)+1), ... , WORKL(IPNTR(8) + NCV - 1). + + + + See Also + + + dsaupd + + + dneupd + + + + + Bibliography + + 1. D.C. Sorensen, "Implicit Application of Polynomial Filters in a + k-Step Arnoldi Method", SIAM J. Matr. Anal. Apps., 13 (1992), pp + 357-385. + + + 2. R.B. Lehoucq, "Analysis and Implementation of an Implicitly + Restarted Arnoldi Iteration", Rice University Technical Report TR95-13, + Department of Computational and Applied Mathematics. + + + 3. B.N. Parlett, "The Symmetric Eigenvalue Problem". Prentice-Hall, + 1980. + + + 4. B.N. Parlett, B. Nour-Omid, "Towards a Black Box Lanczos + Program", Computer Physics Communications, 53 (1989), pp 169-179. + + + 5. B. Nour-Omid, B.N. Parlett, T. Ericson, P.S. Jensen, "How to + Implement the Spectral Transformation", Math. Comp., 48 (1987), pp + 663-673. + + + 6. R.G. Grimes, J.G. Lewis and H.D. Simon, "A Shifted Block Lanczos + Algorithm for Solving Sparse Symmetric Generalized Eigenproblems", SIAM J. + Matr. Anal. Apps., January (1993). + + + 7. L. Reichel, W.B. Gragg, "Algorithm 686: FORTRAN Subroutines for + Updating the QR decomposition", ACM TOMS, December 1990, Volume 16 Number + 4, pp 369-377. + + + 8. R.B. Lehoucq, D.C. Sorensen, "Implementation of Some Spectral + Transformations in a k-Step Arnoldi Method". In Preparation. + + + + Used Functions + Based on ARPACK routine dnaupd + + + 履歴 + + + 5.4.0 + + 関数は廃止され,eigsに代替されました. + + + + + diff --git a/modules/arnoldi/help/ja_JP/dneupd.xml b/modules/arnoldi/help/ja_JP/dneupd.xml new file mode 100755 index 000000000..ebd52acc8 --- /dev/null +++ b/modules/arnoldi/help/ja_JP/dneupd.xml @@ -0,0 +1,621 @@ + + + + dneupd + + 暗黙のうちに再開されるArnoldi反復へのインターフェイスで, + 実線形演算子の小数の固有値/ベクトルの組を近似する + A * z = lambda * B * z の固有値を収束的近似により計算します. + + この関数は廃止されました. eigsを使用してください + + + + + Calling Sequence + + [Dr, Di, Z, RESID, V, IPARAM, IPNTR, WORKD, WORKL, INFO] = dneupd(RVEC, HOWMANY, SELECT, Dr, Di, Z, SIGMAr, SIGMAi, WORKev, + BMAT, N, WHICH, NEV, TOL, RESID, NCV, V, IPARAM, IPNTR, WORKD, WORKL, INFO) + + + + Arguments + + + RVEC + + Integer. (INPUT) + + Specifies whether a basis for the invariant subspace + corresponding to the converged Ritz value approximations for the + eigenproblem A * z = lambda * B * z is computed. + + + + RVEC = 0 Compute Ritz values only. + + + RVEC = 1 Compute the Ritz vectors or Schur vectors. + + + See Remarks below. + + + + HOWMANY + + Character. (INPUT) + + Specifies the form of the basis for the invariant subspace + corresponding to the converged Ritz values that is to be + computed. + + + + 'A': Compute NEV Ritz vectors; + + + 'P': Compute NEV Schur vectors; + + + + 'S': compute some of the Ritz vectors, specified by the + integer array SELECT. + + + + + + + SELECT + + Integer array of dimension NCV. (INPUT) + + If HOWMANY = 'S', SELECT specifies the Ritz vectors to be + computed. To select the Ritz vector corresponding to a Ritz value + (DR(j), DI(j)), SELECT(j) must be set to 1. + + + If HOWMANY = 'A' or 'P', SELECT is used as internal + workspace. + + + + + DR + + Double precision array of dimension NEV + 1. (OUTPUT) + + If IPARAM(7) = 1, 2 or 3 and SIGMAI = 0.0 then on exit: DR + contains the real part of the Ritz approximations to the eigenvalues + of A * z = lambda * B * z. + + + If IPARAM(7) = 3, 4 and SIGMAI is not equal to zero, then on + exit: DR contains the real part of the Ritz values of OP computed by + DNAUPD. + + + A further computation must be performed by the user to + transform the Ritz values computed for OP by DNAUPD to those of the + original system A * z = lambda * B * z. See remark 3 below. + + + + + DI + + Double precision array of dimension NEV + 1. (OUTPUT) + + On exit, DI contains the imaginary part of the Ritz value + approximations to the eigenvalues of A * z = lambda * B * z associated + with DR. + + + NOTE: When Ritz values are complex, they will come in complex + conjugate pairs. If eigenvectors are requested, the corresponding + Ritz vectors will also come in conjugate pairs and the real and + imaginary parts of these are represented in two consecutive columns + of the array Z (see below). + + + + + Z + + Double precision N by NEV + 1 array + if RVEC = 1 and HOWMANY = 'A'. (OUTPUT) + + On exit, if RVEC = 1 and HOWMANY = 'A', then the columns of Z + represent approximate eigenvectors (Ritz vectors) corresponding to + the NCONV = IPARAM(5) Ritz values for eigensystem A * z = lambda * B * z. + The complex Ritz vector associated with the Ritz value with positive + imaginary part is stored in two consecutive columns. The first + column holds the real part of the Ritz vector and the second column + holds the imaginary part. The Ritz vector associated with the Ritz + value with negative imaginary part is simply the complex conjugate + of the Ritz vector associated with the positive imaginary part. + + + If RVEC = 0 or HOWMANY = 'P', then Z is not referenced. + + + NOTE: If if RVEC = 1 and a Schur basis is not required, the + array Z may be set equal to first NEV+1 columns of the Arnoldi basis + array V computed by DNAUPD . In this case the Arnoldi basis will be + destroyed and overwritten with the eigenvector basis. + + + + + SIGMAR + + Double precision (INPUT) + + If IPARAM(7) = 3 or 4, represents the real part of the + shift. + + Not referenced if IPARAM(7) = 1 or 2. + + + + SIGMAI + + Double precision (INPUT) + + If IPARAM(7) = 3 or 4, represents the imaginary part of the + shift. + + + Not referenced if IPARAM(7) = 1 or 2. See remark 3 + below. + + + + + WORKEV + + + Double precision work array of dimension 3 * NCV. + (WORKSPACE) + + + + + + NOTE: The remaining arguments BMAT, N, WHICH, NEV, TOL, RESID, NCV, + V, IPARAM, IPNTR, WORKD, WORKL, LWORKL, INFO must be passed directly to + DNEUPD following the last call to DNAUPD . + + + These arguments MUST NOT BE MODIFIED between the last call to + DNAUPD and the call to DNEUPD . + + + Three of these parameters (V, WORKL, INFO) are also output + parameters. + + + + V + + Double precision N by NCV array. (INPUT/OUTPUT) + + Upon INPUT: the NCV columns of V contain the Arnoldi basis + vectors for OP as constructed by DNAUPD. + + + Upon OUTPUT: If RVEC = 1 the first NCONV = IPARAM(5) columns + contain approximate Schur vectors that span the desired invariant + subspace. See Remark 2 below. + + + NOTE: If the array Z has been set equal to first NEV+1 columns + of the array V and RVEC = 1 and HOWMANY= 'A', then the Arnoldi basis + held by V has been overwritten by the desired Ritz vectors. If a + separate array Z has been passed then the first NCONV = IPARAM(5) + columns of V will contain approximate Schur vectors that span the + desired invariant subspace. + + + + + WORKL + + + Double precision work array of length LWORKL. + (OUTPUT/WORKSPACE) + + + WORKL(1:ncv*ncv+3*ncv) contains information obtained in dnaupd + . They are not changed by dneupd . + + + WORKL(ncv*ncv+3*ncv+1:3*ncv*ncv+6*ncv) holds the real and + imaginary part of the untransformed Ritz values, the upper + quasi-triangular matrix for H, and the associated matrix + representation of the invariant subspace for H. + + + Note: IPNTR(9:13) contains the pointer into WORKL for + addresses of the above information computed by dneupd . + + + + + IPNTR(9): pointer to the real part of the NCV RITZ values + of the original system. + + + + + IPNTR(10): pointer to the imaginary part of the NCV RITZ + values of the original system. + + + + + IPNTR(11): pointer to the NCV corresponding error + bounds. + + + + + IPNTR(12): pointer to the NCV by NCV upper + quasi-triangular Schur matrix for H. + + + + + IPNTR(13): pointer to the NCV by NCV matrix of + eigenvectors of the upper Hessenberg matrix H. Only referenced + by dneupd if RVEC = 1 See Remark 2 below. + + + + + + + INFO + + Integer. (OUTPUT). + Error flag on output. + + + 0: Normal exit. + + + + 1: The Schur form computed by LAPACK routine dlahqr could + not be reordered by LAPACK routine dtrsen . Re-enter subroutine + dneupd with IPARAM(5)=NCV and increase the size of the arrays DR + and DI to have dimension at least dimension NCV and allocate at + least NCV columns for Z. + + + NOTE: Not necessary if Z and V share the same space. + Please notify the authors if this error occurs. + + + + -1: N must be positive. + + + -2: NEV must be positive. + + + -3: NCV-NEV >= 2 and less than or equal to N. + + + + -5: WHICH must be one of 'LM', 'SM', 'LR', 'SR', 'LI', + 'SI'. + + + + -6: BMAT must be one of 'I' or 'G'. + + + + -7: Length of private work WORKL array is not + sufficient. + + + + + -8: Error return from calculation of a real Schur form. + Informational error from LAPACK routine dlahqr. + + + + + -9: Error return from calculation of eigenvectors. + Informational error from LAPACK routine dtrevc. + + + + -10: IPARAM(7) must be 1, 2, 3, 4. + + + -11: IPARAM(7) = 1 and BMAT = 'G' are incompatible. + + + -12: HOWMANY = 'S' not yet implemented. + + + -13: HOWMANY must be one of 'A' or 'P' if RVEC = 1. + + + + -14: DNAUPD did not find any eigenvalues to sufficient + accuracy. + + + + + -15: DNEUPD got a different count of the number of + converged Ritz values than DNAUPD got. This indicates the user + probably made an error in passing data from DNAUPD to DNEUPD or + that the data was modified before entering DNEUPD. + + + + + + + + + Description + + This subroutine returns the converged approximations to eigenvalues + of A * z = lambda * B * z and (optionally): + + + + The corresponding approximate eigenvectors; + + + + An orthonormal basis for the associated approximate invariant + subspace; + + + + Both. + + + + There is negligible additional cost to obtain eigenvectors. An + orthonormal basis is always computed. + + + There is an additional storage cost of n*nev if both are requested + (in this case a separate array Z must be supplied). + + + The approximate eigenvalues and eigenvectors of A * z = lambda * B * z are + derived from approximate eigenvalues and eigenvectors of of the linear + operator OP prescribed by the MODE selection in the call to DNAUPD. DNAUPD + must be called before this routine is called. + + + These approximate eigenvalues and vectors are commonly called Ritz + values and Ritz vectors respectively. They are referred to as such in the + comments that follow. + + + The computed orthonormal basis for the invariant subspace + corresponding to these Ritz values is referred to as a Schur basis. + + + See documentation in the header of the subroutine DNAUPD for + definition of OP as well as other terms and the relation of computed Ritz + values and Ritz vectors of OP with respect to the given problem A * z = + lambda * B * z. + + + For a brief description, see definitions of IPARAM(7), MODE and + WHICH in the documentation of DNAUPD . + + + + Remarks + + + Currently only HOWMNY = 'A' and 'P' are implemented. + Let trans(X) denote the transpose of X. + + + + Schur vectors are an orthogonal representation for the basis of + Ritz vectors. Thus, their numerical properties are often superior. If + RVEC = 1 then the relationship + + + A * V(:,1:IPARAM(5)) = V(:,1:IPARAM(5)) * T, and + trans(V(:,1:IPARAM(5))) * V(:,1:IPARAM(5)) = I + + are approximately satisfied. + + Here T is the leading submatrix of order IPARAM(5) of the real + upper quasi-triangular matrix stored workl(ipntr(12)). That is, T is + block upper triangular with 1-by-1 and 2-by-2 diagonal blocks; each + 2-by-2 diagonal block has its diagonal elements equal and its + off-diagonal elements of opposite sign. Corresponding to each 2-by-2 + diagonal block is a complex conjugate pair of Ritz values. The real + Ritz values are stored on the diagonal of T. + + + + + If IPARAM(7) = 3 or 4 and SIGMAI is not equal zero, then the + user must form the IPARAM(5) Rayleigh quotients in order to transform + the Ritz values computed by DNAUPD for OP to those of A * z = + lambda * B * z. Set RVEC = 1 and HOWMNY = 'A', and compute + + trans(Z(:,I)) * A * Z(:,I) if DI(I) = 0. + + If DI(I) is not equal to zero and DI(I+1) = - D(I), then the + desired real and imaginary parts of the Ritz value are + + + trans(Z(:,I)) * A * Z(:,I) + trans(Z(:,I+1)) * A * Z(:,I+1), + + + trans(Z(:,I)) * A * Z(:,I+1) - trans(Z(:,I+1)) * A * Z(:,I), + + respectively. + + Another possibility is to set RVEC = 1 and HOWMANY = 'P' and + compute + + trans(V(:,1:IPARAM(5))) * A * V(:,1:IPARAM(5)) + + and then an upper quasi-triangular matrix of order IPARAM(5) is + computed. See remark 2 above. + + + + + + Example + + 99) + // Repeatedly call the routine DNAUPD and take actions indicated by parameter IDO until + // either convergence is indicated or maxitr has been exceeded. + [ido, resid, v, iparam, ipntr, workd, workl, info_dnaupd] = dnaupd(ido, bmat, nx, which, nev, tol, resid, ncv, v, iparam, ipntr, workd, workl, info_dnaupd); + if(info_dnaupd < 0) + printf('\nError with dnaupd, info = %d\n',info_dnaupd); + printf('Check the documentation of dnaupd\n\n'); + end + if(ido == -1 | ido == 1) + // Perform matrix vector multiplication + workd(ipntr(2):ipntr(2) + nx -1) = A * workd(ipntr(1):ipntr(1) + nx - 1); + end +end +// Post-Process using DNEUPD. +rvec = 1; +howmany = 'A'; +info_dneupd = 0; +[dr, di, z, resid, v, iparam, ipntr, workd, workl, info_dneupd] = dneupd(rvec, howmany, _select, dr, di, z, sigmar, sigmai, workev, ... + bmat, nx, which, nev, tol, resid, ncv, v, ... + iparam, ipntr, workd, workl, info_dneupd); +if(info_dneupd < 0) + printf('\nError with dneupd, info = %d\n', info_dneupd); + printf('Check the documentation of dneupd.\n\n'); +end +printf('\nDNSIMP\n'); +printf('======\n'); +printf('\n'); +printf('Size of the matrix is %d\n', nx); +printf('The number of Ritz values requested is %d\n', nev); +printf('The number of Arnoldi vectors generated (NCV) is %d\n', ncv); +printf('What portion of the spectrum: %s\n', which); +printf('The number of Implicit Arnoldi update iterations taken is %d\n', iparam(3)); +printf('The number of OP*x is %d\n', iparam(9)); +printf('The convergence criterion is %d\n', tol); +]]> + + + + See Also + + + dsaupd + + + dnaupd + + + + + Bibliography + + 1. D.C. Sorensen, "Implicit Application of Polynomial Filters in a + k-Step Arnoldi Method", SIAM J. Matr. Anal. Apps., 13 (1992), pp + 357-385. + + + 2. R.B. Lehoucq, "Analysis and Implementation of an Implicitly + Restarted Arnoldi Iteration", Rice University Technical Report TR95-13, + Department of Computational and Applied Mathematics. + + + 3. B.N. Parlett, "The Symmetric Eigenvalue Problem". Prentice-Hall, + 1980. + + + 4. B.N. Parlett, B. Nour-Omid, "Towards a Black Box Lanczos + Program", Computer Physics Communications, 53 (1989), pp 169-179. + + + 5. B. Nour-Omid, B.N. Parlett, T. Ericson, P.S. Jensen, "How to + Implement the Spectral Transformation", Math. Comp., 48 (1987), pp + 663-673. + + + 6. R.G. Grimes, J.G. Lewis and H.D. Simon, "A Shifted Block Lanczos + Algorithm for Solving Sparse Symmetric Generalized Eigenproblems", SIAM J. + Matr. Anal. Apps., January (1993). + + + 7. L. Reichel, W.B. Gragg, "Algorithm 686: FORTRAN Subroutines for + Updating the QR decomposition", ACM TOMS, December 1990, Volume 16 Number + 4, pp 369-377. + + + 8. R.B. Lehoucq, D.C. Sorensen, "Implementation of Some Spectral + Transformations in a k-Step Arnoldi Method". In Preparation. + + + + Used Functions + Based on ARPACK routine dneupd + + + 履歴 + + + 5.4.0 + + 関数は廃止され,eigsに代替されました. + + + + + diff --git a/modules/arnoldi/help/ja_JP/dsaupd.xml b/modules/arnoldi/help/ja_JP/dsaupd.xml new file mode 100755 index 000000000..051494045 --- /dev/null +++ b/modules/arnoldi/help/ja_JP/dsaupd.xml @@ -0,0 +1,765 @@ + + + + dsaupd + + 暗黙のうちに再開されるArnoldi反復へのインターフェイスで, + 実対称線形演算子の小数の固有値/ベクトルの組を近似的に計算します. + + この関数は廃止されました. eigsを使用してください + + + + + Calling Sequence + [IDO, RESID, V, IPARAM, IPNTR, WORKD, WORKL, INFO] = dsaupd(ID0, BMAT, N, WHICH, NEV, TOL, RESID, NCV, V, IPARAM, IPNTR, WORKD, WORKL, INFO) + + + Arguments + + + ID0 + + Integer. (INPUT/OUTPUT) + + Reverse communication flag. IDO must be zero on the first call + to dsaupd . IDO will be set internally to indicate the type of + operation to be performed. Control is then given back to the calling + routine which has the responsibility to carry out the requested + operation and call dsaupd with the result. + + + The operand is given in WORKD(IPNTR(1)), the result must be put + in WORKD(IPNTR(2)). (If Mode = 2 see remark 5 below) + + + + + IDO = 0: first call to the reverse communication + interface. + + + + + IDO = -1: compute Y = OP * X where IPNTR(1) is the pointer + into WORKD for X, IPNTR(2) is the pointer into WORKD for Y. This + is for the initialization phase to force the starting vector + into the range of OP. + + + + + IDO = 1: compute Y = OP * X where IPNTR(1) is the pointer + into WORKD for X, IPNTR(2) is the pointer into WORKD for Y. In + mode 3, 4 and 5, the vector B * X is already available in + WORKD(ipntr(3)). It does not need to be recomputed in forming OP + * X. + + + + + IDO = 2: compute Y = B * X where IPNTR(1) is the pointer + into WORKD for X, IPNTR(2) is the pointer into WORKD for + Y. + + + + + IDO = 3: compute the IPARAM(8) shifts where IPNTR(11) is + the pointer into WORKL for placing the shifts. See remark 6 + below. + + + + IDO = 99: done + + + + + + BMAT + + Character. (INPUT) + + Specifies the type of the matrix B that defines the semi-inner + product for the operator OP. + + + + 'I': standard eigenvalue problem A * x = lambda * x + + + + 'G': generalized eigenvalue problem A * x = + lambda * B * x + + + + + + + N + + Integer. (INPUT) + Dimension of the eigenproblem. + + + + WHICH + + String of length 2. (INPUT) + Specifies which of the Ritz values of OP to compute. + + + + 'LA' - compute the NEV largest (algebraic) + eigenvalues. + + + + + 'SA' - compute the NEV smallest (algebraic) + eigenvalues. + + + + + 'LM' - compute the NEV largest (in magnitude) + eigenvalues. + + + + + 'SM' - compute the NEV smallest (in magnitude) + eigenvalues. + + + + + 'BE' - compute NEV eigenvalues, half from each end of the + spectrum. When NEV is odd, compute one more from the high end + than from the low end. (see remark 1 below) + + + + + + + NEV + + Integer. (INPUT) + + Number of eigenvalues of OP to be computed. 0 < NEV < + N. + + + + + TOL + + scalar. (INPUT) + + Stopping criterion: the relative accuracy of the Ritz value is + considered acceptable if BOUNDS(I) <= TOL * ABS(RITZ(I)). If TOL + <= 0. is passed the machine precision is set. + + + + + RESID + + Array of length N. (INPUT/OUTPUT) + + On INPUT: If INFO = 0, a random initial residual vector is + used, else RESID contains the initial residual vector, possibly from + a previous run. + + On OUTPUT: RESID contains the final residual vector. + + + + NCV + + Integer. (INPUT) + + Number of columns of the matrix V (less than or equal to N). + + + This will indicate how many Lanczos vectors are generated at + each iteration. After the startup phase in which NEV Lanczos vectors + are generated, the algorithm generates NCV - NEV Lanczos vectors at + each subsequent update iteration. Most of the cost in generating + each Lanczos vector is in the matrix-vector product OP * x. (See + remark 4 below). + + + + + V + + N by NCV array. (OUTPUT) + The NCV columns of V contain the Lanczos basis vectors. + + + + IPARAM + + array of length 11. (INPUT/OUTPUT) + + + + IPARAM(1) = ISHIFT: method for selecting the implicit + shifts. The shifts selected at each iteration are used to + restart the Arnoldi iteration in an implicit fashion. + + + + + ISHIFT = 0: the shifts are provided by the user via + reverse communication. The NCV eigenvalues of the current + tridiagonal matrix T are returned in the part of WORKL array + corresponding to RITZ. See remark 6 below. + + + + + ISHIFT = 1: exact shifts with respect to the reduced + tridiagonal matrix T. This is equivalent to restarting the + iteration with a starting vector that is a linear + combination of Ritz vectors associated with the "wanted" + Ritz values. + + + + + + + IPARAM(2) = LEVEC. No longer referenced. See remark 2 + below. + + + + IPARAM(3) = MXITER + + On INPUT: maximum number of Arnoldi update iterations + allowed. + + + On OUTPUT: actual number of Arnoldi update iterations + taken. + + + + + IPARAM(4) = NB: blocksize to be used in the recurrence. + The code currently works only for NB = 1. + + + + + IPARAM(5) = NCONV: number of "converged" Ritz values. This + represents the number of Ritz values that satisfy the + convergence criterion. + + + + + IPARAM(6) = IUPD No longer referenced. Implicit restarting + is ALWAYS used. + + + + + IPARAM(7) = MODE On INPUT determines what type of + eigenproblem is being solved. Must be 1,2,3,4,5; See under + Description of dsaupd for the five modes available. + + + + + IPARAM(8) = NP When ido = 3 and the user provides shifts + through reverse communication (IPARAM(1)=0), dsaupd returns NP, + the number of shifts the user is to provide. 0 < NP <= + NCV-NEV. See Remark 6 below. + + + + IPARAM(9) = NUMOP, + IPARAM(10) = NUMOPB, + + IPARAM(11) = NUMREO, OUTPUT: NUMOP = total number of OP*x + operations, NUMOPB = total number of B*x operations if BMAT='G', + NUMREO = total number of steps of re-orthogonalization. + + + + + + + IPNTR + + + array of length 11. (OUTPUT) + + + Pointer to mark the starting locations in + the WORKD and WORKL arrays for matrices/vectors used by the Lanczos + iteration. + + + + + IPNTR(1): pointer to the current operand vector X in + WORKD. + + + + + IPNTR(2): pointer to the current result vector Y in + WORKD. + + + + + IPNTR(3): pointer to the vector B * X in WORKD when used + in the shift-and-invert mode. + + + + + IPNTR(4): pointer to the next available location in WORKL + that is untouched by the program. + + + + + IPNTR(5): pointer to the NCV by 2 tridiagonal matrix T in + WORKL. + + + + + IPNTR(6): pointer to the NCV RITZ values array in + WORKL. + + + + + IPNTR(7): pointer to the Ritz estimates in array WORKL + associated with the Ritz values located in RITZ in WORKL. + + + + + IPNTR(11): pointer to the NP shifts in WORKL. See Remark 6 + below. + + + + + Note: IPNTR(8:10) is only referenced by dseupd . See Remark + 2. + + + + + IPNTR(8): pointer to the NCV RITZ values of the original + system. + + + + + IPNTR(9): pointer to the NCV corresponding error + bounds. + + + + + IPNTR(10): pointer to the NCV by NCV matrix of + eigenvectors of the tridiagonal matrix T. Only referenced by + dseupd if RVEC = 1. See Remarks + + + + + + + WORKD + + work array of length 3 * N. (REVERSE COMMUNICATION) + + Distributed array to be used in the basic Arnoldi iteration + for reverse communication. The user should not use WORKD as + temporary workspace during the iteration. Upon termination + WORKD(1:N) contains B*RESID(1:N). If the Ritz vectors are desired + subroutine dseupd uses this output. See Data Distribution Note + below. + + + + + WORKL + + + work array of length at least NCV ** 2 + 8 * NCV. + (OUTPUT/WORKSPACE) + + + Private (replicated) array on each PE or array allocated on + the front end. See Data Distribution Note below. add here the + parameter description. + + + + + INFO + + Integer. (INPUT/OUTPUT) + + If INFO = 0, a randomly initial residual vector is used, else + RESID contains the initial residual vector, possibly from a previous + run. + + Error flag on output. + + + 0: Normal exit. + + + + 1: Maximum number of iterations taken. All possible + eigenvalues of OP has been found. IPARAM(5) returns the number + of wanted converged Ritz values. + + + + + 2: No longer an informational error. Deprecated starting + with release 2 of ARPACK. + + + + + 3: No shifts could be applied during a cycle of the + Implicitly restarted Arnoldi iteration. One possibility is to + increase the size of NCV relative to NEV. See remark 4 + below. + + + + -1: N must be positive. + + + -2: NEV must be positive. + + + + -3: NCV must be greater than NEV and less than or equal to + N. + + + + + -4: The maximum number of Arnoldi update iterations + allowed must be greater than zero. + + + + + -5: WHICH must be one of 'LM', 'SM', 'LA', 'SA' or + 'BE'. + + + + -6: BMAT must be one of 'I' or 'G'. + + + + -7: Length of private work array WORKL is not + sufficient. + + + + + -8: Error return from trid. eigenvalue calculation; + Informatinal error from LAPACK routine dsteqr. + + + + -9: Starting vector is zero. + + + -10: IPARAM(7) must be 1, 2, 3, 4, 5. + + + -11: IPARAM(7) = 1 and BMAT = 'G' are incompatable. + + + -12: IPARAM(1) must be equal to 0 or 1. + + + -13: NEV and WHICH = 'BE' are incompatable. + + + + -9999: Could not build an Arnoldi factorization. IPARAM(5) + returns the size of the current Arnoldi factorization. The user + is advised to check that enough workspace and array storage has + been allocated. + + + + + + + + + Description + + Reverse communication interface for the Implicitly Restarted Arnoldi + Iteration. For symmetric problems this reduces to a variant of the Lanczos + method. This method has been designed to compute approximations to a few + eigenpairs of a linear operator OP that is real and symmetric with respect + to a real positive semi-definite symmetric matrix B, i.e. + B * OP = + (OP`) * B + + . + + + Another way to express this condition is + < x,OPy > = + < OPx,y > where <z,w > = z`Bw + + . + + + In the standard eigenproblem B is the identity matrix. ( A` denotes + transpose of A) + + + The computed approximate eigenvalues are called Ritz values and the + corresponding approximate eigenvectors are called Ritz vectors. + + + dsaupd is usually called iteratively to solve one of the following + problems: + + + + + Mode 1: A * x = lambda * x, A symmetric ===> OP = A and B = + I. + + + + + Mode 2: A * x = lambda * M * x, A symmetric, M symmetric positive + definite ===> OP = inv[M] * A and B = M. ===> (If M can be + factored see remark 3 below) + + + + + Mode 3: K * x = lambda * M * x, K symmetric, M symmetric positive + semi-definite ===> OP = (inv[K - sigma * M]) * M and B = M. ===> + Shift-and-Invert mode + + + + + Mode 4: K * x = lambda * KG * x, K symmetric positive semi-definite, + KG symmetric indefinite ===> OP = (inv[K - sigma * KG]) * K and B = K. + ===> Buckling mode + + + + + Mode 5: A * x = lambda * M * x, A symmetric, M symmetric positive + semi-definite ===> OP = inv[A - sigma * M] * [A + sigma * M] and B = M. + ===> Cayley transformed mode + + + + + NOTE: The action of w <- inv[A - sigma * M] * v or w <- inv[M] * v + should be accomplished either by a direct method using a sparse matrix + factorization and solving + [A - sigma * M] * w = v or M * w = + v + + , + + + or through an iterative method for solving these systems. If an + iterative method is used, the convergence test must be more stringent than + the accuracy requirements for the eigenvalue approximations. + + + + Remarks + + 1. The converged Ritz values are always returned in ascending + algebraic order. The computed Ritz values are approximate eigenvalues of + OP. The selection of WHICH should be made with this in mind when Mode = + 3, 4, 5. After convergence, approximate eigenvalues of the original problem + may be obtained with the ARPACK subroutine dseupd . + + + 2. If the Ritz vectors corresponding to the converged Ritz values + are needed, the user must call dseupd immediately following completion of + dsaupd . This is new starting with version 2.1 of ARPACK. + + + 3. If M can be factored into a Cholesky factorization M = LL` then + Mode = 2 should not be selected. Instead one should use Mode = 1 with OP = + inv(L) * A * inv(L`). Appropriate triangular linear systems should be solved + with L and L` rather than computing inverses. After convergence, an + approximate eigenvector z of the original problem is recovered by solving + L`z = x where x is a Ritz vector of OP. + + + 4. At present there is no a-priori analysis to guide the selection + of NCV relative to NEV. The only formal requirement is that NCV > NEV. + However, it is recommended that NCV >= 2 * NEV. If many problems of the + same type are to be solved, one should experiment with increasing NCV + while keeping NEV fixed for a given test problem. This will usually + decrease the required number of OP * x operations but it also increases the + work and storage required to maintain the orthogonal basis vectors. The + optimal "cross-over" with respect to CPU time is problem dependent and + must be determined empirically. + + + 5. If IPARAM(7) = 2 then in the Reverse communication interface the + user must do the following. When IDO = 1, Y = OP * X is to be computed. + When IPARAM(7) = 2 OP = inv(B) * A. After computing A * X the user must + overwrite X with A * X. Y is then the solution to the linear set of + equations B * Y = A * X. + + + 6. When IPARAM(1) = 0, and IDO = 3, the user needs to provide the NP + = IPARAM(8) shifts in locations: 1 WORKL(IPNTR(11)) 2 WORKL(IPNTR(11) + 1) . + . . NP WORKL(IPNTR(11) + NP - 1). The eigenvalues of the current tridiagonal + matrix are located in WORKL(IPNTR(6)) through WORKL(IPNTR(6) + NCV - 1). They + are in the order defined by WHICH. The associated Ritz estimates are + located in WORKL(IPNTR(8)), WORKL(IPNTR(8) + 1), ... , + WORKL(IPNTR(8) + NCV - 1). + + + + Example + + 99) + // Repeatedly call the routine DSAUPD and take actions indicated by parameter IDO until + // either convergence is indicated or maxitr has been exceeded. + [ido, resid, v, iparam, ipntr, workd, workl, info_dsaupd] = dsaupd(ido, bmat, nx, which, nev, tol, resid, ncv, v, iparam, ipntr, workd, workl, info_dsaupd); + if(info_dsaupd < 0) + printf('\nError with dsaupd, info = %d\n',info_dsaupd); + printf('Check the documentation of dsaupd\n\n'); + end + if(ido == -1 | ido == 1) + // Perform matrix vector multiplication + workd(ipntr(2):ipntr(2) + nx - 1) = A * workd(ipntr(1):ipntr(1) + nx - 1); + end +end +// Post-Process using DSEUPD. +rvec = 1; +howmany = 'A'; +info_dseupd = 0; +[d, z, resid, v, iparam, ipntr, workd, workl, info_dseupd] = dseupd(rvec, howmany, _select, d, z, sigma, bmat, nx, which, nev, tol, resid, ncv, v, ... + iparam, ipntr, workd, workl, info_dseupd); +if(info_dseupd < 0) + printf('\nError with dseupd, info = %d\n', info_dseupd); + printf('Check the documentation of dseupd.\n\n'); +end +// Done with program dssimp. +printf('\nDSSIMP\n'); +printf('======\n'); +printf('\n'); +printf('Size of the matrix is %d\n', nx); +printf('The number of Ritz values requested is %d\n', nev); +printf('The number of Arnoldi vectors generated (NCV) is %d\n', ncv); +printf('What portion of the spectrum: %s\n', which); +printf('The number of Implicit Arnoldi update iterations taken is %d\n', iparam(3)); +printf('The number of OP*x is %d\n', iparam(9)); +printf('The convergence criterion is %d\n', tol); +]]> + + + + See Also + + + dnaupd + + + dseupd + + + + + Bibliography + + 1. D.C. Sorensen, "Implicit Application of Polynomial Filters in a + k-Step Arnoldi Method", SIAM J. Matr. Anal. Apps., 13 (1992), pp + 357-385. + + + 2. R.B. Lehoucq, "Analysis and Implementation of an Implicitly + Restarted Arnoldi Iteration", Rice University Technical Report TR95-13, + Department of Computational and Applied Mathematics. + + + 3. B.N. Parlett and Y. Saad, "Complex Shift and Invert Strategies + for Real Matrices", Linear Algebra and its Applications, vol 88/89, pp + 575-595, (1987). + + + + Used Functions + Based on ARPACK routine dsaupd + + + 履歴 + + + 5.4.0 + + 関数は廃止され,eigsに代替されました. + + + + + diff --git a/modules/arnoldi/help/ja_JP/dseupd.xml b/modules/arnoldi/help/ja_JP/dseupd.xml new file mode 100755 index 000000000..87490a423 --- /dev/null +++ b/modules/arnoldi/help/ja_JP/dseupd.xml @@ -0,0 +1,440 @@ + + + + dseupd + + 暗黙のうちに再開されるArnoldi反復へのインターフェイスで, + A * z = lambda * B * z の固有値を収束的近似により計算します. + + この関数は廃止されました. eigsを使用してください + + + + + Calling Sequence + + [D, Z, RESID, V, IPARAM, IPNTR, WORKD, WORKL, INFO] = dseupd(RVEC, HOWMANY, SELECT, D, Z, SIGMA, BMAT, N, WHICH, + NEV, TOL, RESID, NCV, V, IPARAM, IPNTR, WORKD, WORKL, INFO) + + + + Arguments + + + RVEC + + Integer. (INPUT) + + Specifies whether Ritz vectors corresponding to the Ritz value + approximations to the eigenproblem A * z = lambda * B * z are + computed. + + + + RVEC = 0 Compute Ritz values only. + + + RVEC = 1 Compute Ritz vectors. + + + + + + HOWMNY + + Character*1. (INPUT) + + Specifies how many Ritz vectors are wanted and the form of Z + the matrix of Ritz vectors. See remark 1 below. + + + + 'A': compute NEV Ritz vectors; + + + + 'S': compute some of the Ritz vectors, specified by the + integer array SELECT. + + + + + + + SELECT + + Integer array of dimension NCV. (INPUT/WORKSPACE) + + If HOWMANY = 'S', SELECT specifies the Ritz vectors to be + computed. To select the Ritz vector corresponding to a Ritz value + D(j), SELECT(j) must be set to 1. + + + If HOWMANY = 'A' , SELECT is used as a workspace for + reordering the Ritz values. + + + + + D + + Double precision array of dimension NEV. (OUTPUT) + + On exit, D contains the Ritz value approximations to the + eigenvalues of A * z = lambda * B * z. The values are returned in + ascending order. + + + If IPARAM(7) = 3, 4, 5 then D represents the Ritz values of OP + computed by dsaupd transformed to those of the original eigensystem + A * z = lambda * B * z. + + + If IPARAM(7) = 1, 2 then the Ritz values of OP are the same as + the those of A * z = lambda * B * z. + + + + + Z + + Double precision N by NEV array. + + If HOWMNY = 'A'. (OUTPUT) On exit, Z contains the + B-orthonormal Ritz vectors of the eigensystemA * z = lambda * B * z + corresponding to the Ritz value approximations. + + If RVEC = 0 then Z is not referenced. + + NOTE: The array Z may be set equal to first NEV columns of the + Arnoldi/Lanczos basis array V computed by DSAUPD . + + + + + SIGMA + + Double precision (INPUT) + + If IPARAM(7) = 3, 4, 5 represents the shift. Not referenced if + IPARAM(7) = 1 or 2. + + + + + + NOTE: The remaining arguments BMAT, N, WHICH, NEV, TOL, RESID, NCV, + V, IPARAM, IPNTR, WORKD, WORKL, LWORKL, INFO must be passed directly to + DSEUPD following the last call to DSAUPD . + + + These arguments MUST NOT BE MODIFIED between the last call to + DSAUPD and the call to DSEUPD. + + + Two of these parameters (WORKL, INFO) are also output + parameters. + + + + WORKL + + + Double precision work array of length LWORKL. + (OUTPUT/WORKSPACE) + + + WORKL(1:4*ncv) contains information obtained in dsaupd. They + are not changed by dseupd. + + + WORKL(4*ncv+1:ncv*ncv+8*ncv) holds the untransformed Ritz + values, the computed error estimates, and the associated eigenvector + matrix of H. + + + Note: IPNTR(8:10) contains the pointer into WORKL for + addresses of the above information computed by dseupd . + + + + + IPNTR(8): pointer to the NCV RITZ values of the original + system. + + + + + IPNTR(9): pointer to the NCV corresponding error bounds. + + + + + IPNTR(10): pointer to the NCV by NCV matrix of + eigenvectors of the tridiagonal matrix T. Only referenced by + dseupd if RVEC = 1 See Remarks. + + + + + + + INFO + + Integer. (OUTPUT) + Error flag on output. + + + 0: Normal exit. + + + -1: N must be positive. + + + -2: NEV must be positive. + + + + -3: NCV must be greater than NEV and less than or equal to + N. + + + + + -5: WHICH must be one of 'LM', 'SM', 'LA', 'SA' or + 'BE'. + + + + -6: BMAT must be one of 'I' or 'G'. + + + + -7: Length of private work WORKL array is not + sufficient. + + + + + -8: Error return from trid. eigenvalue calculation; + Information error from LAPACK routine dsteqr. + + + + -9: Starting vector is zero. + + + -10: IPARAM(7) must be 1, 2, 3, 4, 5. + + + -11: IPARAM(7) = 1 and BMAT = 'G' are incompatible. + + + -12: NEV and WHICH = 'BE' are incompatible. + + + + -14: DSAUPD did not find any eigenvalues to sufficient + accuracy. + + + + -15: HOWMNY must be one of 'A' or 'S' if RVEC = 1. + + + -16: HOWMNY = 'S' not yet implemented. + + + + -17: DSEUPD got a different count of the number of + converged Ritz values than DSAUPD got. This indicates the user + probably made an error in passing data from DSAUPD to DSEUPD or + that the data was modified before entering DSEUPD. + + + + + + + + + Description + + This subroutine returns the converged approximations to eigenvalues + of A * z = lambda * B * z and (optionally): + + + + the corresponding approximate eigenvectors, + + + + an orthonormal (Lanczos) basis for the associated approximate + invariant subspace, + + + + Both. + + + + There is negligible additional cost to obtain eigenvectors. An + orthonormal (Lanczos) basis is always computed. There is an additional + storage cost of n*nev if both are requested (in this case a separate array + Z must be supplied). + + + These quantities are obtained from the Lanczos factorization + computed by DSAUPD for the linear operator OP prescribed by the MODE + selection (see IPARAM(7) in DSAUPD documentation.) DSAUPD must be called + before this routine is called. + + + These approximate eigenvalues and vectors are commonly called Ritz + values and Ritz vectors respectively. They are referred to as such in the + comments that follow. + + + The computed orthonormal basis for the invariant subspace + corresponding to these Ritz values is referred to as a Lanczos basis. + + + See documentation in the header of the subroutine DSAUPD for a + definition of OP as well as other terms and the relation of computed Ritz + values and vectors of OP with respect to the given problem A * z = lambda * B * z. + + + The approximate eigenvalues of the original problem are returned in + ascending algebraic order. + + + The user may elect to call this routine once for each desired Ritz + vector and store it peripherally if desired. There is also the option of + computing a selected set of these vectors with a single call. + + + + Remarks + + 1. The converged Ritz values are always returned in increasing + (algebraic) order. c 2. Currently only HOWMNY = 'A' is implemented. It is + included at this stage for the user who wants to incorporate it. + + + + Example + + 99) + // Repeatedly call the routine DSAUPD and take actions indicated by parameter IDO until + // either convergence is indicated or maxitr has been exceeded. + [ido, resid, v, iparam, ipntr, workd, workl, info_dsaupd] = dsaupd(ido, bmat, nx, which, nev, tol, resid, ncv, v, iparam, ipntr, workd, workl, info_dsaupd); + if(info_dsaupd < 0) + printf('\nError with dsaupd, info = %d\n',info_dsaupd); + printf('Check the documentation of dsaupd\n\n'); + end + if(ido == -1 | ido == 1) + // Perform matrix vector multiplication + workd(ipntr(2):ipntr(2) + nx - 1) = A * workd(ipntr(1):ipntr(1) + nx - 1); + end +end +// Post-Process using DSEUPD. +rvec = 1; +howmany = 'A'; +info_dseupd = 0; +[d, z, resid, v, iparam, ipntr, workd, workl, info_dseupd] = dseupd(rvec, howmany, _select, d, z, sigma, bmat, nx, which, nev, tol, resid, ncv, v, ... + iparam, ipntr, workd, workl, info_dseupd); +if(info_dseupd < 0) + printf('\nError with dseupd, info = %d\n', info_dseupd); + printf('Check the documentation of dseupd.\n\n'); +end +// Done with program dssimp. +printf('\nDSSIMP\n'); +printf('======\n'); +printf('\n'); +printf('Size of the matrix is %d\n', nx); +printf('The number of Ritz values requested is %d\n', nev); +printf('The number of Arnoldi vectors generated (NCV) is %d\n', ncv); +printf('What portion of the spectrum: %s\n', which); +printf('The number of Implicit Arnoldi update iterations taken is %d\n', iparam(3)); +printf('The number of OP*x is %d\n', iparam(9)); +printf('The convergence criterion is %d\n', tol); +]]> + + + + See Also + + + dsaupd + + + dneupd + + + + + Bibliography + + 1. D.C. Sorensen, "Implicit Application of Polynomial Filters in + k-Step Arnoldi Method", SIAM J. Matr. Anal. Apps., 13 (1992), pp + 357-385. + + + 2. R.B. Lehoucq, "Analysis and Implementation of an Implicitly + Restarted Arnoldi Iteration", Rice University Technical Report TR95-13, + Department of Computational and Applied Mathematics. + + + 3. B.N. Parlett and Y. Saad, "Complex Shift and Invert Strategies + for Real Matrices", Linear Algebra and its Applications, vol 88/89, pp + 575-595, (1987). + + + + Used Functions + Based on ARPACK routine dseupd + + + 履歴 + + + 5.4.0 + + 関数は廃止され,eigsに代替されました. + + + + + diff --git a/modules/arnoldi/help/ja_JP/eigs.xml b/modules/arnoldi/help/ja_JP/eigs.xml new file mode 100755 index 000000000..b47056695 --- /dev/null +++ b/modules/arnoldi/help/ja_JP/eigs.xml @@ -0,0 +1,526 @@ + + + + + eigs + + 行列の最大固有値と固有ベクトルを計算 + + + + 呼び出し手順 + + d = eigs(A [,B [,k [,sigma [,opts]]]]) + [d, v] = eigs(A [,B [,k [,sigma [,opts]]]]) + d = eigs(Af, n [,B [,k [,sigma [,opts]]]]) + [d, v] = eigs(Af, n [,B [,k [,sigma [,opts]]]]) + + + + 引数 + + + A + + 通常または疎, 実数または複素数, 対称または非対称正方行列 + + + + Af + + 関数 + + + + n + + + スカラー, Aが関数の場合のみ A 定義 + + + + + B + + + Aと同じ次元の + 疎, 実数または複素数, 正方行列 + + + + + k + + 整数, 計算する固有値の数 + + + + sigma + + 実スカラーまたは長さ2の文字列 + + + + opts + + 構造体 + + + + d + + 実数または複素数の固有値ベクトルまたは対角行列 (対角項に固有値) + + + + v + + + 実数または複素数の固有ベクトル行列 + + + + + + + 説明 + + eigs関数の目的は,疎で大きな行列の最大固有値を計算することです. + + + + d = eigs(A) または d = eigs(Af, n) + + + は,固有値問題A * v = lambda * vを解きます. + このコールは,大きさが最大の6個の固有値を有する + ベクトル dを返します. + A は正方行列で, + 対称または非対称, 実数または複素数, 通常または複素数 + とすることができます. + + + A は関数Afで + 表すことも可能です.この場合, + ベクトル引数の長さを指定するスカラーnを + 定義する必要があります. + この関数は,以下のヘッダを有する必要があります: + + + + + + この関数 Af は以下の4つの式の1つを返す必要があります: + + + A * x + sigmaが指定されないか文字列が'SM'以外の場合. + + + A \ x + sigmaが0または'SM'の場合. + + + (A - sigma * I) \ x + 標準固有値問題の場合, ただし I は単位行列. + + + (A - sigma * B) \ x + 一般化固有値問題の場合. + + + + + + + [d, v] = eigs(A) or [d, v] = eigs(Af, n) + + + は,6個の最大固有値を対角項に有する対角行列 d を返します. + v は n行6列の行列で, + その列は返された固有値に対応する6個の固有値ベクトルです. + + + + + d = eigs(A, B) + + + は,正定行列Bを指定して, + 一般化固有値問題 A * v = lambda * B * v + を解きます. + + + + + B が指定されない場合, + B = [] が使用されます. + + + + + B が指定された場合, + B はAと同じ大きさとする必要があります. + + + + + + + d = eigs(A, B, k) + + + は,k個の固有値をベクトルdに返します. + k が指定されない場合, + k = min(n, 6), ただし, nはAの行数となります. + + + + + d = eigs(A, B, k, sigma) + + + は,sigmaで定義されたk個の固有値を + ベクトルdに返します. + sigma は,0を含む実数または複素数,または文字列 + とすることができます. + sigma が長さ2の文字列の場合, 以下の値のどれかとします : + + + + + 'LM' は,大きさが最大のk個の + 固有値を計算します(デフォルト). + + + + + 'SM' は,大きさが最小のk個の + 固有値を計算します(sigma = 0 と同じ). + + + + + 'LA' は,実対称問題のみに適用され, + k個の代数的最大固有値を計算します. + + + + + 'SA' は,実対称問題のみに適用され, + k個の代数的最小固有値を計算します. + + + + + 'BE' は,実対称問題のみに適用され, + スペクトラムの各端から半分づつ,k個の固有値を計算します. + + + + + 'LR' は,実非対称または複素問題のみに適用され, + k個の実部最大の固有値を計算します. + + + + + 'SR' は,実非対称または複素問題のみに適用され, + k個の実部最小の固有値を計算します. + + + + + 'LI' は,実非対称または複素問題のみに適用され, + k個の虚部最大の固有値を計算します. + + + + + 'SI' は,実非対称または複素問題のみに適用され, + k個の虚部最小の固有値を計算します. + + + + + + + d = eigs(A, B, k, sigma, opts) + + + opts 構造体が指定された場合, + k 個の固有値を計算する際に + 異なるオプションを使用できます: + + + + + tol + + 所要の収束閾値. デフォルトで, tol = %eps. + + + + + + maxiter + + 最大反復回数. デフォルトで, maxiter = 300. + + + + + + ncv + + 使用するLanzcos基底ベクトルの数. + 実非対称問題の場合, ncvの値は + 2 * k + 1 以上とする必要があり, + デフォルトで ncv = min(max(2 * k + 1, 20), nA) です. + 実対称または複素数問題の場合,ncvは + 2 * k 以上とする必要があり, + デフォルトで ncv = min(max(2 * k, 20), nA) + です.ただし, nA = size(A, 2) . + + + + + + resid + + 初期残差ベクトルを有する開始ベクトルで, + 前回実行時の値を使用することもできます. + デフォルトで,resid はランダムな + 初期値ベクトルです. + + + + + + cholB + + Bではなく + chol(B)を指定します. + デフォルトで + , cholB は %f です. + + + + + + isreal + + Af が指定された場合, + isreal を定義できます. + デフォルトで, isreal は %t です. + この引数は,Aが行列の場合, + 指定する必要がありません. + + + + + + issym + + Af が指定された場合, + issym を定義できます. + デフォルトで issym は %f です. + この引数は,Aが行列の場合, + 指定する必要がありません. + + + + + + + + + + 参考文献 + + この関数はR. Lehoucq, K. Maschhoff, D. Sorensen, および C. Yang.により書かれた + ARPACKパッケージに基づいています. + + + + 実対称問題用のDSAUPD および DSEUPD ルーチン, + + + 実非対称行列用のDNAUPD および DNEUPD ルーチン. + + + 複素問題用のZNAUPD および ZNEUPD. + + + + + 実対称問題の例 + + + + + + 実非対称問題の例 + + + + + + 複素問題の例 + + + + + + 参照 + + + spec + + + + + 履歴 + + + 5.4.0 + + 関数が導入されました. + dnaupd, dneupd, dsaupd, dseupd, znaupd および zneupdは廃止されました. + + + + + diff --git a/modules/arnoldi/help/ja_JP/znaupd.xml b/modules/arnoldi/help/ja_JP/znaupd.xml new file mode 100755 index 000000000..4db374b2d --- /dev/null +++ b/modules/arnoldi/help/ja_JP/znaupd.xml @@ -0,0 +1,780 @@ + + + + znaupd + + 暗黙のうちに再開されるArnoldi反復へのインターフェイスで, + エルミート準正定実行列Bにより定義される準内積に関する + 複素線形演算子 OP の小数の固有値/ベクトルの組を近似的に計算します. + + この関数は廃止されました. eigsを使用してください + + + + + Calling Sequence + [IDO, RESID, V, IPARAM, IPNTR, WORKD, WORKL, RWORK, INFO] = znaupd(ID0, BMAT, N, WHICH, NEV, TOL, RESID, NCV, V, IPARAM, IPNTR, WORKD, WORKL, RWORK, INFO) + + + Arguments + + + IDO + + Integer. (INPUT/OUTPUT) + + Reverse communication flag. IDO must be zero on the first call + to znaupd. IDO will be set internally to indicate the type of + operation to be performed. Control is then given back to the calling + routine which has the responsibility to carry out the requested + operation and call znaupd with the result. + + + The operand is given in WORKD(IPNTR(1)), the result must be + put in WORKD(IPNTR(2)). + + + + + IDO = 0: first call to the reverse communication interface + + + + + IDO = -1: compute Y = OP * X where IPNTR(1) is the pointer + into WORKD for X, IPNTR(2) is the pointer into WORKD for Y. + + + This is for the initialization phase to force the starting + vector into the range of OP. + + + + + IDO = 1: compute Y = OP * X where IPNTR(1) is the pointer + into WORKD for X, IPNTR(2) is the pointer into WORKD for Y. + + + In mode 3, the vector B * X is already available in + WORKD(ipntr(3)). It does not need to be recomputed in forming OP + * X. + + + + + IDO = 2: compute Y = M * X where IPNTR(1) is the pointer + into WORKD for X, IPNTR(2) is the pointer into WORKD for + Y. + + + + + IDO = 3: compute and return the shifts in the first NP + locations of WORKL. + + + + IDO = 99: done + + + + After the initialization phase, when the routine is used in + the "shift-and-invert" mode, the vector M * X is already available + and does not need to be recomputed in forming OP*X. + + + + + BMAT + + Character. (INPUT) + + specifies the type of the matrix B that defines the + semi-inner product for the operator OP. + + + + 'I': standard eigenvalue problem A * x = lambda * x + + + + 'G': generalized eigenvalue problem A * x = + lambda * M * x + + + + + + + N + + Integer. (INPUT) + Dimension of the eigenproblem. + + + + WHICH + + string of length 2. (INPUT) + + + + 'LM': want the NEV eigenvalues of largest + magnitude. + + + + + 'SM': want the NEV eigenvalues of smallest + magnitude. + + + + + 'LR': want the NEV eigenvalues of largest real + part. + + + + + 'SR': want the NEV eigenvalues of smallest real part. + + + + + 'LI': want the NEV eigenvalues of largest imaginary + part. + + + + + 'SI': want the NEV eigenvalues of smallest imaginary + part. + + + + + + + NEV + + Integer. (INPUT) + + Number of eigenvalues of OP to be computed. 0 < NEV < + N - 1. + + + + + TOL + + Double precision scalar. (INPUT) + + Stopping criteria: the relative accuracy of the Ritz value is + considered acceptable if BOUNDS(I) .LE. TOL * ABS(RITZ(I)) where + ABS(RITZ(I)) is the magnitude when RITZ(I) is complex. DEFAULT = + dlamch('EPS') (machine precision as computed by the LAPACK auxiliary + subroutine dlamch). + + + + + RESID + + Complex*16 array of length N. (INPUT/OUTPUT) + + On INPUT: If INFO .EQ. 0, a random initial residual vector is + used. If INFO .NE. 0, RESID contains the initial residual vector, + possibly from a previous run. + + On OUTPUT: RESID contains the final residual vector. + + + + NCV + + Integer. (INPUT) + + Number of columns of the matrix V. NCV must satisfy the two + inequalities 2 <= NCV - NEV and NCV <= N. + + + This will indicate how many Arnoldi vectors are generated at + each iteration. After the startup phase in which NEV Arnoldi vectors + are generated, the algorithm generates approximately NCV - NEV Arnoldi + vectors at each subsequent update iteration. Most of the cost in + generating each Arnoldi vector is in the matrix-vector operation + OP * x. (See remark 4 below.) + + + + + V + + Complex*16 array N by NCV. (OUTPUT) + Contains the final set of Arnoldi basis vectors. + + + + IPARAM + + Integer array of length 11. (INPUT/OUTPUT) + + + + IPARAM(1) = ISHIFT: method for selecting the implicit + shifts. The shifts selected at each iteration are used to filter + out the components of the unwanted eigenvector. + + + + + ISHIFT = 0: the shifts are to be provided by the user + via reverse communication. The NCV eigenvalues of the + Hessenberg matrix H are returned in the part of WORKL array + corresponding to RITZ. + + + + + ISHIFT = 1: exact shifts with respect to the current + Hessenberg matrix H. This is equivalent to restarting the + iteration from the beginning after updating the starting + vector with a linear combination of Ritz vectors associated + with the "wanted" eigenvalues. + + + + + ISHIFT = 2: other choice of internal shift to be + defined. + + + + + + IPARAM(2) = No longer referenced + + + IPARAM(3) = MXITER + + On INPUT: maximum number of Arnoldi update iterations + allowed. + + + On OUTPUT: actual number of Arnoldi update iterations + taken. + + + + + IPARAM(4) = NB: blocksize to be used in the recurrence. + The code currently works only for NB = 1. + + + + + IPARAM(5) = NCONV: number of "converged" Ritz values. This + represents the number of Ritz values that satisfy the + convergence criterion. + + + + + IPARAM(6) = IUPD No longer referenced. Implicit restarting + is ALWAYS used. + + + + + IPARAM(7) = MODE On INPUT determines what type of + eigenproblem is being solved. Must be 1,2,3; See under + Description of znaupd for the four modes available. + + + + + IPARAM(8) = NP When ido = 3 and the user provides shifts + through reverse communication (IPARAM(1)=0), _naupd returns NP, + the number of shifts the user is to provide. 0 < NP < + NCV-NEV. + + + + IPARAM(9) = NUMOP, + IPARAM(10) = NUMOPB, + + IPARAM(11) = NUMREO, OUTPUT: NUMOP = total number of OP*x + operations, NUMOPB = total number of B*x operations if BMAT='G', + NUMREO = total number of steps of re-orthogonalization. + + + + + + + IPNTR + + Integer array of length 14. (OUTPUT) + + Pointer to mark the starting locations in the WORKD and WORKL + arrays for matrices/vectors used by the Arnoldi iteration. + + + + + IPNTR(1): pointer to the current operand vector X in + WORKD. + + + + + IPNTR(2): pointer to the current result vector Y in + WORKD. + + + + + IPNTR(3): pointer to the vector B * X in WORKD when used + in the shift-and-invert mode. + + + + + IPNTR(4): pointer to the next available location in WORKL + that is untouched by the program. + + + + + IPNTR(5): pointer to the NCV by NCV upper Hessenberg + matrix H in WORKL. + + + + IPNTR(6): pointer to the ritz value array RITZ + + + + IPNTR(7): pointer to the (projected) ritz vector array Q + + + + + IPNTR(8): pointer to the error BOUNDS array in WORKL. + + + + + IPNTR(14): pointer to the NP shifts in WORKL. See Remark 5 + below. + + + + + Note: IPNTR(9:13) is only referenced by zneupd. See Remark 2 + below. + + + + + IPNTR(9): pointer to the NCV RITZ values of the original + system. + + + + IPNTR(10): Not Used + + + + IPNTR(11): pointer to the NCV corresponding error + bounds. + + + + + IPNTR(12): pointer to the NCV by NCV upper triangular + Schur matrix for H. + + + + + IPNTR(13): pointer to the NCV by NCV matrix of + eigenvectors of the upper Hessenberg matrix H. Only referenced + by zneupd if RVEC = 1 See Remark 2 below. + + + + + + + WORKD + + + Complex*16 work array of length 3 * N. (REVERSE COMMUNICATION) + + + Distributed array to be used in the basic Arnoldi iteration + for reverse communication. + + + The user should not use WORKD as temporary workspace during + the iteration !!!!!!!!!! + + See Data Distribution Note below. + + + + WORKL + + + Complex*16 work array of length 3 * NCV ** 2 + 5 * NCV. (OUTPUT/WORKSPACE) + + + Private (replicated) array on each PE or array allocated on + the front end. See Data Distribution Note below. + + + + + RWORK + + + Double precision work array of length NCV (WORKSPACE) Private + (replicated) array on each PE or array allocated on the front + end. + + + + + INFO + + Integer. (INPUT/OUTPUT) + + If INFO == 0, a randomly initial residual vector is used. + + + If INFO ~= 0, RESID contains the initial residual vector, + possibly from a previous run. + + Error flag on output. + + + 0: Normal exit. + + + + 1: Maximum number of iterations taken. All possible + eigenvalues of OP has been found. IPARAM(5) returns the number + of wanted converged Ritz values. + + + + + 2: No longer an informational error. Deprecated starting + with release 2 of ARPACK. + + + + + 3: No shifts could be applied during a cycle of the + Implicitly restarted Arnoldi iteration. One possibility is to + increase the size of NCV relative to NEV. See remark 4 + below. + + + + -1: N must be positive. + + + -2: NEV must be positive. + + + -3: NCV-NEV >= 1 and less than or equal to N. + + + + -4: The maximum number of Arnoldi update iteration must be + greater than zero. + + + + + -5: WHICH must be one of 'LM', 'SM', 'LR', 'SR', 'LI', + 'SI'. + + + + -6: BMAT must be one of 'I' or 'G'. + + + -7: Length of private work array is not sufficient. + + + + -8: Error return from LAPACK eigenvalue + calculation. + + + + -9: Starting vector is zero. + + + -10: IPARAM(7) must be 1, 2, 3. + + + -11: IPARAM(7) = 1 and BMAT = 'G' are incompatible. + + + -12: IPARAM(1) must be equal to 0 or 1. + + + + -9999: Could not build an Arnoldi factorization. User + input error highly likely. Please check actual array dimensions + and layout. IPARAM(5) returns the size of the current Arnoldi + factorization. + + + + + + + + + Description + + Reverse communication interface for the Implicitly Restarted Arnoldi + iteration. This is intended to be used to find a few eigenpairs of a + complex linear operator OP with respect to a semi-inner product defined by + a hermitian positive semi-definite real matrix B. B may be the identity + matrix. + + + NOTE: if both OP and B are real, then dsaupd or dnaupd should be + used. + + + The computed approximate eigenvalues are called Ritz values and the + corresponding approximate eigenvectors are called Ritz vectors. znaupd is + usually called iteratively to solve one of the following problems: + + + + Mode 1: A * x = lambda * x. + ===> OP = A and B = I. + + + Mode 2: A * x = lambda * M * x, M hermitian positive definite + ===> OP = inv[M] * A and B = M. + ===> (If M can be factored see remark 3 below) + + + Mode 3: A * x = lambda * M * x, M hermitian semi-definite + ===> OP = inv[A - sigma * M] * M and B = M. + + ===> shift-and-invert mode If OP * x = amu * x, then lambda = + sigma + 1/amu. + + + + + NOTE: The action of w <- inv[A - sigma * M] * v or w <- inv[M] * v + should be accomplished either by a direct method using a sparse matrix + factorization and solving + + [A - sigma * M] * w = v or M * w = v, + + or through an iterative method for solving these systems. If an + iterative method is used, the convergence test must be more stringent than + the accuracy requirements for the eigenvalue approximations. + + + + Remarks + + + + The computed Ritz values are approximate eigenvalues of OP. The + selection of WHICH should be made with this in mind when using Mode = + 3. When operating in Mode = 3 setting WHICH = 'LM' will compute the + NEV eigenvalues of the original problem that are closest to the shift + SIGMA . After convergence, approximate eigenvalues of the original + problem may be obtained with the ARPACK subroutine zneupd. + + + + + If a basis for the invariant subspace corresponding to the + converged Ritz values is needed, the user must call zneupd immediately + following completion of znaupd. This is new starting with release 2 of + ARPACK. + + + + + If M can be factored into a Cholesky factorization M = LL` then + Mode = 2 should not be selected. Instead one should use Mode = 1 with + OP = inv(L) * A * inv(L`). Appropriate triangular linear systems should be + solved with L and L` rather than computing inverses. After + convergence, an approximate eigenvector z of the original problem is + recovered by solving L`z = x where x is a Ritz vector of OP. + + + + + At present there is no a-priori analysis to guide the selection + of NCV relative to NEV. The only formal requirement is that NCV > + NEV + 1. However, it is recommended that NCV .ge. 2 * NEV. If many + problems of the same type are to be solved, one should experiment with + increasing NCV while keeping NEV fixed for a given test problem. This + will usually decrease the required number of OP*x operations but it + also increases the work and storage required to maintain the + orthogonal basis vectors. The optimal "cross-over" with respect to CPU + time is problem dependent and must be determined empirically. See + Chapter 8 of Reference 2 for further information. + + + + + When IPARAM(1) = 0, and IDO = 3, the user needs to provide the + NP = IPARAM(8) complex shifts in locations + + + WORKL(IPNTR(14)), WORKL(IPNTR(14)+1), ... , WORKL(IPNTR(14)+NP). + + + Eigenvalues of the current upper Hessenberg matrix are located + in WORKL(IPNTR(6)) through WORKL(IPNTR(6)+NCV-1). They are ordered + according to the order defined by WHICH. The associated Ritz estimates + are located in + + + WORKL(IPNTR(8)), WORKL(IPNTR(8)+1), ... , + WORKL(IPNTR(8)+NCV-1). + + + + + + Example + + 99) + // Repeatedly call the routine ZNAUPD and take actions indicated by parameter IDO until + // either convergence is indicated or maxitr has been exceeded. + [ido, resid, v, iparam, ipntr, workd, workl, rwork, info_znaupd] = znaupd(ido, bmat, nx, which, nev, tol, resid, ncv, v, iparam, ipntr, workd, workl, rwork, info_znaupd); + if(info_znaupd < 0) + printf('\nError with znaupd, info = %d\n', info_znaupd); + printf('Check the documentation of znaupd\n\n'); + end + if(ido == -1 | ido == 1) + // Perform matrix vector multiplication + workd(ipntr(2):ipntr(2) + nx - 1) = A * workd(ipntr(1):ipntr(1) + nx - 1); + end +end +// Post-Process using ZNEUPD. +rvec = 1; +howmany = 'A'; +info_zneupd = 0; +[d, z, resid, iparam, ipntr, workd, workl, rwork, info_zneupd] = zneupd(rvec, howmany, _select, d, z, sigma, workev, bmat, nx, which, nev, tol, resid, ncv, v, ... + iparam, ipntr, workd, workl, rwork, info_zneupd); +if(info_zneupd < 0) + printf('\nError with zneupd, info = %d\n', info_zneupd); + printf('Check the documentation of zneupd.\n\n'); +end +// Done with program znsimp. +printf('\nZNSIMP\n'); +printf('======\n'); +printf('\n'); +printf('Size of the matrix is %d\n', nx); +printf('The number of Ritz values requested is %d\n', nev); +printf('The number of Arnoldi vectors generated (NCV) is %d\n', ncv); +printf('What portion of the spectrum: %s\n', which); +printf('The number of Implicit Arnoldi update iterations taken is %d\n', iparam(3)); +printf('The number of OP*x is %d\n', iparam(9)); +printf('The convergence criterion is %d\n', tol); +]]> + + + + See Also + + + dnaupd + + + dneupd + + + zneupd + + + + + Bibliography + + 1. D.C. Sorensen, "Implicit Application of Polynomial Filters in a + k-Step Arnoldi Method", SIAM J. Matr. Anal. Apps., 13 (1992), pp + 357-385. + + + 2. R.B. Lehoucq, "Analysis and Implementation of an Implicitly + Restarted Arnoldi Iteration", Rice University Technical Report TR95-13, + Department of Computational and Applied Mathematics. + + + 3. B.N. Parlett and Y. Saad, "Complex Shift and Invert Strategies + for Real Matrices", Linear Algebra and its Applications, vol 88/89, pp + 575-595, (1987). + + + + Used Functions + Based on ARPACK routine znaupd + + + 履歴 + + + 5.4.0 + + 関数は廃止され,eigsに代替されました. + + + + + diff --git a/modules/arnoldi/help/ja_JP/zneupd.xml b/modules/arnoldi/help/ja_JP/zneupd.xml new file mode 100755 index 000000000..6b2522440 --- /dev/null +++ b/modules/arnoldi/help/ja_JP/zneupd.xml @@ -0,0 +1,506 @@ + + + + zneupd + + 暗黙のうちに再開されるArnoldi反復へのインターフェイスで, + A * z = lambda * B * z の固有値を収束的近似により計算します. + + この関数は廃止されました. eigsを使用してください + + + + + Calling Sequence + + [D, Z, RESID, IPARAM, IPNTR, WORKD, WORKL, RWORK, INFO] = zneupd(RVEC, HOWMANY, SELECT, D, Z, SIGMA, WORKev, + BMAT, N, WHICH, NEV, TOL, RESID, NCV, V, IPARAM, IPNTR, WORKD, WORKL, RWORK, INFO) + + + + Arguments + + + RVEC + + Integer. (INPUT) + + Specifies whether a basis for the invariant subspace + corresponding to the converged Ritz value approximations for the + eigenproblem A * z = lambda * B * z is computed. + + + + RVEC = 0 Compute Ritz values only. + + + + RVEC = 1 Compute Ritz vectors or Schur vectors. See + Remarks below. + + + + + + + HOWMANY + + Character. (INPUT) + + Specifies the form of the basis for the invariant subspace + corresponding to the converged Ritz values that is to be computed. + + + + 'A': Compute NEV Ritz vectors; + + + 'P': Compute NEV Schur vectors; + + + + 'S': compute some of the Ritz vectors, specified by the + integer array SELECT. + + + + + + + SELECT + + Integer array of dimension NCV. (INPUT) + + If HOWMANY = 'S', SELECT specifies the Ritz vectors to be + computed. To select the Ritz vector corresponding to a Ritz value + D(j), SELECT(j) must be set to 1. + + + If HOWMANY = 'A' or 'P', SELECT need not be initialized but it + is used as internal workspace. + + + + + D + + Complex*16 array of dimension NEV + 1. (OUTPUT) + + On exit, D contains the Ritz approximations to the eigenvalues + lambda for A * z = lambda * B * z. + + + + + Z + + Complex*16 N by NEV array. (OUTPUT) + On exit, + + If RVEC = 1 and HOWMANY = 'A', then the columns of Z + represents approximate eigenvectors (Ritz vectors) corresponding to + the NCONV = IPARAM(5) Ritz values for eigensystem A * z = lambda * B * z. + + + If RVEC = 0 or HOWMANY = 'P', then Z is NOT REFERENCED. + + + NOTE: If if RVEC = 1 and a Schur basis is not required, the + array Z may be set equal to first NEV+1 columns of the Arnoldi basis + array V computed by ZNAUPD. In this case the Arnoldi basis will be + destroyed and overwritten with the eigenvector basis. + + + + + SIGMA + + Complex*16. (INPUT) + If IPARAM(7) = 3 then SIGMA represents the shift. + Not referenced if IPARAM(7) = 1 or 2. + + + + WORKev + + Complex*16 work array of dimension 2 * NCV. (WORKSPACE) + + + + + NOTE: The remaining arguments BMAT, N, WHICH, NEV, TOL, RESID, NCV, + V, IPARAM, IPNTR, WORKD, WORKL, LWORKL, RWORK, INFO must be passed + directly to ZNEUPD following the last call to ZNAUPD. + + + These arguments MUST NOT BE MODIFIED between the last call to + ZNAUPD and the call to ZNEUPD. + + + Three of these parameters (V, WORKL and INFO) are also output + parameters. + + + + V + + Complex*16 N by NCV array. (INPUT/OUTPUT) + + Upon INPUT: the NCV columns of V contain the Arnoldi basis + vectors for OP as constructed by ZNAUPD. + + + Upon OUTPUT: If RVEC = 1 the first NCONV = IPARAM(5) columns + contain approximate Schur vectors that span the desired invariant + subspace. + + + NOTE: If the array Z has been set equal to first NEV+1 columns + of the array V and RVEC = 1 and HOWMANY = 'A', then the Arnoldi basis + held by V has been overwritten by the desired Ritz vectors. If a + separate array Z has been passed then the first NCONV=IPARAM(5) + columns of V will contain approximate Schur vectors that span the + desired invariant subspace. + + + + + WORKL + + + Double precision work array of length LWORKL. + (OUTPUT/WORKSPACE) + + + WORKL(1:ncv * ncv + 2 * ncv) contains information obtained in + znaupd. They are not changed by zneupd. + + + WORKL(ncv * ncv + 2 * ncv + 1:3 * ncv * ncv + 4 * ncv) holds the untransformed + Ritz values, the untransformed error estimates of the Ritz values, + the upper triangular matrix for H, and the associated matrix + representation of the invariant subspace for H. + + + Note: IPNTR(9:13) contains the pointer into WORKL for + addresses of the above information computed by zneupd. + + + + + IPNTR(9): pointer to the NCV RITZ values of the original + system. + + + + IPNTR(10): Not used + + + + IPNTR(11): pointer to the NCV corresponding error + estimates. + + + + + IPNTR(12): pointer to the NCV by NCV upper triangular + Schur matrix for H. + + + + + IPNTR(13): pointer to the NCV by NCV matrix of + eigenvectors of the upper Hessenberg matrix H. Only referenced + by zneupd if RVEC = 1 See Remark 2 below. + + + + + + + INFO + + Integer. (OUTPUT) + Error flag on output. + + + 0: Normal exit. + + + + 1: The Schur form computed by LAPACK routine csheqr could + not be reordered by LAPACK routine ztrsen. Re-enter subroutine + zneupd with IPARAM(5) = NCV and increase the size of the array D + to have dimension at least dimension NCV and allocate at least + NCV columns for Z. + + + NOTE: Not necessary if Z and V share the same space. + Please notify the authors if this error occurs. + + + + -1: N must be positive. + + + -2: NEV must be positive. + + + -3: NCV-NEV >= 1 and less than or equal to N. + + + + -5: WHICH must be one of 'LM', 'SM', 'LR', 'SR', 'LI', + 'SI'. + + + + -6: BMAT must be one of 'I' or 'G'. + + + + -7: Length of private work WORKL array is not + sufficient. + + + + + -8: Error return from LAPACK eigenvalue calculation. This + should never happened. + + + + + -9: Error return from calculation of eigenvectors. + Informational error from LAPACK routine ztrevc. + + + + -10: IPARAM(7) must be 1, 2, 3. + + + -11: IPARAM(7) = 1 and BMAT = 'G' are incompatible. + + + -12: HOWMANY = 'S' not yet implemented. + + + + -13: HOWMANY must be one of 'A' or 'P' if RVEC = .true. + + + + + -14: ZNAUPD did not find any eigenvalues to sufficient + accuracy. + + + + + -15: ZNEUPD got a different count of the number of + converged Ritz values than ZNAUPD got. This indicates the user + probably made an error in passing data from ZNAUPD to ZNEUPD or + that the data was modified before entering ZNEUPD. + + + + + + + + + Description + + This subroutine returns the converged approximations to eigenvalues + of A * z = lambda * B * z and (optionally): + + + + The corresponding approximate eigenvectors; + + + + An orthonormal basis for the associated approximate invariant + subspace; + + + + Both. + + + + There is negligible additional cost to obtain eigenvectors. An + orthonormal basis is always computed. + + + There is an additional storage cost of n*nev if both are requested + (in this case a separate array Z must be supplied). + + + The approximate eigenvalues and eigenvectors of A * z = lambda * B * z are + derived from approximate eigenvalues and eigenvectors of of the linear + operator OP prescribed by the MODE selection in the call to ZNAUPD. + + ZNAUPD must be called before this routine is called. + + These approximate eigenvalues and vectors are commonly called Ritz + values and Ritz vectors respectively. They are referred to as such in the + comments that follow. + + + The computed orthonormal basis for the invariant subspace + corresponding to these Ritz values is referred to as a Schur basis. + + + The definition of OP as well as other terms and the relation of + computed Ritz values and vectors of OP with respect to the given problem + A*z = lambda*B*z may be found in the header of ZNAUPD. For a brief + description, see definitions of IPARAM(7), MODE and WHICH in the + documentation of ZNAUPD. + + + + Remarks + + + Currently only HOWMNY = 'A' and 'P' are implemented. + + + + Schur vectors are an orthogonal representation for the basis of + Ritz vectors. Thus, their numerical properties are often superior. + + If RVEC = 1 then the relationship + A * V(:,1:IPARAM(5)) = V(:,1:IPARAM(5)) * T, + and + transpose( V(:,1:IPARAM(5)) ) * V(:,1:IPARAM(5)) = I + + are approximately satisfied. Here T is the leading submatrix of + order IPARAM(5) of the upper triangular matrix stored + workl(ipntr(12)). + + + + + + Example + + 99) + // Repeatedly call the routine ZNAUPD and take actions indicated by parameter IDO until + // either convergence is indicated or maxitr has been exceeded. + [ido, resid, v, iparam, ipntr, workd, workl, rwork, info_znaupd] = znaupd(ido, bmat, nx, which, nev, tol, resid, ncv, v, iparam, ipntr, workd, workl, rwork, info_znaupd); + if(info_znaupd < 0) + printf('\nError with znaupd, info = %d\n', info_znaupd); + printf('Check the documentation of znaupd\n\n'); + end + if(ido == -1 | ido == 1) + // Perform matrix vector multiplication + workd(ipntr(2):ipntr(2) + nx - 1) = A * workd(ipntr(1):ipntr(1) + nx - 1); + end +end +// Post-Process using ZNEUPD. +rvec = 1; +howmany = 'A'; +info_zneupd = 0; +[d, z, resid, iparam, ipntr, workd, workl, rwork, info_zneupd] = zneupd(rvec, howmany, _select, d, z, sigma, workev, bmat, nx, which, nev, tol, resid, ncv, v, ... + iparam, ipntr, workd, workl, rwork, info_zneupd); +if(info_zneupd < 0) + printf('\nError with zneupd, info = %d\n', info_zneupd); + printf('Check the documentation of zneupd.\n\n'); +end +// Done with program znsimp. +printf('\nZNSIMP\n'); +printf('======\n'); +printf('\n'); +printf('Size of the matrix is %d\n', nx); +printf('The number of Ritz values requested is %d\n', nev); +printf('The number of Arnoldi vectors generated (NCV) is %d\n', ncv); +printf('What portion of the spectrum: %s\n', which); +printf('The number of Implicit Arnoldi update iterations taken is %d\n', iparam(3)); +printf('The number of OP*x is %d\n', iparam(9)); +printf('The convergence criterion is %d\n', tol); +]]> + + + + See Also + + + znaupd + + + dnaupd + + + dneupd + + + + + Bibliography + + 1. D.C. Sorensen, "Implicit Application of Polynomial Filters in a + k-Step Arnoldi Method", SIAM J. Matr. Anal. Apps., 13 (1992), pp + 357-385. + + + 2. R.B. Lehoucq, "Analysis and Implementation of an Implicitly + Restarted Arnoldi Iteration", Rice University Technical Report TR95-13, + Department of Computational and Applied Mathematics. + + + 3. B.N. Parlett and Y. Saad, "Complex Shift and Invert Strategies + for Real Matrices", Linear Algebra and its Applications, vol 88/89, pp + 575-595, (1987). + + + + Used Functions + Based on ARPACK routine zneupd + + + 履歴 + + + 5.4.0 + + 関数は廃止され,eigsに代替されました. + + + + + diff --git a/modules/arnoldi/help/pt_BR/addchapter.sce b/modules/arnoldi/help/pt_BR/addchapter.sce new file mode 100755 index 000000000..d3565543c --- /dev/null +++ b/modules/arnoldi/help/pt_BR/addchapter.sce @@ -0,0 +1,11 @@ +// Scilab ( http://www.scilab.org/ ) - This file is part of Scilab +// Copyright (C) 2009 - DIGITEO +// +// This file must be used under the terms of the CeCILL. +// This source file is licensed as described in the file COPYING, which +// you should have received as part of this distribution. The terms +// are also available at +// http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt + +add_help_chapter("ARnoldi PACKage",SCI+"/modules/arnoldi/help/pt_BR",%T); + diff --git a/modules/arnoldi/help/ru_RU/addchapter.sce b/modules/arnoldi/help/ru_RU/addchapter.sce new file mode 100755 index 000000000..10bc12342 --- /dev/null +++ b/modules/arnoldi/help/ru_RU/addchapter.sce @@ -0,0 +1,11 @@ +// Scilab ( http://www.scilab.org/ ) - This file is part of Scilab +// Copyright (C) 2009 - DIGITEO +// +// This file must be used under the terms of the CeCILL. +// This source file is licensed as described in the file COPYING, which +// you should have received as part of this distribution. The terms +// are also available at +// http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt + +add_help_chapter("ARnoldi PACKage",SCI+"/modules/arnoldi/help/ru_RU",%T); + -- cgit