diff options
| author | Shashank | 2017-05-29 12:40:26 +0530 |
|---|---|---|
| committer | Shashank | 2017-05-29 12:40:26 +0530 |
| commit | 0345245e860375a32c9a437c4a9d9cae807134e9 (patch) | |
| tree | ad51ecbfa7bcd3cc5f09834f1bb8c08feaa526a4 /modules/arnoldi/help | |
| download | scilab_for_xcos_on_cloud-0345245e860375a32c9a437c4a9d9cae807134e9.tar.gz scilab_for_xcos_on_cloud-0345245e860375a32c9a437c4a9d9cae807134e9.tar.bz2 scilab_for_xcos_on_cloud-0345245e860375a32c9a437c4a9d9cae807134e9.zip | |
CMSCOPE changed
Diffstat (limited to 'modules/arnoldi/help')
| -rwxr-xr-x | modules/arnoldi/help/en_US/addchapter.sce | 11 | ||||
| -rwxr-xr-x | modules/arnoldi/help/en_US/dnaupd.xml | 882 | ||||
| -rwxr-xr-x | modules/arnoldi/help/en_US/dneupd.xml | 642 | ||||
| -rwxr-xr-x | modules/arnoldi/help/en_US/dsaupd.xml | 788 | ||||
| -rwxr-xr-x | modules/arnoldi/help/en_US/dseupd.xml | 463 | ||||
| -rwxr-xr-x | modules/arnoldi/help/en_US/eigs.xml | 525 | ||||
| -rwxr-xr-x | modules/arnoldi/help/en_US/znaupd.xml | 799 | ||||
| -rwxr-xr-x | modules/arnoldi/help/en_US/zneupd.xml | 525 | ||||
| -rwxr-xr-x | modules/arnoldi/help/fr_FR/addchapter.sce | 11 | ||||
| -rwxr-xr-x | modules/arnoldi/help/ja_JP/addchapter.sce | 11 | ||||
| -rwxr-xr-x | modules/arnoldi/help/ja_JP/dnaupd.xml | 861 | ||||
| -rwxr-xr-x | modules/arnoldi/help/ja_JP/dneupd.xml | 621 | ||||
| -rwxr-xr-x | modules/arnoldi/help/ja_JP/dsaupd.xml | 765 | ||||
| -rwxr-xr-x | modules/arnoldi/help/ja_JP/dseupd.xml | 440 | ||||
| -rwxr-xr-x | modules/arnoldi/help/ja_JP/eigs.xml | 526 | ||||
| -rwxr-xr-x | modules/arnoldi/help/ja_JP/znaupd.xml | 780 | ||||
| -rwxr-xr-x | modules/arnoldi/help/ja_JP/zneupd.xml | 506 | ||||
| -rwxr-xr-x | modules/arnoldi/help/pt_BR/addchapter.sce | 11 | ||||
| -rwxr-xr-x | modules/arnoldi/help/ru_RU/addchapter.sce | 11 |
19 files changed, 9178 insertions, 0 deletions
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 @@ +<?xml version="1.0" encoding="UTF-8"?> +<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="dnaupd" xml:lang="en"> + <refnamediv> + <refname>dnaupd</refname> + <refpurpose> + Interface for the Implicitly Restarted Arnoldi Iteration, to + compute approximations to a few eigenpairs of a real linear + operator + <emphasis role="bold"> + This function is obsolete. Please use <link linkend="eigs">eigs</link> + </emphasis> + </refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>Calling Sequence</title> + <synopsis>[IDO, RESID, V, IPARAM, IPNTR, WORKD, WORKL, INFO] = dnaupd(ID0, BMAT, N, WHICH, NEV, TOL, RESID, NCV, V, IPARAM, IPNTR, WORKD, WORKL, INFO)</synopsis> + </refsynopsisdiv> + <refsection> + <title>Arguments</title> + <variablelist> + <varlistentry> + <term>ID0</term> + <listitem> + <para> + Integer. (INPUT/OUTPUT) + </para> + <para> + 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)). + </para> + <itemizedlist> + <listitem> + <para> + IDO = 0: first call to the reverse communication + interface. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para>IDO = 99: done.</para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>BMAT</term> + <listitem> + <para> + Character. (INPUT) + </para> + <para> + specifies the type of the matrix B that defines the + semi-inner product for the operator OP. + </para> + <itemizedlist> + <listitem> + <para>'I' - standard eigenvalue problem A * x = lambda * x</para> + </listitem> + <listitem> + <para> + 'G' - generalized eigenvalue problem A * x = + lambda * B * x + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>N</term> + <listitem> + <para>Integer. (INPUT)</para> + <para>dimension of the eigenproblem.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>WHICH</term> + <listitem> + <para> + string of length 2. (INPUT) + </para> + <para> + Specifies which of the Ritz values of OP to + compute. + </para> + <itemizedlist> + <listitem> + <para> + 'LM' - want the NEV eigenvalues of largest + magnitude. + </para> + </listitem> + <listitem> + <para> + 'SM' - want the NEV eigenvalues of smallest + magnitude. + </para> + </listitem> + <listitem> + <para> + 'LR' - want the NEV eigenvalues of largest real + part. + </para> + </listitem> + <listitem> + <para> + 'SR' - want the NEV eigenvalues of smallest real + part. + </para> + </listitem> + <listitem> + <para> + 'LI' - want the NEV eigenvalues of largest imaginary + part. + </para> + </listitem> + <listitem> + <para> + 'SI' - want the NEV eigenvalues of smallest imaginary + part. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>NEV</term> + <listitem> + <para> + Integer. (INPUT) + </para> + <para> + number of eigenvalues of OP to be computed. 0 < + NEV < N-1. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>TOL</term> + <listitem> + <para> + scalar. (INPUT) + </para> + <para> + 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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>RESID</term> + <listitem> + <para>array of length N. (INPUT/OUTPUT)</para> + <para> + On INPUT: If INFO = 0, a random initial residual vector is + used, else RESID contains the initial residual vector, possibly from + a previous run. + </para> + <para>On OUTPUT: RESID contains the final residual vector.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>NCV</term> + <listitem> + <para> + Integer. (INPUT) + </para> + <para> + number of columns of the matrix V. NCV must satisfy + the two inequalities 2 <= NCV - NEV and NCV <= N. + </para> + <para> + This will indicate how many Arnoldi vectors are generated at + each iteration. + </para> + <para> + 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. + </para> + <para> + NOTE: 2 <= NCV - NEV in order that complex conjugate pairs of + Ritz values are kept together. (See remark 4 below) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>V</term> + <listitem> + <para> + N by NCV array. (OUTPUT) + </para> + <para> + Contains the final set of Arnoldi basis + vectors. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>IPARAM</term> + <listitem> + <para>array of length 11. (INPUT/OUTPUT)</para> + <itemizedlist> + <listitem> + <para> + 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. + </para> + <itemizedlist> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para>IPARAM(2) = LEVEC. No longer referenced.</para> + </listitem> + <listitem> + <para>IPARAM(3) = MXITER </para> + <para> + On INPUT: maximum number of Arnoldi update iterations + allowed. + </para> + <para> + On OUTPUT: actual number of Arnoldi update iterations + taken. + </para> + </listitem> + <listitem> + <para> + IPARAM(4) = NB: blocksize to be used in the recurrence. + The code currently works only for NB = 1. + </para> + </listitem> + <listitem> + <para> + IPARAM(5) = NCONV: number of "converged" Ritz values. This + represents the number of Ritz values that satisfy the + convergence criterion. + </para> + </listitem> + <listitem> + <para> + IPARAM(6) = IUPD No longer referenced. Implicit restarting + is ALWAYS used. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + <para>0 < NP <= NCV-NEV. See Remark 5 below.</para> + </listitem> + <listitem> + <para>IPARAM(9) = NUMOP, </para> + <para>IPARAM(10) = NUMOPB, </para> + <para>IPARAM(11) = NUMREO, </para> + <para> + 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. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>IPNTR</term> + <listitem> + <para> + array of length 14. (OUTPUT) + </para> + <para> + Pointer to mark the starting locations in + the WORKD and WORKL arrays for matrices/vectors used by the Arnoldi + iteration. + </para> + <itemizedlist> + <listitem> + <para> + IPNTR(1): pointer to the current operand vector X in + WORKD. + </para> + </listitem> + <listitem> + <para> + IPNTR(2): pointer to the current result vector Y in + WORKD. + </para> + </listitem> + <listitem> + <para> + IPNTR(3): pointer to the vector B * X in WORKD when used + in the shift-and-invert mode. + </para> + </listitem> + <listitem> + <para> + IPNTR(4): pointer to the next available location in WORKL + that is untouched by the program. + </para> + </listitem> + <listitem> + <para> + IPNTR(5): pointer to the NCV by NCV upper Hessenberg + matrix H in WORKL. + </para> + </listitem> + <listitem> + <para> + IPNTR(6): pointer to the real part of the ritz value array + RITZR in WORKL. + </para> + </listitem> + <listitem> + <para> + IPNTR(7): pointer to the imaginary part of the ritz value + array RITZI in WORKL. + </para> + </listitem> + <listitem> + <para> + IPNTR(8): pointer to the Ritz estimates in array WORKL + associated with the Ritz values located in RITZR and RITZI in + WORKL. + </para> + </listitem> + <listitem> + <para> + IPNTR(14): pointer to the NP shifts in WORKL. See Remark 5 + below. + </para> + </listitem> + </itemizedlist> + <para> + Note: IPNTR(9:13) is only referenced by dneupd . See Remark + 2. + </para> + <itemizedlist> + <listitem> + <para> + IPNTR(9): pointer to the real part of the NCV RITZ values + of the original system. + </para> + </listitem> + <listitem> + <para> + IPNTR(10): pointer to the imaginary part of the NCV RITZ + values of the original system. + </para> + </listitem> + <listitem> + <para> + IPNTR(11): pointer to the NCV corresponding error + bounds. + </para> + </listitem> + <listitem> + <para> + IPNTR(12):pointer to the NCV by NCV upper quasi-triangular + Schur matrix for H. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>WORKD</term> + <listitem> + <para> + Double precision work array of length 3 * N. (REVERSE + COMMUNICATION) + </para> + <para> + 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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>WORKL</term> + <listitem> + <para> + work array of length at least 3 * NCV ** 2 + 6 * NCV. + (OUTPUT/WORKSPACE) + </para> + <para> + Private (replicated) array on each PE or array + allocated on the front end. See Data Distribution Note below. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>INFO</term> + <listitem> + <para>Integer. (INPUT/OUTPUT)</para> + <para> + If INFO == 0, a randomly initial residual vector is used, else + RESID contains the initial residual vector, possibly from a previous + run. + </para> + <para>Error flag on output.</para> + <itemizedlist> + <listitem> + <para>0: Normal exit.</para> + </listitem> + <listitem> + <para> + 1: Maximum number of iterations taken. All possible + eigenvalues of OP has been found. IPARAM(5) returns the number + of wanted converged Ritz values. + </para> + </listitem> + <listitem> + <para> + 2: No longer an informational error. Deprecated starting + with release 2 of ARPACK. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para>-1: N must be positive.</para> + </listitem> + <listitem> + <para>-2: NEV must be positive.</para> + </listitem> + <listitem> + <para>-3: NCV-NEV >= 2 and less than or equal to N.</para> + </listitem> + <listitem> + <para> + -4: The maximum number of Arnoldi update iterations + allowed must be greater than zero. + </para> + </listitem> + <listitem> + <para> + -5: WHICH must be one of 'LM', 'SM', 'LR', 'SR', 'LI', + 'SI'. + </para> + </listitem> + <listitem> + <para>-6: BMAT must be one of 'I' or 'G'.</para> + </listitem> + <listitem> + <para> + -7: Length of private work array WORKL is not + sufficient. + </para> + </listitem> + <listitem> + <para> + -8: Error return from LAPACK eigenvalue + calculation. + </para> + </listitem> + <listitem> + <para>-9: Starting vector is zero.</para> + </listitem> + <listitem> + <para>-10: IPARAM(7) must be 1, 2, 3, 4.</para> + </listitem> + <listitem> + <para>-11: IPARAM(7) = 1 and BMAT = 'G' are incompatable.</para> + </listitem> + <listitem> + <para>-12: IPARAM(1) must be equal to 0 or 1.</para> + </listitem> + <listitem> + <para> + -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. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Description</title> + <para> + 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. + </para> + <para> + The computed approximate eigenvalues are called Ritz values and the + corresponding approximate eigenvectors are called Ritz vectors. + </para> + <para> + dnaupd is usually called iteratively to solve one of the following + problems: + </para> + <itemizedlist> + <listitem> + <para> + Mode 1: A*x = lambda*x. <literal> + OP = A , B = + I + </literal> + . + </para> + </listitem> + <listitem> + <para> + Mode 2: A*x = lambda*M*x, M symmetric positive definite + <literal>OP = inv[M]*A, B = M</literal>. (If M can be factored see + remark 3 below) + </para> + </listitem> + <listitem> + <para> + Mode 3: A*x = lambda*M*x, M symmetric positive semi-definite. + <literal>OP = Real_Part{ inv[A - sigma*M]*M }, B = M</literal>. + shift-and-invert mode (in real arithmetic) + </para> + <para> + If <literal>OP*x = amu*x</literal>, then + </para> + <para> + <literal> + amu = 1/2 * [ 1/(lambda-sigma) + + 1/(lambda-conjg(sigma))] + </literal> + . + </para> + <para> + Note: If sigma is real, i.e. imaginary part of sigma is zero; + <literal> + Real_Part{ inv[A - sigma*M]*M } == inv[A - + sigma*M]*M + </literal> + <literal> + amu == + 1/(lambda-sigma) + </literal> + . + </para> + </listitem> + <listitem> + <para> + Mode 4: A*x = lambda*M*x, M symmetric semi-definite <literal> + OP + = Imaginary_Part{ inv[A - sigma*M]*M } , B = M + </literal> + . + shift-and-invert mode (in real arithmetic) + </para> + <para> + If <literal>OP*x = amu*x</literal>, then <literal> + amu = 1/2i * [ + 1/(lambda-sigma) - 1/(lambda-conjg(sigma)) ] + </literal> + . + </para> + </listitem> + </itemizedlist> + <para> + 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. + </para> + <para> + 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 <literal>[A - sigma * M] * w = v</literal> or + <literal>M * w = v</literal>, 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. + </para> + </refsection> + <refsection> + <title>Example</title> + <programlisting role="example"> + <![CDATA[ +// The following sets dimensions for this problem. + +nx = 10; + +nev = 3; +ncv = 6; +bmat = 'I'; +which = 'LM'; + +// Local Arrays + +iparam = zeros(11, 1); +ipntr = zeros(14, 1); +_select = zeros(ncv, 1); +dr = zeros(nev + 1, 1); +di = zeros(nev + 1, 1); +z = zeros(nx, nev + 1); +resid = zeros(nx, 1); +v = zeros(nx, ncv); +workd = zeros(3 * nx, 1); +workev = zeros(3 * ncv, 1); +workl = zeros(3 * ncv * ncv + 6 * ncv, 1); + +// Build the test matrix + +A = diag(10 * ones(nx, 1)); +A(1:$-1,2:$) = A(1:$-1,2:$) + diag(6 * ones(nx-1,1)); +A(2:$,1:$-1) = A(2:$,1:$-1) + diag(-6 * ones(nx-1,1)); + +tol = 0; +ido = 0; + +ishfts = 1; +maxitr = 300; +mode1 = 1; + +iparam(1) = ishfts; +iparam(3) = maxitr; +iparam(7) = mode1; + +sigmar = 0; // the real part of the shift +sigmai = 0; // the imaginary part of the shift +info_dnaupd = 0; + +// M A I N L O O P (Reverse communication) + +while(ido <> 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); + +]]> + </programlisting> + </refsection> + <refsection> + <title>Remarks</title> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 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 + </para> + <programlisting> + 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). + </programlisting> + <para> + 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). + </para> + </refsection> + <refsection role="see also"> + <title>See Also</title> + <simplelist type="inline"> + <member> + <link linkend="dsaupd">dsaupd</link> + </member> + <member> + <link linkend="dneupd">dneupd</link> + </member> + </simplelist> + </refsection> + <refsection> + <title>Bibliography</title> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 3. B.N. Parlett, "The Symmetric Eigenvalue Problem". Prentice-Hall, + 1980. + </para> + <para> + 4. B.N. Parlett, B. Nour-Omid, "Towards a Black Box Lanczos + Program", Computer Physics Communications, 53 (1989), pp 169-179. + </para> + <para> + 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. + </para> + <para> + 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). + </para> + <para> + 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. + </para> + <para> + 8. R.B. Lehoucq, D.C. Sorensen, "Implementation of Some Spectral + Transformations in a k-Step Arnoldi Method". In Preparation. + </para> + </refsection> + <refsection> + <title>Used Functions</title> + <para>Based on ARPACK routine dnaupd</para> + </refsection> + <refsection> + <title>History</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revremark> + Function obsolete for <link linkend="eigs">eigs</link>. + </revremark> + </revision> + </revhistory> + </refsection> +</refentry> 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 @@ +<?xml version="1.0" encoding="UTF-8"?> +<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="dneupd" xml:lang="en"> + <refnamediv> + <refname>dneupd</refname> + <refpurpose> + 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 + <emphasis role="bold"> + This function is obsolete. Please use <link linkend="eigs">eigs</link> + </emphasis> + </refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>Calling Sequence</title> + <synopsis> + [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) + </synopsis> + </refsynopsisdiv> + <refsection> + <title>Arguments</title> + <variablelist> + <varlistentry> + <term>RVEC</term> + <listitem> + <para>Integer. (INPUT)</para> + <para> + 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. + </para> + <itemizedlist> + <listitem> + <para>RVEC = 0 Compute Ritz values only.</para> + </listitem> + <listitem> + <para>RVEC = 1 Compute the Ritz vectors or Schur vectors.</para> + </listitem> + </itemizedlist> + <para>See Remarks below.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>HOWMANY</term> + <listitem> + <para>Character. (INPUT) </para> + <para> + Specifies the form of the basis for the invariant subspace + corresponding to the converged Ritz values that is to be + computed. + </para> + <itemizedlist> + <listitem> + <para>'A': Compute NEV Ritz vectors;</para> + </listitem> + <listitem> + <para>'P': Compute NEV Schur vectors;</para> + </listitem> + <listitem> + <para> + 'S': compute some of the Ritz vectors, specified by the + integer array SELECT. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>SELECT</term> + <listitem> + <para>Integer array of dimension NCV. (INPUT) </para> + <para> + 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. + </para> + <para> + If HOWMANY = 'A' or 'P', SELECT is used as internal + workspace. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>DR</term> + <listitem> + <para>Double precision array of dimension NEV + 1. (OUTPUT)</para> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>DI</term> + <listitem> + <para>Double precision array of dimension NEV + 1. (OUTPUT) </para> + <para> + On exit, DI contains the imaginary part of the Ritz value + approximations to the eigenvalues of A * z = lambda * B * z associated + with DR. + </para> + <para> + 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). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Z</term> + <listitem> + <para>Double precision N by NEV + 1 array </para> + <para>if RVEC = 1 and HOWMANY = 'A'. (OUTPUT) </para> + <para> + 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. + </para> + <para> + If RVEC = 0 or HOWMANY = 'P', then Z is not referenced. + </para> + <para> + 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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>SIGMAR</term> + <listitem> + <para>Double precision (INPUT) </para> + <para> + If IPARAM(7) = 3 or 4, represents the real part of the + shift. + </para> + <para>Not referenced if IPARAM(7) = 1 or 2.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>SIGMAI</term> + <listitem> + <para>Double precision (INPUT) </para> + <para> + If IPARAM(7) = 3 or 4, represents the imaginary part of the + shift. + </para> + <para> + Not referenced if IPARAM(7) = 1 or 2. See remark 3 + below. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>WORKEV</term> + <listitem> + <para> + Double precision work array of dimension 3 * NCV. + (WORKSPACE) + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + 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 . + </para> + <para> + These arguments MUST NOT BE MODIFIED between the last call to + DNAUPD and the call to DNEUPD . + </para> + <para> + Three of these parameters (V, WORKL, INFO) are also output + parameters. + </para> + <variablelist> + <varlistentry> + <term>V</term> + <listitem> + <para>Double precision N by NCV array. (INPUT/OUTPUT) </para> + <para> + Upon INPUT: the NCV columns of V contain the Arnoldi basis + vectors for OP as constructed by DNAUPD. + </para> + <para> + 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. + </para> + <para> + 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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>WORKL</term> + <listitem> + <para> + Double precision work array of length LWORKL. + (OUTPUT/WORKSPACE) + </para> + <para> + WORKL(1:ncv*ncv+3*ncv) contains information obtained in dnaupd + . They are not changed by dneupd . + </para> + <para> + 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. + </para> + <para> + Note: IPNTR(9:13) contains the pointer into WORKL for + addresses of the above information computed by dneupd . + </para> + <itemizedlist> + <listitem> + <para> + IPNTR(9): pointer to the real part of the NCV RITZ values + of the original system. + </para> + </listitem> + <listitem> + <para> + IPNTR(10): pointer to the imaginary part of the NCV RITZ + values of the original system. + </para> + </listitem> + <listitem> + <para> + IPNTR(11): pointer to the NCV corresponding error + bounds. + </para> + </listitem> + <listitem> + <para> + IPNTR(12): pointer to the NCV by NCV upper + quasi-triangular Schur matrix for H. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>INFO</term> + <listitem> + <para>Integer. (OUTPUT).</para> + <para>Error flag on output.</para> + <itemizedlist> + <listitem> + <para>0: Normal exit.</para> + </listitem> + <listitem> + <para> + 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. + </para> + <para> + NOTE: Not necessary if Z and V share the same space. + Please notify the authors if this error occurs. + </para> + </listitem> + <listitem> + <para>-1: N must be positive.</para> + </listitem> + <listitem> + <para>-2: NEV must be positive.</para> + </listitem> + <listitem> + <para>-3: NCV-NEV >= 2 and less than or equal to N.</para> + </listitem> + <listitem> + <para> + -5: WHICH must be one of 'LM', 'SM', 'LR', 'SR', 'LI', + 'SI'. + </para> + </listitem> + <listitem> + <para>-6: BMAT must be one of 'I' or 'G'.</para> + </listitem> + <listitem> + <para> + -7: Length of private work WORKL array is not + sufficient. + </para> + </listitem> + <listitem> + <para> + -8: Error return from calculation of a real Schur form. + Informational error from LAPACK routine dlahqr. + </para> + </listitem> + <listitem> + <para> + -9: Error return from calculation of eigenvectors. + Informational error from LAPACK routine dtrevc. + </para> + </listitem> + <listitem> + <para>-10: IPARAM(7) must be 1, 2, 3, 4.</para> + </listitem> + <listitem> + <para>-11: IPARAM(7) = 1 and BMAT = 'G' are incompatible.</para> + </listitem> + <listitem> + <para>-12: HOWMANY = 'S' not yet implemented. </para> + </listitem> + <listitem> + <para>-13: HOWMANY must be one of 'A' or 'P' if RVEC = 1.</para> + </listitem> + <listitem> + <para> + -14: DNAUPD did not find any eigenvalues to sufficient + accuracy. + </para> + </listitem> + <listitem> + <para> + -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. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Description</title> + <para> + This subroutine returns the converged approximations to eigenvalues + of A * z = lambda * B * z and (optionally): + </para> + <orderedlist> + <listitem> + <para>The corresponding approximate eigenvectors;</para> + </listitem> + <listitem> + <para> + An orthonormal basis for the associated approximate invariant + subspace; + </para> + </listitem> + <listitem> + <para>Both.</para> + </listitem> + </orderedlist> + <para> + There is negligible additional cost to obtain eigenvectors. An + orthonormal basis is always computed. + </para> + <para> + There is an additional storage cost of n*nev if both are requested + (in this case a separate array Z must be supplied). + </para> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + The computed orthonormal basis for the invariant subspace + corresponding to these Ritz values is referred to as a Schur basis. + </para> + <para> + 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. + </para> + <para> + For a brief description, see definitions of IPARAM(7), MODE and + WHICH in the documentation of DNAUPD . + </para> + </refsection> + <refsection> + <title>Remarks</title> + <orderedlist> + <listitem> + <para>Currently only HOWMNY = 'A' and 'P' are implemented. </para> + <para>Let trans(X) denote the transpose of X. </para> + </listitem> + <listitem> + <para> + 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 + </para> + <para> + A * V(:,1:IPARAM(5)) = V(:,1:IPARAM(5)) * T, and + trans(V(:,1:IPARAM(5))) * V(:,1:IPARAM(5)) = I + </para> + <para>are approximately satisfied. </para> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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 + </para> + <para>trans(Z(:,I)) * A * Z(:,I) if DI(I) = 0. </para> + <para> + 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 + </para> + <para> + trans(Z(:,I)) * A * Z(:,I) + trans(Z(:,I+1)) * A * Z(:,I+1), + </para> + <para> + trans(Z(:,I)) * A * Z(:,I+1) - trans(Z(:,I+1)) * A * Z(:,I), + </para> + <para>respectively. </para> + <para> + Another possibility is to set RVEC = 1 and HOWMANY = 'P' and + compute + </para> + <para>trans(V(:,1:IPARAM(5))) * A * V(:,1:IPARAM(5)) </para> + <para> + and then an upper quasi-triangular matrix of order IPARAM(5) is + computed. See remark 2 above. + </para> + </listitem> + </orderedlist> + </refsection> + <refsection> + <title>Example</title> + <programlisting role="example"> + <![CDATA[ + +// The following sets dimensions for this problem. + +nx = 10; + +nev = 3; +ncv = 6; +bmat = 'I'; +which = 'LM'; + +// Local Arrays + +iparam = zeros(11, 1); +ipntr = zeros(14, 1); +_select = zeros(ncv, 1); +dr = zeros(nev + 1, 1); +di = zeros(nev + 1, 1); +z = zeros(nx, nev + 1); +resid = zeros(nx, 1); +v = zeros(nx, ncv); +workd = zeros(3 * nx, 1); +workev = zeros(3 * ncv, 1); +workl = zeros(3 * ncv * ncv + 6 * ncv, 1); + +// Build the test matrix + +A = diag(10 * ones(nx, 1)); +A(1:$-1,2:$) = A(1:$-1,2:$) + diag(6 * ones(nx-1,1)); +A(2:$,1:$-1) = A(2:$,1:$-1) + diag(-6 * ones(nx-1,1)); + +tol = 0; +ido = 0; + +ishfts = 1; +maxitr = 300; +mode1 = 1; + +iparam(1) = ishfts; +iparam(3) = maxitr; +iparam(7) = mode1; + +sigmar = 0; // the real part of the shift +sigmai = 0; // the imaginary part of the shift +info_dnaupd = 0; + +// M A I N L O O P (Reverse communication) + +while(ido <> 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); + +]]> + </programlisting> + </refsection> + <refsection role="see also"> + <title>See Also</title> + <simplelist type="inline"> + <member> + <link linkend="dsaupd">dsaupd</link> + </member> + <member> + <link linkend="dnaupd">dnaupd</link> + </member> + </simplelist> + </refsection> + <refsection> + <title>Bibliography</title> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 3. B.N. Parlett, "The Symmetric Eigenvalue Problem". Prentice-Hall, + 1980. + </para> + <para> + 4. B.N. Parlett, B. Nour-Omid, "Towards a Black Box Lanczos + Program", Computer Physics Communications, 53 (1989), pp 169-179. + </para> + <para> + 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. + </para> + <para> + 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). + </para> + <para> + 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. + </para> + <para> + 8. R.B. Lehoucq, D.C. Sorensen, "Implementation of Some Spectral + Transformations in a k-Step Arnoldi Method". In Preparation. + </para> + </refsection> + <refsection> + <title>Used Functions</title> + <para>Based on ARPACK routine dneupd</para> + </refsection> + <refsection> + <title>History</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revremark> + Function obsolete for <link linkend="eigs">eigs</link>. + </revremark> + </revision> + </revhistory> + </refsection> +</refentry> 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 @@ +<?xml version="1.0" encoding="UTF-8"?> +<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="dsaupd" xml:lang="en"> + <refnamediv> + <refname>dsaupd</refname> + <refpurpose> + Interface for the Implicitly Restarted Arnoldi Iteration, to + compute approximations to a few eigenpairs of a real and symmetric linear + operator + <emphasis role="bold"> + This function is obsolete. Please use <link linkend="eigs">eigs</link> + </emphasis> + </refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>Calling Sequence</title> + <synopsis>[IDO, RESID, V, IPARAM, IPNTR, WORKD, WORKL, INFO] = dsaupd(ID0, BMAT, N, WHICH, NEV, TOL, RESID, NCV, V, IPARAM, IPNTR, WORKD, WORKL, INFO)</synopsis> + </refsynopsisdiv> + <refsection> + <title>Arguments</title> + <variablelist> + <varlistentry> + <term>ID0</term> + <listitem> + <para>Integer. (INPUT/OUTPUT) </para> + <para> + 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. + </para> + <para> + The operand is given in WORKD(IPNTR(1)), the result must be put + in WORKD(IPNTR(2)). (If Mode = 2 see remark 5 below) + </para> + <itemizedlist> + <listitem> + <para> + IDO = 0: first call to the reverse communication + interface. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + IDO = 3: compute the IPARAM(8) shifts where IPNTR(11) is + the pointer into WORKL for placing the shifts. See remark 6 + below. + </para> + </listitem> + <listitem> + <para>IDO = 99: done</para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>BMAT</term> + <listitem> + <para>Character. (INPUT)</para> + <para> + Specifies the type of the matrix B that defines the semi-inner + product for the operator OP. + </para> + <itemizedlist> + <listitem> + <para>'I': standard eigenvalue problem A * x = lambda * x</para> + </listitem> + <listitem> + <para> + 'G': generalized eigenvalue problem A * x = + lambda * B * x + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>N</term> + <listitem> + <para>Integer. (INPUT)</para> + <para>Dimension of the eigenproblem.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>WHICH</term> + <listitem> + <para>String of length 2. (INPUT)</para> + <para>Specifies which of the Ritz values of OP to compute.</para> + <itemizedlist> + <listitem> + <para> + 'LA' - compute the NEV largest (algebraic) + eigenvalues. + </para> + </listitem> + <listitem> + <para> + 'SA' - compute the NEV smallest (algebraic) + eigenvalues. + </para> + </listitem> + <listitem> + <para> + 'LM' - compute the NEV largest (in magnitude) + eigenvalues. + </para> + </listitem> + <listitem> + <para> + 'SM' - compute the NEV smallest (in magnitude) + eigenvalues. + </para> + </listitem> + <listitem> + <para> + '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) + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>NEV</term> + <listitem> + <para>Integer. (INPUT)</para> + <para> + Number of eigenvalues of OP to be computed. 0 < NEV < + N. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>TOL</term> + <listitem> + <para>scalar. (INPUT)</para> + <para> + 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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>RESID</term> + <listitem> + <para>Array of length N. (INPUT/OUTPUT)</para> + <para> + On INPUT: If INFO = 0, a random initial residual vector is + used, else RESID contains the initial residual vector, possibly from + a previous run. + </para> + <para>On OUTPUT: RESID contains the final residual vector.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>NCV</term> + <listitem> + <para>Integer. (INPUT)</para> + <para> + Number of columns of the matrix V (less than or equal to N). + </para> + <para> + 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). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>V</term> + <listitem> + <para>N by NCV array. (OUTPUT) </para> + <para>The NCV columns of V contain the Lanczos basis vectors.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>IPARAM</term> + <listitem> + <para>array of length 11. (INPUT/OUTPUT)</para> + <itemizedlist> + <listitem> + <para> + 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. + </para> + <itemizedlist> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para> + IPARAM(2) = LEVEC. No longer referenced. See remark 2 + below. + </para> + </listitem> + <listitem> + <para>IPARAM(3) = MXITER </para> + <para> + On INPUT: maximum number of Arnoldi update iterations + allowed. + </para> + <para> + On OUTPUT: actual number of Arnoldi update iterations + taken. + </para> + </listitem> + <listitem> + <para> + IPARAM(4) = NB: blocksize to be used in the recurrence. + The code currently works only for NB = 1. + </para> + </listitem> + <listitem> + <para> + IPARAM(5) = NCONV: number of "converged" Ritz values. This + represents the number of Ritz values that satisfy the + convergence criterion. + </para> + </listitem> + <listitem> + <para> + IPARAM(6) = IUPD No longer referenced. Implicit restarting + is ALWAYS used. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para>IPARAM(9) = NUMOP, </para> + <para>IPARAM(10) = NUMOPB, </para> + <para> + 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. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>IPNTR</term> + <listitem> + <para> + array of length 11. (OUTPUT) + </para> + <para> + Pointer to mark the starting locations in + the WORKD and WORKL arrays for matrices/vectors used by the Lanczos + iteration. + </para> + <itemizedlist> + <listitem> + <para> + IPNTR(1): pointer to the current operand vector X in + WORKD. + </para> + </listitem> + <listitem> + <para> + IPNTR(2): pointer to the current result vector Y in + WORKD. + </para> + </listitem> + <listitem> + <para> + IPNTR(3): pointer to the vector B * X in WORKD when used + in the shift-and-invert mode. + </para> + </listitem> + <listitem> + <para> + IPNTR(4): pointer to the next available location in WORKL + that is untouched by the program. + </para> + </listitem> + <listitem> + <para> + IPNTR(5): pointer to the NCV by 2 tridiagonal matrix T in + WORKL. + </para> + </listitem> + <listitem> + <para> + IPNTR(6): pointer to the NCV RITZ values array in + WORKL. + </para> + </listitem> + <listitem> + <para> + IPNTR(7): pointer to the Ritz estimates in array WORKL + associated with the Ritz values located in RITZ in WORKL. + </para> + </listitem> + <listitem> + <para> + IPNTR(11): pointer to the NP shifts in WORKL. See Remark 6 + below. + </para> + </listitem> + </itemizedlist> + <para> + Note: IPNTR(8:10) is only referenced by dseupd . See Remark + 2. + </para> + <itemizedlist> + <listitem> + <para> + IPNTR(8): pointer to the NCV RITZ values of the original + system. + </para> + </listitem> + <listitem> + <para> + IPNTR(9): pointer to the NCV corresponding error + bounds. + </para> + </listitem> + <listitem> + <para> + 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 + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>WORKD</term> + <listitem> + <para>work array of length 3 * N. (REVERSE COMMUNICATION) </para> + <para> + 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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>WORKL</term> + <listitem> + <para> + work array of length at least NCV ** 2 + 8 * NCV. + (OUTPUT/WORKSPACE) + </para> + <para> + Private (replicated) array on each PE or array allocated on + the front end. See Data Distribution Note below. add here the + parameter description. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>INFO</term> + <listitem> + <para>Integer. (INPUT/OUTPUT)</para> + <para> + If INFO = 0, a randomly initial residual vector is used, else + RESID contains the initial residual vector, possibly from a previous + run. + </para> + <para>Error flag on output.</para> + <itemizedlist> + <listitem> + <para>0: Normal exit.</para> + </listitem> + <listitem> + <para> + 1: Maximum number of iterations taken. All possible + eigenvalues of OP has been found. IPARAM(5) returns the number + of wanted converged Ritz values. + </para> + </listitem> + <listitem> + <para> + 2: No longer an informational error. Deprecated starting + with release 2 of ARPACK. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para>-1: N must be positive.</para> + </listitem> + <listitem> + <para>-2: NEV must be positive.</para> + </listitem> + <listitem> + <para> + -3: NCV must be greater than NEV and less than or equal to + N. + </para> + </listitem> + <listitem> + <para> + -4: The maximum number of Arnoldi update iterations + allowed must be greater than zero. + </para> + </listitem> + <listitem> + <para> + -5: WHICH must be one of 'LM', 'SM', 'LA', 'SA' or + 'BE'. + </para> + </listitem> + <listitem> + <para>-6: BMAT must be one of 'I' or 'G'.</para> + </listitem> + <listitem> + <para> + -7: Length of private work array WORKL is not + sufficient. + </para> + </listitem> + <listitem> + <para> + -8: Error return from trid. eigenvalue calculation; + Informatinal error from LAPACK routine dsteqr. + </para> + </listitem> + <listitem> + <para>-9: Starting vector is zero.</para> + </listitem> + <listitem> + <para>-10: IPARAM(7) must be 1, 2, 3, 4, 5.</para> + </listitem> + <listitem> + <para>-11: IPARAM(7) = 1 and BMAT = 'G' are incompatable.</para> + </listitem> + <listitem> + <para>-12: IPARAM(1) must be equal to 0 or 1.</para> + </listitem> + <listitem> + <para>-13: NEV and WHICH = 'BE' are incompatable.</para> + </listitem> + <listitem> + <para> + -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. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Description</title> + <para> + 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.<literal> + B * OP = + (OP`) * B + </literal> + . + </para> + <para> + Another way to express this condition is <literal> + < x,OPy > = + < OPx,y > where <z,w > = z`Bw + </literal> + . + </para> + <para> + In the standard eigenproblem B is the identity matrix. ( A` denotes + transpose of A) + </para> + <para> + The computed approximate eigenvalues are called Ritz values and the + corresponding approximate eigenvectors are called Ritz vectors. + </para> + <para> + dsaupd is usually called iteratively to solve one of the following + problems: + </para> + <itemizedlist> + <listitem> + <para> + Mode 1: A * x = lambda * x, A symmetric ===> OP = A and B = + I. + </para> + </listitem> + <listitem> + <para> + 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) + </para> + </listitem> + <listitem> + <para> + 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 + </para> + </listitem> + <listitem> + <para> + 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 + </para> + </listitem> + <listitem> + <para> + 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 + </para> + </listitem> + </itemizedlist> + <para> + 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 <literal> + [A - sigma * M] * w = v or M * w = + v + </literal> + , + </para> + <para> + 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. + </para> + </refsection> + <refsection> + <title>Remarks</title> + <para> + 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 . + </para> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 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). + </para> + </refsection> + <refsection> + <title>Example</title> + <programlisting role="example"> + <![CDATA[ + +// The following sets dimensions for this problem. + +nx = 10; + +nev = 3; +ncv = 6; +bmat = 'I'; +which = 'LM'; + +// Local Arrays + +iparam = zeros(11, 1); +ipntr = zeros(14, 1); +_select = zeros(ncv, 1); +d = zeros(nev, 1); +z = zeros(nx, nev); +resid = zeros(nx, 1); +v = zeros(nx, ncv); +workd = zeros(3 * nx, 1); +workl = zeros(ncv * ncv + 8 * ncv, 1); + +// Build the symmetric test matrix + +A = diag(10 * ones(nx,1)); +A(1:$-1,2:$) = A(1:$-1,2:$) + diag(6 * ones(nx-1,1)); +A(2:$,1:$-1) = A(2:$,1:$-1) + diag(6 * ones(nx-1,1)); + +tol = 0; +ido = 0; + +ishfts = 1; +maxitr = 300; +mode1 = 1; + +iparam(1) = ishfts; +iparam(3) = maxitr; +iparam(7) = mode1; + +sigma = 0; // the real part of the shift +info_dsaupd = 0; + +// M A I N L O O P (Reverse communication) + +while(ido <> 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); + +]]> + </programlisting> + </refsection> + <refsection role="see also"> + <title>See Also</title> + <simplelist type="inline"> + <member> + <link linkend="dnaupd">dnaupd</link> + </member> + <member> + <link linkend="dseupd">dseupd</link> + </member> + </simplelist> + </refsection> + <refsection> + <title>Bibliography</title> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 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). + </para> + </refsection> + <refsection> + <title>Used Functions</title> + <para>Based on ARPACK routine dsaupd</para> + </refsection> + <refsection> + <title>History</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revremark> + Function obsolete for <link linkend="eigs">eigs</link>. + </revremark> + </revision> + </revhistory> + </refsection> +</refentry> 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 @@ +<?xml version="1.0" encoding="UTF-8"?> +<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="dseupd" xml:lang="en"> + <refnamediv> + <refname>dseupd</refname> + <refpurpose> + Interface for the Implicitly Restarted Arnoldi Iteration, to + compute approximations to the converged approximations to eigenvalues of + A * z = lambda * B * z + <emphasis role="bold"> + This function is obsolete. Please use <link linkend="eigs">eigs</link> + </emphasis> + </refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>Calling Sequence</title> + <synopsis> + [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) + </synopsis> + </refsynopsisdiv> + <refsection> + <title>Arguments</title> + <variablelist> + <varlistentry> + <term>RVEC</term> + <listitem> + <para>Integer. (INPUT) </para> + <para> + Specifies whether Ritz vectors corresponding to the Ritz value + approximations to the eigenproblem A * z = lambda * B * z are + computed. + </para> + <itemizedlist> + <listitem> + <para>RVEC = 0 Compute Ritz values only.</para> + </listitem> + <listitem> + <para>RVEC = 1 Compute Ritz vectors.</para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>HOWMNY</term> + <listitem> + <para>Character*1. (INPUT) </para> + <para> + Specifies how many Ritz vectors are wanted and the form of Z + the matrix of Ritz vectors. See remark 1 below. + </para> + <itemizedlist> + <listitem> + <para>'A': compute NEV Ritz vectors;</para> + </listitem> + <listitem> + <para> + 'S': compute some of the Ritz vectors, specified by the + integer array SELECT. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>SELECT</term> + <listitem> + <para>Integer array of dimension NCV. (INPUT/WORKSPACE) </para> + <para> + 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. + </para> + <para> + If HOWMANY = 'A' , SELECT is used as a workspace for + reordering the Ritz values. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>D</term> + <listitem> + <para>Double precision array of dimension NEV. (OUTPUT) </para> + <para> + On exit, D contains the Ritz value approximations to the + eigenvalues of A * z = lambda * B * z. The values are returned in + ascending order. + </para> + <para> + 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. + </para> + <para> + If IPARAM(7) = 1, 2 then the Ritz values of OP are the same as + the those of A * z = lambda * B * z. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Z</term> + <listitem> + <para>Double precision N by NEV array.</para> + <para> + 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. + </para> + <para>If RVEC = 0 then Z is not referenced. </para> + <para> + NOTE: The array Z may be set equal to first NEV columns of the + Arnoldi/Lanczos basis array V computed by DSAUPD . + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>SIGMA</term> + <listitem> + <para>Double precision (INPUT) </para> + <para> + If IPARAM(7) = 3, 4, 5 represents the shift. Not referenced if + IPARAM(7) = 1 or 2. + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + 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 . + </para> + <para> + These arguments MUST NOT BE MODIFIED between the last call to + DSAUPD and the call to DSEUPD. + </para> + <para> + Two of these parameters (WORKL, INFO) are also output + parameters. + </para> + <variablelist> + <varlistentry> + <term>WORKL</term> + <listitem> + <para> + Double precision work array of length LWORKL. + (OUTPUT/WORKSPACE) + </para> + <para> + WORKL(1:4*ncv) contains information obtained in dsaupd. They + are not changed by dseupd. + </para> + <para> + WORKL(4*ncv+1:ncv*ncv+8*ncv) holds the untransformed Ritz + values, the computed error estimates, and the associated eigenvector + matrix of H. + </para> + <para> + Note: IPNTR(8:10) contains the pointer into WORKL for + addresses of the above information computed by dseupd . + </para> + <itemizedlist> + <listitem> + <para> + IPNTR(8): pointer to the NCV RITZ values of the original + system. + </para> + </listitem> + <listitem> + <para> + IPNTR(9): pointer to the NCV corresponding error bounds. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>INFO</term> + <listitem> + <para>Integer. (OUTPUT) </para> + <para>Error flag on output.</para> + <itemizedlist> + <listitem> + <para>0: Normal exit.</para> + </listitem> + <listitem> + <para>-1: N must be positive.</para> + </listitem> + <listitem> + <para>-2: NEV must be positive.</para> + </listitem> + <listitem> + <para> + -3: NCV must be greater than NEV and less than or equal to + N. + </para> + </listitem> + <listitem> + <para> + -5: WHICH must be one of 'LM', 'SM', 'LA', 'SA' or + 'BE'. + </para> + </listitem> + <listitem> + <para>-6: BMAT must be one of 'I' or 'G'.</para> + </listitem> + <listitem> + <para> + -7: Length of private work WORKL array is not + sufficient. + </para> + </listitem> + <listitem> + <para> + -8: Error return from trid. eigenvalue calculation; + Information error from LAPACK routine dsteqr. + </para> + </listitem> + <listitem> + <para>-9: Starting vector is zero.</para> + </listitem> + <listitem> + <para>-10: IPARAM(7) must be 1, 2, 3, 4, 5.</para> + </listitem> + <listitem> + <para>-11: IPARAM(7) = 1 and BMAT = 'G' are incompatible.</para> + </listitem> + <listitem> + <para>-12: NEV and WHICH = 'BE' are incompatible.</para> + </listitem> + <listitem> + <para> + -14: DSAUPD did not find any eigenvalues to sufficient + accuracy. + </para> + </listitem> + <listitem> + <para>-15: HOWMNY must be one of 'A' or 'S' if RVEC = 1.</para> + </listitem> + <listitem> + <para>-16: HOWMNY = 'S' not yet implemented.</para> + </listitem> + <listitem> + <para> + -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. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Description</title> + <para> + This subroutine returns the converged approximations to eigenvalues + of A * z = lambda * B * z and (optionally): + </para> + <orderedlist> + <listitem> + <para>the corresponding approximate eigenvectors,</para> + </listitem> + <listitem> + <para> + an orthonormal (Lanczos) basis for the associated approximate + invariant subspace, + </para> + </listitem> + <listitem> + <para>Both. </para> + </listitem> + </orderedlist> + <para> + 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). + </para> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + The computed orthonormal basis for the invariant subspace + corresponding to these Ritz values is referred to as a Lanczos basis. + </para> + <para> + 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. + </para> + <para> + The approximate eigenvalues of the original problem are returned in + ascending algebraic order. + </para> + <para> + 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. + </para> + </refsection> + <refsection> + <title>Remarks</title> + <para> + 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. + </para> + </refsection> + <refsection> + <title>Example</title> + <programlisting role="example"> + <![CDATA[ + +// The following sets dimensions for this problem. + +nx = 10; + +nev = 3; +ncv = 6; +bmat = 'I'; +which = 'LM'; + +// Local Arrays + +iparam = zeros(11, 1); +ipntr = zeros(14, 1); +_select = zeros(ncv, 1); +d = zeros(nev, 1); +z = zeros(nx, nev); +resid = zeros(nx, 1); +v = zeros(nx, ncv); +workd = zeros(3 * nx, 1); +workl = zeros(ncv * ncv + 8 * ncv, 1); + +// Build the symmetric test matrix + +A = diag(10 * ones(nx,1)); +A(1:$-1,2:$) = A(1:$-1,2:$) + diag(6 * ones(nx-1,1)); +A(2:$,1:$-1) = A(2:$,1:$-1) + diag(6 * ones(nx-1,1)); + +tol = 0; +ido = 0; + +ishfts = 1; +maxitr = 300; +mode1 = 1; + +iparam(1) = ishfts; +iparam(3) = maxitr; +iparam(7) = mode1; + +sigma = 0; // the real part of the shift +info_dsaupd = 0; + +// M A I N L O O P (Reverse communication) + +while(ido <> 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); + +]]> + </programlisting> + </refsection> + <refsection role="see also"> + <title>See Also</title> + <simplelist type="inline"> + <member> + <link linkend="dsaupd">dsaupd</link> + </member> + <member> + <link linkend="dneupd">dneupd</link> + </member> + </simplelist> + </refsection> + <refsection> + <title>Bibliography</title> + <para> + 1. D.C. Sorensen, "Implicit Application of Polynomial Filters in + k-Step Arnoldi Method", SIAM J. Matr. Anal. Apps., 13 (1992), pp + 357-385. + </para> + <para> + 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. + </para> + <para> + 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). + </para> + </refsection> + <refsection> + <title>Used Functions</title> + <para>Based on ARPACK routine dseupd</para> + </refsection> + <refsection> + <title>History</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revremark> + Function obsolete for <link linkend="eigs">eigs</link>. + </revremark> + </revision> + </revhistory> + </refsection> +</refentry> 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 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab + * Copyright (C) 2012 - Scilab Enterprises - Adeline CARNIS + * + * 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 + * + --> +<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="eigs" xml:lang="en"> + <refnamediv> + <refname>eigs</refname> + <refpurpose>calculates largest eigenvalues and eigenvectors of matrices</refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>Calling Sequence</title> + <synopsis> + 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]]]]) + </synopsis> + </refsynopsisdiv> + <refsection> + <title>Arguments</title> + <variablelist> + <varlistentry> + <term>A </term> + <listitem> + <para>a full or sparse, real or complex, symmetric or non-symmetric square matrix</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Af </term> + <listitem> + <para>a function</para> + </listitem> + </varlistentry> + <varlistentry> + <term>n </term> + <listitem> + <para> + a scalar, defined only if <literal>A</literal> is a function + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>B</term> + <listitem> + <para> + a sparse, real or complex, square matrix with same dimensions as + <literal> A</literal> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>k</term> + <listitem> + <para>an integer, number of eigenvalues to be computed</para> + </listitem> + </varlistentry> + <varlistentry> + <term>sigma</term> + <listitem> + <para>a real scalar or a string of length 2</para> + </listitem> + </varlistentry> + <varlistentry> + <term>opts</term> + <listitem> + <para>a structure</para> + </listitem> + </varlistentry> + <varlistentry> + <term>d</term> + <listitem> + <para>a real or complex eigenvalues vector or diagonal matrix (eigenvalues along the diagonal)</para> + </listitem> + </varlistentry> + <varlistentry> + <term>v</term> + <listitem> + <para> + real or complex eigenvector matrix + </para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Description</title> + <para> + The purpose of the eigs function is to compute the largest eigenvalues of sparse, large matrices. + </para> + <variablelist> + <varlistentry> + <term>d = eigs(A) or d = eigs(Af, n)</term> + <listitem> + <para> + solves the eigenvalue problem <literal>A * v = lambda * v</literal>. This calling returns a vector <literal>d</literal> containing the six largest magnitude eigenvalues. + <literal>A</literal> is either a square matrix, which can be symmetric or non-symmetric, real or complex, full or sparse. + </para> + <para> + <literal>A</literal> should be represented by a function <literal>Af</literal>. In this instance, a scalar <literal>n</literal> designating + the length of the vector argument, must be defined. It must have the following header : + </para> + <programlisting role="no-scilab-exec"> + <![CDATA[ +function y = A ( x ) + ]]> + </programlisting> + <para> + This function <literal>Af</literal> must return one of the four following expressions : + <itemizedlist> + <listitem> + <term>A * x</term> + <para> if sigma is not given or is a string other than 'SM'.</para> + </listitem> + <listitem> + <term>A \ x</term> + <para> if sigma is 0 or 'SM'.</para> + </listitem> + <listitem> + <term>(A - sigma * I) \ x</term> + <para>for the standard eigenvalue problem, where I is the identity matrix.</para> + </listitem> + <listitem> + <term>(A - sigma * B) \ x</term> + <para> for the generalized eigenvalue problem.</para> + </listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>[d, v] = eigs(A) or [d, v] = eigs(Af, n)</term> + <listitem> + <para> + returns a diagonal matrix <literal>d</literal> containing the six largest magnitude eigenvalues on the diagonal. + <literal>v</literal> is a n by six matrix whose columns are the six eigenvectors corresponding to the returned eigenvalues. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>d = eigs(A, B)</term> + <listitem> + <para> + solves the generalized eigenvalue problem <literal>A * v = lambda * B * v </literal> with positive, definite matrix <literal>B</literal>. + </para> + <itemizedlist> + <listitem> + <para> + if <literal>B</literal> is not specified, <literal>B = []</literal> is used. + </para> + </listitem> + <listitem> + <para> + if <literal>B</literal> is specified, <literal>B</literal> must be the same size as A. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>d = eigs(A, B, k)</term> + <listitem> + <para> + returns in vector <literal>d</literal> the <literal>k</literal> eigenvalues. + If <literal>k</literal> is not specified, <literal>k = min(n, 6)</literal>, where n is the row number of A. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>d = eigs(A, B, k, sigma)</term> + <listitem> + <para> + returns in vector <literal>d</literal> the <literal>k</literal> eigenvalues determined by <literal>sigma</literal>. + <literal>sigma</literal> 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 : + </para> + <itemizedlist> + <listitem> + <para> + <literal>'LM'</literal> compute the <varname>k</varname> largest in magnitude eigenvalues (by default). + </para> + </listitem> + <listitem> + <para> + <literal>'SM'</literal> compute the <varname>k</varname> smallest in magnitude eigenvalues (same as sigma = 0). + </para> + </listitem> + <listitem> + <para> + <literal>'LA'</literal> compute the <varname>k</varname> Largest Algebraic eigenvalues, only for real symmetric problems. + </para> + </listitem> + <listitem> + <para> + <literal>'SA'</literal> compute the <varname>k</varname> Smallest Algebraic eigenvalues, only for real symmetric problems. + </para> + </listitem> + <listitem> + <para> + <literal>'BE'</literal> compute <varname>k</varname> eigenvalues, half from each end of the spectrum, only for real + symmetric problems. + </para> + </listitem> + <listitem> + <para> + <literal>'LR'</literal> compute the <varname>k</varname> eigenvalues of Largest Real part, only for real non-symmetric or + complex problems. + </para> + </listitem> + <listitem> + <para> + <literal>'SR'</literal> compute the <varname>k</varname> eigenvalues of Smallest Real part, only for real non-symmetric or + complex problems. + </para> + </listitem> + <listitem> + <para> + <literal>'LI'</literal> compute the <varname>k</varname> eigenvalues of Largest Imaginary part, only for real non-symmetric + or complex problems. + </para> + </listitem> + <listitem> + <para> + <literal>'SI'</literal> compute the <varname>k</varname> eigenvalues of Smallest Imaginary part, only for real non-symmetric + or complex problems. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>d = eigs(A, B, k, sigma, opts)</term> + <listitem> + <para> + If the <literal> opts </literal> structure is specified, different options can be used to compute the <literal>k</literal> eigenvalues : + </para> + <itemizedlist> + <listitem> + <para> + <term>tol</term> + <para> + required convergence tolerance. By default, <literal>tol = %eps</literal>. + </para> + </para> + </listitem> + <listitem> + <para> + <term>maxiter</term> + <para> + maximum number of iterations. By default, <literal>maxiter = 300</literal>. + </para> + </para> + </listitem> + <listitem> + <para> + <term>ncv</term> + <para> + number of Lanzcos basis vectors to use. For real non-symmetric problems, the <literal>ncv</literal> value must be greater or equal than <literal>2 * k + 1 </literal> and, by default, <literal>ncv = min(max(2 * k + 1, 20), nA) </literal>. For real symmetric or complex problems, <literal>ncv</literal> must be greater or equal <literal>2 * k </literal> and, by default, <literal> ncv = min(max(2 * k, 20), nA) </literal> with <literal> nA = size(A, 2) </literal>. + </para> + </para> + </listitem> + <listitem> + <para> + <term>resid</term> + <para> + starting vector whose contains the initial residual vector, possibly from a previous run. By default, + <literal>resid</literal> is a random initial vector. + </para> + </para> + </listitem> + <listitem> + <para> + <term>cholB</term> + <para> + if <literal>chol(B)</literal> is passed rather than <literal>B</literal>. By default, <literal>cholB</literal> is %f. + </para> + </para> + </listitem> + <listitem> + <para> + <term>isreal</term> + <para> + if <literal>Af</literal> is given, <literal>isreal</literal> can be defined. By default, <literal>isreal</literal> is %t. + This argument must not be indicated if <literal>A</literal> is a matrix. + </para> + </para> + </listitem> + <listitem> + <para> + <term>issym</term> + <para> + if <literal>Af</literal> is given, <literal>issym</literal> can be defined. By default, <literal>issym</literal> is %f. + This argument must not be indicated if <literal>A</literal> is a matrix. + </para> + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>References</title> + <para> + This function is based on the ARPACK package written by R. Lehoucq, K. Maschhoff, D. Sorensen, and C. Yang. + </para> + <itemizedlist> + <listitem> + <para>DSAUPD and DSEUPD routines for real symmetric problems,</para> + </listitem> + <listitem> + <para>DNAUPD and DNEUPD routines for real non-symmetric problems.</para> + </listitem> + <listitem> + <para>ZNAUPD and ZNEUPD routines for complex problems.</para> + </listitem> + </itemizedlist> + </refsection> + <refsection> + <title>Example for real symmetric problems</title> + <programlisting role="example"> + <![CDATA[ +clear opts +A = diag(10*ones(10,1)); +A(1:$-1,2:$) = A(1:$-1,2:$) + diag(6*ones(9,1)); +A(2:$,1:$-1) = A(2:$,1:$-1) + diag(6*ones(9,1)); + +B = eye(10,10); +k = 8; +sigma = 'SM'; +opts.cholB = %t; + +d = eigs(A) +[d, v] = eigs(A) + +d = eigs(A, B, k, sigma) +[d, v] = eigs(A, B, k, sigma) + +d = eigs(A, B, k, sigma, opts) +[d, v] = eigs(A, B, k, sigma, opts) + +// With sparses +AS = sparse(A); +BS = sparse(B); + +d = eigs(AS) +[d, v] = eigs(AS) + +d = eigs(AS, BS, k, sigma) +[d, v] = eigs(AS, BS, k, sigma) + +d = eigs(AS, BS, k, sigma, opts) +[d, v] = eigs(AS, BS, k, sigma, opts) + +// With function +clear opts +function y = fn(x) + y = A * x; +endfunction + +opts.isreal = %t; +opts.issym = %t; + +d = eigs(fn, 10, [], k, 'LM', opts) + +function y = fn(x) + y = A \ x; +endfunction + +d = eigs(fn, 10, [], k, 'SM', opts) + +function y = fn(x) + y = (A - 4 * eye(10,10)) \ x; +endfunction + +d = eigs(fn, 10, [], k, 4, opts) + ]]> + </programlisting> + </refsection> + <refsection> + <title>Example for real non-symmetric problems</title> + <programlisting role="example"> + <![CDATA[ + clear opts + A = diag(10*ones(10,1)); + A(1:$-1,2:$) = A(1:$-1,2:$) + diag(6*ones(9,1)); + A(2:$,1:$-1) = A(2:$,1:$-1) + diag(-6*ones(9,1)); + + B = eye(10,10); + k = 8; + sigma = 'SM'; + opts.cholB = %t; + + d = eigs(A) +[d, v] = eigs(A) + + d = eigs(A, B, k, sigma) + [d, v] = eigs(A, B, k, sigma) + + d = eigs(A, B, k, sigma, opts) + [d, v] = eigs(A, B, k, sigma, opts) + +// With sparses + AS = sparse(A); + BS = sparse(B); + +d = eigs(AS) +[d, v] = eigs(AS) + d = eigs(AS, BS, k, sigma) + [d, v] = eigs(AS, BS, k, sigma) + + d = eigs(AS, BS, k, sigma, opts) + [d, v] = eigs(AS, BS, k, sigma, opts) + + // With function +clear opts +function y = fn(x) + y = A * x; +endfunction + +opts.isreal = %t; +opts.issym = %f; + +d = eigs(fn, 10, [], k, 'LM', opts) + +function y = fn(x) + y = A \ x; +endfunction + +d = eigs(fn, 10, [], k, 'SM', opts) + +function y = fn(x) + y = (A - 4 * eye(10,10)) \ x; +endfunction + +d = eigs(fn, 10, [], k, 4, opts) + ]]> + </programlisting> + </refsection> + <refsection> + <title>Example for complex problems</title> + <programlisting role="example"> + <![CDATA[ + clear opts + A = diag(10*ones(10,1) + %i * ones(10,1)); + A(1:$-1,2:$) = A(1:$-1,2:$) + diag(6*ones(9,1)); + A(2:$,1:$-1) = A(2:$,1:$-1) + diag(-6*ones(9,1)); + + B = eye(10,10); + k = 8; + sigma = 'LM'; + opts.cholB = %t; + + d = eigs(A) +[d, v] = eigs(A) + + d = eigs(A, B, k, sigma) + [d, v] = eigs(A, B, k, sigma) + d = eigs(A, B, k, sigma, opts) + [d, v] = eigs(A, B, k, sigma, opts) + + // With sparses + AS = sparse(A); + BS = sparse(B); + + d = eigs(AS) +[d, v] = eigs(AS) + + d = eigs(AS, BS, k, sigma) + [d, v] = eigs(AS, BS, k, sigma) + + d = eigs(AS, BS, k, sigma, opts) + [d, v] = eigs(AS, BS, k, sigma, opts) + + // With function +clear opts +function y = fn(x) + y = A * x; +endfunction + +opts.isreal = %f; +opts.issym = %f; + +d = eigs(fn, 10, [], k, 'LM', opts) + +function y = fn(x) + y = A \ x; +endfunction + +d = eigs(fn, 10, [], k, 'SM', opts) + +function y = fn(x) + y = (A - 4 * eye(10,10)) \ x; +endfunction + +d = eigs(fn, 10, [], k, 4, opts) + ]]> + </programlisting> + </refsection> + <refsection role="see also"> + <title>See Also</title> + <simplelist type="inline"> + <member> + <link linkend="spec">spec</link> + </member> + </simplelist> + </refsection> + <refsection> + <title>History</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revremark>Function introduced. Deprecates dnaupd, dneupd, dsaupd, dseupd, znaupd and zneupd.</revremark> + </revision> + </revhistory> + </refsection> +</refentry> 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 @@ +<?xml version="1.0" encoding="UTF-8"?> +<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="znaupd" xml:lang="en"> + <refnamediv> + <refname>znaupd</refname> + <refpurpose> + 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. + <emphasis role="bold"> + This function is obsolete. Please use <link linkend="eigs">eigs</link> + </emphasis> + </refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>Calling Sequence</title> + <synopsis>[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)</synopsis> + </refsynopsisdiv> + <refsection> + <title>Arguments</title> + <variablelist> + <varlistentry> + <term>IDO</term> + <listitem> + <para>Integer. (INPUT/OUTPUT) </para> + <para> + 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. + </para> + <para> + The operand is given in WORKD(IPNTR(1)), the result must be + put in WORKD(IPNTR(2)). + </para> + <itemizedlist> + <listitem> + <para> + IDO = 0: first call to the reverse communication interface + </para> + </listitem> + <listitem> + <para> + 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. + </para> + <para> + This is for the initialization phase to force the starting + vector into the range of OP. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + IDO = 3: compute and return the shifts in the first NP + locations of WORKL. + </para> + </listitem> + <listitem> + <para>IDO = 99: done </para> + </listitem> + </itemizedlist> + <para> + 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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>BMAT</term> + <listitem> + <para>Character. (INPUT) </para> + <para> + specifies the type of the matrix B that defines the + semi-inner product for the operator OP. + </para> + <itemizedlist> + <listitem> + <para>'I': standard eigenvalue problem A * x = lambda * x</para> + </listitem> + <listitem> + <para> + 'G': generalized eigenvalue problem A * x = + lambda * M * x + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>N</term> + <listitem> + <para>Integer. (INPUT) </para> + <para>Dimension of the eigenproblem.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>WHICH</term> + <listitem> + <para>string of length 2. (INPUT) </para> + <itemizedlist> + <listitem> + <para> + 'LM': want the NEV eigenvalues of largest + magnitude. + </para> + </listitem> + <listitem> + <para> + 'SM': want the NEV eigenvalues of smallest + magnitude. + </para> + </listitem> + <listitem> + <para> + 'LR': want the NEV eigenvalues of largest real + part. + </para> + </listitem> + <listitem> + <para> + 'SR': want the NEV eigenvalues of smallest real part. + </para> + </listitem> + <listitem> + <para> + 'LI': want the NEV eigenvalues of largest imaginary + part. + </para> + </listitem> + <listitem> + <para> + 'SI': want the NEV eigenvalues of smallest imaginary + part. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>NEV</term> + <listitem> + <para>Integer. (INPUT) </para> + <para> + Number of eigenvalues of OP to be computed. 0 < NEV < + N - 1. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>TOL</term> + <listitem> + <para>Double precision scalar. (INPUT) </para> + <para> + 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). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>RESID</term> + <listitem> + <para>Complex*16 array of length N. (INPUT/OUTPUT) </para> + <para> + 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. + </para> + <para>On OUTPUT: RESID contains the final residual vector.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>NCV</term> + <listitem> + <para>Integer. (INPUT) </para> + <para> + Number of columns of the matrix V. NCV must satisfy the two + inequalities 2 <= NCV - NEV and NCV <= N. + </para> + <para> + 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.) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>V</term> + <listitem> + <para>Complex*16 array N by NCV. (OUTPUT) </para> + <para>Contains the final set of Arnoldi basis vectors.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>IPARAM</term> + <listitem> + <para>Integer array of length 11. (INPUT/OUTPUT) </para> + <itemizedlist> + <listitem> + <para> + 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. + </para> + <itemizedlist> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + ISHIFT = 2: other choice of internal shift to be + defined. + </para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para>IPARAM(2) = No longer referenced</para> + </listitem> + <listitem> + <para>IPARAM(3) = MXITER </para> + <para> + On INPUT: maximum number of Arnoldi update iterations + allowed. + </para> + <para> + On OUTPUT: actual number of Arnoldi update iterations + taken. + </para> + </listitem> + <listitem> + <para> + IPARAM(4) = NB: blocksize to be used in the recurrence. + The code currently works only for NB = 1. + </para> + </listitem> + <listitem> + <para> + IPARAM(5) = NCONV: number of "converged" Ritz values. This + represents the number of Ritz values that satisfy the + convergence criterion. + </para> + </listitem> + <listitem> + <para> + IPARAM(6) = IUPD No longer referenced. Implicit restarting + is ALWAYS used. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para>IPARAM(9) = NUMOP, </para> + <para>IPARAM(10) = NUMOPB, </para> + <para> + 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. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>IPNTR</term> + <listitem> + <para>Integer array of length 14. (OUTPUT) </para> + <para> + Pointer to mark the starting locations in the WORKD and WORKL + arrays for matrices/vectors used by the Arnoldi iteration. + </para> + <itemizedlist> + <listitem> + <para> + IPNTR(1): pointer to the current operand vector X in + WORKD. + </para> + </listitem> + <listitem> + <para> + IPNTR(2): pointer to the current result vector Y in + WORKD. + </para> + </listitem> + <listitem> + <para> + IPNTR(3): pointer to the vector B * X in WORKD when used + in the shift-and-invert mode. + </para> + </listitem> + <listitem> + <para> + IPNTR(4): pointer to the next available location in WORKL + that is untouched by the program. + </para> + </listitem> + <listitem> + <para> + IPNTR(5): pointer to the NCV by NCV upper Hessenberg + matrix H in WORKL. + </para> + </listitem> + <listitem> + <para>IPNTR(6): pointer to the ritz value array RITZ </para> + </listitem> + <listitem> + <para> + IPNTR(7): pointer to the (projected) ritz vector array Q + </para> + </listitem> + <listitem> + <para> + IPNTR(8): pointer to the error BOUNDS array in WORKL. + </para> + </listitem> + <listitem> + <para> + IPNTR(14): pointer to the NP shifts in WORKL. See Remark 5 + below. + </para> + </listitem> + </itemizedlist> + <para> + Note: IPNTR(9:13) is only referenced by zneupd. See Remark 2 + below. + </para> + <itemizedlist> + <listitem> + <para> + IPNTR(9): pointer to the NCV RITZ values of the original + system. + </para> + </listitem> + <listitem> + <para>IPNTR(10): Not Used </para> + </listitem> + <listitem> + <para> + IPNTR(11): pointer to the NCV corresponding error + bounds. + </para> + </listitem> + <listitem> + <para> + IPNTR(12): pointer to the NCV by NCV upper triangular + Schur matrix for H. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>WORKD</term> + <listitem> + <para> + Complex*16 work array of length 3 * N. (REVERSE COMMUNICATION) + </para> + <para> + Distributed array to be used in the basic Arnoldi iteration + for reverse communication. + </para> + <para> + The user should not use WORKD as temporary workspace during + the iteration !!!!!!!!!! + </para> + <para>See Data Distribution Note below.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>WORKL</term> + <listitem> + <para> + Complex*16 work array of length 3 * NCV ** 2 + 5 * NCV. (OUTPUT/WORKSPACE) + </para> + <para> + Private (replicated) array on each PE or array allocated on + the front end. See Data Distribution Note below. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>RWORK</term> + <listitem> + <para> + Double precision work array of length NCV (WORKSPACE) Private + (replicated) array on each PE or array allocated on the front + end. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>INFO</term> + <listitem> + <para>Integer. (INPUT/OUTPUT) </para> + <para> + If INFO == 0, a randomly initial residual vector is used. + </para> + <para> + If INFO ~= 0, RESID contains the initial residual vector, + possibly from a previous run. + </para> + <para>Error flag on output.</para> + <itemizedlist> + <listitem> + <para>0: Normal exit.</para> + </listitem> + <listitem> + <para> + 1: Maximum number of iterations taken. All possible + eigenvalues of OP has been found. IPARAM(5) returns the number + of wanted converged Ritz values. + </para> + </listitem> + <listitem> + <para> + 2: No longer an informational error. Deprecated starting + with release 2 of ARPACK. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para>-1: N must be positive.</para> + </listitem> + <listitem> + <para>-2: NEV must be positive.</para> + </listitem> + <listitem> + <para>-3: NCV-NEV >= 1 and less than or equal to N.</para> + </listitem> + <listitem> + <para> + -4: The maximum number of Arnoldi update iteration must be + greater than zero. + </para> + </listitem> + <listitem> + <para> + -5: WHICH must be one of 'LM', 'SM', 'LR', 'SR', 'LI', + 'SI'. + </para> + </listitem> + <listitem> + <para>-6: BMAT must be one of 'I' or 'G'.</para> + </listitem> + <listitem> + <para>-7: Length of private work array is not sufficient.</para> + </listitem> + <listitem> + <para> + -8: Error return from LAPACK eigenvalue + calculation. + </para> + </listitem> + <listitem> + <para>-9: Starting vector is zero.</para> + </listitem> + <listitem> + <para>-10: IPARAM(7) must be 1, 2, 3.</para> + </listitem> + <listitem> + <para>-11: IPARAM(7) = 1 and BMAT = 'G' are incompatible.</para> + </listitem> + <listitem> + <para>-12: IPARAM(1) must be equal to 0 or 1.</para> + </listitem> + <listitem> + <para> + -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. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Description</title> + <para> + 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. + </para> + <para> + NOTE: if both OP and B are real, then dsaupd or dnaupd should be + used. + </para> + <para> + 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: + </para> + <itemizedlist> + <listitem> + <para>Mode 1: A * x = lambda * x. </para> + <para>===> OP = A and B = I.</para> + </listitem> + <listitem> + <para>Mode 2: A * x = lambda * M * x, M hermitian positive definite </para> + <para>===> OP = inv[M] * A and B = M. </para> + <para>===> (If M can be factored see remark 3 below) </para> + </listitem> + <listitem> + <para>Mode 3: A * x = lambda * M * x, M hermitian semi-definite </para> + <para>===> OP = inv[A - sigma * M] * M and B = M. </para> + <para> + ===> shift-and-invert mode If OP * x = amu * x, then lambda = + sigma + 1/amu. + </para> + </listitem> + </itemizedlist> + <para> + 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 + </para> + <para>[A - sigma * M] * w = v or M * w = v, </para> + <para> + 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. + </para> + </refsection> + <refsection> + <title>Remarks</title> + <orderedlist> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + When IPARAM(1) = 0, and IDO = 3, the user needs to provide the + NP = IPARAM(8) complex shifts in locations + </para> + <para> + WORKL(IPNTR(14)), WORKL(IPNTR(14)+1), ... , WORKL(IPNTR(14)+NP). + </para> + <para> + 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 + </para> + <para> + WORKL(IPNTR(8)), WORKL(IPNTR(8)+1), ... , + WORKL(IPNTR(8)+NCV-1). + </para> + </listitem> + </orderedlist> + </refsection> + <refsection> + <title>Example</title> + <programlisting role="example"> + <![CDATA[ +// The following sets dimensions for this problem. + +nx = 10; + +nev = 3; +ncv = 6; +bmat = 'I'; +which = 'LM'; + +// Local Arrays + +iparam = zeros(11, 1); +ipntr = zeros(14, 1); +_select = zeros(ncv, 1); +d = zeros(nev + 1, 1) + 0 * %i; +z = zeros(nx, nev) + 0* %i; +resid = zeros(nx, 1) + 0 * %i; +v = zeros(nx, ncv) + 0 * %i; +workd = zeros(3 * nx, 1) + 0 * %i; +workev = zeros(2 * ncv, 1) + 0 * %i; +rwork = zeros(ncv, 1); +workl = zeros(3 * ncv * ncv + 5 *ncv, 1) + 0 * %i; + +// Build the complex test matrix +A = diag(10 * ones(nx,1) + %i * ones(nx,1)); +A(1:$-1,2:$) = A(1:$-1,2:$) + diag(6 * ones(nx - 1,1)); +A(2:$,1:$-1) = A(2:$,1:$-1) + diag(-6 * ones(nx - 1,1)); + +tol = 0; +ido = 0; + +ishfts = 1; +maxitr = 300; +mode1 = 1; + +iparam(1) = ishfts; +iparam(3) = maxitr; +iparam(7) = mode1; + +sigma = complex(0); +info_znaupd = 0; +// M A I N L O O P (Reverse communication) +while(ido <> 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); + +]]> + </programlisting> + </refsection> + <refsection role="see also"> + <title>See Also</title> + <simplelist type="inline"> + <member> + <link linkend="dnaupd">dnaupd</link> + </member> + <member> + <link linkend="dnaupd">dneupd</link> + </member> + <member> + <link linkend="dnaupd">zneupd</link> + </member> + </simplelist> + </refsection> + <refsection> + <title>Bibliography</title> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 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). + </para> + </refsection> + <refsection> + <title>Used Functions</title> + <para>Based on ARPACK routine znaupd</para> + </refsection> + <refsection> + <title>History</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revremark> + Function obsolete for <link linkend="eigs">eigs</link>. + </revremark> + </revision> + </revhistory> + </refsection> +</refentry> 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 @@ +<?xml version="1.0" encoding="UTF-8"?> +<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="zneupd" xml:lang="en"> + <refnamediv> + <refname>zneupd</refname> + <refpurpose> + Interface for the Implicitly Restarted Arnoldi Iteration, to + compute approximations to the converged approximations to eigenvalues of + A * z = lambda * B * z + <emphasis role="bold"> + This function is obsolete. Please use <link linkend="eigs">eigs</link> + </emphasis> + </refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>Calling Sequence</title> + <synopsis> + [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) + </synopsis> + </refsynopsisdiv> + <refsection> + <title>Arguments</title> + <variablelist> + <varlistentry> + <term>RVEC</term> + <listitem> + <para>Integer. (INPUT) </para> + <para> + 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. + </para> + <itemizedlist> + <listitem> + <para>RVEC = 0 Compute Ritz values only.</para> + </listitem> + <listitem> + <para> + RVEC = 1 Compute Ritz vectors or Schur vectors. See + Remarks below. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>HOWMANY</term> + <listitem> + <para>Character. (INPUT) </para> + <para> + Specifies the form of the basis for the invariant subspace + corresponding to the converged Ritz values that is to be computed. + </para> + <itemizedlist> + <listitem> + <para>'A': Compute NEV Ritz vectors;</para> + </listitem> + <listitem> + <para>'P': Compute NEV Schur vectors;</para> + </listitem> + <listitem> + <para> + 'S': compute some of the Ritz vectors, specified by the + integer array SELECT. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>SELECT</term> + <listitem> + <para>Integer array of dimension NCV. (INPUT) </para> + <para> + 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. + </para> + <para> + If HOWMANY = 'A' or 'P', SELECT need not be initialized but it + is used as internal workspace. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>D</term> + <listitem> + <para>Complex*16 array of dimension NEV + 1. (OUTPUT) </para> + <para> + On exit, D contains the Ritz approximations to the eigenvalues + lambda for A * z = lambda * B * z. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Z</term> + <listitem> + <para>Complex*16 N by NEV array. (OUTPUT) </para> + <para>On exit, </para> + <para> + 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. + </para> + <para> + If RVEC = 0 or HOWMANY = 'P', then Z is NOT REFERENCED. + </para> + <para> + 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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>SIGMA</term> + <listitem> + <para>Complex*16. (INPUT) </para> + <para>If IPARAM(7) = 3 then SIGMA represents the shift. </para> + <para>Not referenced if IPARAM(7) = 1 or 2.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>WORKev</term> + <listitem> + <para>Complex*16 work array of dimension 2 * NCV. (WORKSPACE)</para> + </listitem> + </varlistentry> + </variablelist> + <para> + 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. + </para> + <para> + These arguments MUST NOT BE MODIFIED between the last call to + ZNAUPD and the call to ZNEUPD. + </para> + <para> + Three of these parameters (V, WORKL and INFO) are also output + parameters. + </para> + <variablelist> + <varlistentry> + <term>V</term> + <listitem> + <para>Complex*16 N by NCV array. (INPUT/OUTPUT) </para> + <para> + Upon INPUT: the NCV columns of V contain the Arnoldi basis + vectors for OP as constructed by ZNAUPD. + </para> + <para> + Upon OUTPUT: If RVEC = 1 the first NCONV = IPARAM(5) columns + contain approximate Schur vectors that span the desired invariant + subspace. + </para> + <para> + 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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>WORKL</term> + <listitem> + <para> + Double precision work array of length LWORKL. + (OUTPUT/WORKSPACE) + </para> + <para> + WORKL(1:ncv * ncv + 2 * ncv) contains information obtained in + znaupd. They are not changed by zneupd. + </para> + <para> + 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. + </para> + <para> + Note: IPNTR(9:13) contains the pointer into WORKL for + addresses of the above information computed by zneupd. + </para> + <itemizedlist> + <listitem> + <para> + IPNTR(9): pointer to the NCV RITZ values of the original + system. + </para> + </listitem> + <listitem> + <para>IPNTR(10): Not used </para> + </listitem> + <listitem> + <para> + IPNTR(11): pointer to the NCV corresponding error + estimates. + </para> + </listitem> + <listitem> + <para> + IPNTR(12): pointer to the NCV by NCV upper triangular + Schur matrix for H. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>INFO</term> + <listitem> + <para>Integer. (OUTPUT) </para> + <para>Error flag on output.</para> + <itemizedlist> + <listitem> + <para>0: Normal exit.</para> + </listitem> + <listitem> + <para> + 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. + </para> + <para> + NOTE: Not necessary if Z and V share the same space. + Please notify the authors if this error occurs. + </para> + </listitem> + <listitem> + <para>-1: N must be positive.</para> + </listitem> + <listitem> + <para>-2: NEV must be positive.</para> + </listitem> + <listitem> + <para>-3: NCV-NEV >= 1 and less than or equal to N.</para> + </listitem> + <listitem> + <para> + -5: WHICH must be one of 'LM', 'SM', 'LR', 'SR', 'LI', + 'SI'. + </para> + </listitem> + <listitem> + <para>-6: BMAT must be one of 'I' or 'G'.</para> + </listitem> + <listitem> + <para> + -7: Length of private work WORKL array is not + sufficient. + </para> + </listitem> + <listitem> + <para> + -8: Error return from LAPACK eigenvalue calculation. This + should never happened. + </para> + </listitem> + <listitem> + <para> + -9: Error return from calculation of eigenvectors. + Informational error from LAPACK routine ztrevc. + </para> + </listitem> + <listitem> + <para>-10: IPARAM(7) must be 1, 2, 3.</para> + </listitem> + <listitem> + <para>-11: IPARAM(7) = 1 and BMAT = 'G' are incompatible.</para> + </listitem> + <listitem> + <para>-12: HOWMANY = 'S' not yet implemented.</para> + </listitem> + <listitem> + <para> + -13: HOWMANY must be one of 'A' or 'P' if RVEC = .true. + </para> + </listitem> + <listitem> + <para> + -14: ZNAUPD did not find any eigenvalues to sufficient + accuracy. + </para> + </listitem> + <listitem> + <para> + -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. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Description</title> + <para> + This subroutine returns the converged approximations to eigenvalues + of A * z = lambda * B * z and (optionally): + </para> + <orderedlist> + <listitem> + <para>The corresponding approximate eigenvectors; </para> + </listitem> + <listitem> + <para> + An orthonormal basis for the associated approximate invariant + subspace; + </para> + </listitem> + <listitem> + <para>Both.</para> + </listitem> + </orderedlist> + <para> + There is negligible additional cost to obtain eigenvectors. An + orthonormal basis is always computed. + </para> + <para> + There is an additional storage cost of n*nev if both are requested + (in this case a separate array Z must be supplied). + </para> + <para> + 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. + </para> + <para>ZNAUPD must be called before this routine is called. </para> + <para> + 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. + </para> + <para> + The computed orthonormal basis for the invariant subspace + corresponding to these Ritz values is referred to as a Schur basis. + </para> + <para> + 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. + </para> + </refsection> + <refsection> + <title>Remarks</title> + <orderedlist> + <listitem> + <para>Currently only HOWMNY = 'A' and 'P' are implemented. </para> + </listitem> + <listitem> + <para> + Schur vectors are an orthogonal representation for the basis of + Ritz vectors. Thus, their numerical properties are often superior. + </para> + <para>If RVEC = 1 then the relationship </para> + <para>A * V(:,1:IPARAM(5)) = V(:,1:IPARAM(5)) * T, </para> + <para>and </para> + <para>transpose( V(:,1:IPARAM(5)) ) * V(:,1:IPARAM(5)) = I </para> + <para> + are approximately satisfied. Here T is the leading submatrix of + order IPARAM(5) of the upper triangular matrix stored + workl(ipntr(12)). + </para> + </listitem> + </orderedlist> + </refsection> + <refsection> + <title>Example</title> + <programlisting role="example"> + <![CDATA[ +// The following sets dimensions for this problem. + +nx = 10; + +nev = 3; +ncv = 6; +bmat = 'I'; +which = 'LM'; + +// Local Arrays + +iparam = zeros(11, 1); +ipntr = zeros(14, 1); +_select = zeros(ncv, 1); +d = zeros(nev + 1, 1) + 0 * %i; +z = zeros(nx, nev) + 0* %i; +resid = zeros(nx, 1) + 0 * %i; +v = zeros(nx, ncv) + 0 * %i; +workd = zeros(3 * nx, 1) + 0 * %i; +workev = zeros(2 * ncv, 1) + 0 * %i; +rwork = zeros(ncv, 1); +workl = zeros(3 * ncv * ncv + 5 *ncv, 1) + 0 * %i; + +// Build the complex test matrix +A = diag(10 * ones(nx,1) + %i * ones(nx,1)); +A(1:$-1,2:$) = A(1:$-1,2:$) + diag(6 * ones(nx - 1,1)); +A(2:$,1:$-1) = A(2:$,1:$-1) + diag(-6 * ones(nx - 1,1)); + +tol = 0; +ido = 0; + +ishfts = 1; +maxitr = 300; +mode1 = 1; + +iparam(1) = ishfts; +iparam(3) = maxitr; +iparam(7) = mode1; + +sigma = complex(0); +info_znaupd = 0; +// M A I N L O O P (Reverse communication) +while(ido <> 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); + +]]> + </programlisting> + </refsection> + <refsection role="see also"> + <title>See Also</title> + <simplelist type="inline"> + <member> + <link linkend="dnaupd">znaupd</link> + </member> + <member> + <link linkend="dnaupd">dnaupd</link> + </member> + <member> + <link linkend="dnaupd">dneupd</link> + </member> + </simplelist> + </refsection> + <refsection> + <title>Bibliography</title> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 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). + </para> + </refsection> + <refsection> + <title>Used Functions</title> + <para>Based on ARPACK routine zneupd</para> + </refsection> + <refsection> + <title>History</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revremark> + Function obsolete for <link linkend="eigs">eigs</link>. + </revremark> + </revision> + </revhistory> + </refsection> +</refentry> 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 @@ +<?xml version="1.0" encoding="UTF-8"?> +<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="dnaupd" xml:lang="ja"> + <refnamediv> + <refname>dnaupd</refname> + <refpurpose> + 暗黙のうちに再開されるArnoldi反復へのインターフェイスで, + 実線形演算子の小数の固有値/ベクトルの組を近似的に計算します. + <emphasis role="bold"> + この関数は廃止されました. <link linkend="eigs">eigs</link>を使用してください + </emphasis> + </refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>Calling Sequence</title> + <synopsis>[IDO, RESID, V, IPARAM, IPNTR, WORKD, WORKL, INFO] = dnaupd(ID0, BMAT, N, WHICH, NEV, TOL, RESID, NCV, V, IPARAM, IPNTR, WORKD, WORKL, INFO)</synopsis> + </refsynopsisdiv> + <refsection> + <title>Arguments</title> + <variablelist> + <varlistentry> + <term>ID0</term> + <listitem> + <para> + Integer. (INPUT/OUTPUT) + </para> + <para> + 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)). + </para> + <itemizedlist> + <listitem> + <para> + IDO = 0: first call to the reverse communication + interface. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para>IDO = 99: done.</para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>BMAT</term> + <listitem> + <para> + Character. (INPUT) + </para> + <para> + specifies the type of the matrix B that defines the + semi-inner product for the operator OP. + </para> + <itemizedlist> + <listitem> + <para>'I' - standard eigenvalue problem A * x = lambda * x</para> + </listitem> + <listitem> + <para> + 'G' - generalized eigenvalue problem A * x = + lambda * B * x + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>N</term> + <listitem> + <para>Integer. (INPUT)</para> + <para>dimension of the eigenproblem.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>WHICH</term> + <listitem> + <para> + string of length 2. (INPUT) + </para> + <para> + Specifies which of the Ritz values of OP to + compute. + </para> + <itemizedlist> + <listitem> + <para> + 'LM' - want the NEV eigenvalues of largest + magnitude. + </para> + </listitem> + <listitem> + <para> + 'SM' - want the NEV eigenvalues of smallest + magnitude. + </para> + </listitem> + <listitem> + <para> + 'LR' - want the NEV eigenvalues of largest real + part. + </para> + </listitem> + <listitem> + <para> + 'SR' - want the NEV eigenvalues of smallest real + part. + </para> + </listitem> + <listitem> + <para> + 'LI' - want the NEV eigenvalues of largest imaginary + part. + </para> + </listitem> + <listitem> + <para> + 'SI' - want the NEV eigenvalues of smallest imaginary + part. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>NEV</term> + <listitem> + <para> + Integer. (INPUT) + </para> + <para> + number of eigenvalues of OP to be computed. 0 < + NEV < N-1. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>TOL</term> + <listitem> + <para> + scalar. (INPUT) + </para> + <para> + 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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>RESID</term> + <listitem> + <para>array of length N. (INPUT/OUTPUT)</para> + <para> + On INPUT: If INFO = 0, a random initial residual vector is + used, else RESID contains the initial residual vector, possibly from + a previous run. + </para> + <para>On OUTPUT: RESID contains the final residual vector.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>NCV</term> + <listitem> + <para> + Integer. (INPUT) + </para> + <para> + number of columns of the matrix V. NCV must satisfy + the two inequalities 2 <= NCV - NEV and NCV <= N. + </para> + <para> + This will indicate how many Arnoldi vectors are generated at + each iteration. + </para> + <para> + 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. + </para> + <para> + NOTE: 2 <= NCV - NEV in order that complex conjugate pairs of + Ritz values are kept together. (See remark 4 below) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>V</term> + <listitem> + <para> + N by NCV array. (OUTPUT) + </para> + <para> + Contains the final set of Arnoldi basis + vectors. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>IPARAM</term> + <listitem> + <para>array of length 11. (INPUT/OUTPUT)</para> + <itemizedlist> + <listitem> + <para> + 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. + </para> + <itemizedlist> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para>IPARAM(2) = LEVEC. No longer referenced.</para> + </listitem> + <listitem> + <para>IPARAM(3) = MXITER </para> + <para> + On INPUT: maximum number of Arnoldi update iterations + allowed. + </para> + <para> + On OUTPUT: actual number of Arnoldi update iterations + taken. + </para> + </listitem> + <listitem> + <para> + IPARAM(4) = NB: blocksize to be used in the recurrence. + The code currently works only for NB = 1. + </para> + </listitem> + <listitem> + <para> + IPARAM(5) = NCONV: number of "converged" Ritz values. This + represents the number of Ritz values that satisfy the + convergence criterion. + </para> + </listitem> + <listitem> + <para> + IPARAM(6) = IUPD No longer referenced. Implicit restarting + is ALWAYS used. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + <para>0 < NP <= NCV-NEV. See Remark 5 below.</para> + </listitem> + <listitem> + <para>IPARAM(9) = NUMOP, </para> + <para>IPARAM(10) = NUMOPB, </para> + <para>IPARAM(11) = NUMREO, </para> + <para> + 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. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>IPNTR</term> + <listitem> + <para> + array of length 14. (OUTPUT) + </para> + <para> + Pointer to mark the starting locations in + the WORKD and WORKL arrays for matrices/vectors used by the Arnoldi + iteration. + </para> + <itemizedlist> + <listitem> + <para> + IPNTR(1): pointer to the current operand vector X in + WORKD. + </para> + </listitem> + <listitem> + <para> + IPNTR(2): pointer to the current result vector Y in + WORKD. + </para> + </listitem> + <listitem> + <para> + IPNTR(3): pointer to the vector B * X in WORKD when used + in the shift-and-invert mode. + </para> + </listitem> + <listitem> + <para> + IPNTR(4): pointer to the next available location in WORKL + that is untouched by the program. + </para> + </listitem> + <listitem> + <para> + IPNTR(5): pointer to the NCV by NCV upper Hessenberg + matrix H in WORKL. + </para> + </listitem> + <listitem> + <para> + IPNTR(6): pointer to the real part of the ritz value array + RITZR in WORKL. + </para> + </listitem> + <listitem> + <para> + IPNTR(7): pointer to the imaginary part of the ritz value + array RITZI in WORKL. + </para> + </listitem> + <listitem> + <para> + IPNTR(8): pointer to the Ritz estimates in array WORKL + associated with the Ritz values located in RITZR and RITZI in + WORKL. + </para> + </listitem> + <listitem> + <para> + IPNTR(14): pointer to the NP shifts in WORKL. See Remark 5 + below. + </para> + </listitem> + </itemizedlist> + <para> + Note: IPNTR(9:13) is only referenced by dneupd . See Remark + 2. + </para> + <itemizedlist> + <listitem> + <para> + IPNTR(9): pointer to the real part of the NCV RITZ values + of the original system. + </para> + </listitem> + <listitem> + <para> + IPNTR(10): pointer to the imaginary part of the NCV RITZ + values of the original system. + </para> + </listitem> + <listitem> + <para> + IPNTR(11): pointer to the NCV corresponding error + bounds. + </para> + </listitem> + <listitem> + <para> + IPNTR(12):pointer to the NCV by NCV upper quasi-triangular + Schur matrix for H. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>WORKD</term> + <listitem> + <para> + Double precision work array of length 3 * N. (REVERSE + COMMUNICATION) + </para> + <para> + 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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>WORKL</term> + <listitem> + <para> + work array of length at least 3 * NCV ** 2 + 6 * NCV. + (OUTPUT/WORKSPACE) + </para> + <para> + Private (replicated) array on each PE or array + allocated on the front end. See Data Distribution Note below. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>INFO</term> + <listitem> + <para>Integer. (INPUT/OUTPUT)</para> + <para> + If INFO == 0, a randomly initial residual vector is used, else + RESID contains the initial residual vector, possibly from a previous + run. + </para> + <para>Error flag on output.</para> + <itemizedlist> + <listitem> + <para>0: Normal exit.</para> + </listitem> + <listitem> + <para> + 1: Maximum number of iterations taken. All possible + eigenvalues of OP has been found. IPARAM(5) returns the number + of wanted converged Ritz values. + </para> + </listitem> + <listitem> + <para> + 2: No longer an informational error. Deprecated starting + with release 2 of ARPACK. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para>-1: N must be positive.</para> + </listitem> + <listitem> + <para>-2: NEV must be positive.</para> + </listitem> + <listitem> + <para>-3: NCV-NEV >= 2 and less than or equal to N.</para> + </listitem> + <listitem> + <para> + -4: The maximum number of Arnoldi update iterations + allowed must be greater than zero. + </para> + </listitem> + <listitem> + <para> + -5: WHICH must be one of 'LM', 'SM', 'LR', 'SR', 'LI', + 'SI'. + </para> + </listitem> + <listitem> + <para>-6: BMAT must be one of 'I' or 'G'.</para> + </listitem> + <listitem> + <para> + -7: Length of private work array WORKL is not + sufficient. + </para> + </listitem> + <listitem> + <para> + -8: Error return from LAPACK eigenvalue + calculation. + </para> + </listitem> + <listitem> + <para>-9: Starting vector is zero.</para> + </listitem> + <listitem> + <para>-10: IPARAM(7) must be 1, 2, 3, 4.</para> + </listitem> + <listitem> + <para>-11: IPARAM(7) = 1 and BMAT = 'G' are incompatable.</para> + </listitem> + <listitem> + <para>-12: IPARAM(1) must be equal to 0 or 1.</para> + </listitem> + <listitem> + <para> + -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. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Description</title> + <para> + 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. + </para> + <para> + The computed approximate eigenvalues are called Ritz values and the + corresponding approximate eigenvectors are called Ritz vectors. + </para> + <para> + dnaupd is usually called iteratively to solve one of the following + problems: + </para> + <itemizedlist> + <listitem> + <para> + Mode 1: A*x = lambda*x. <literal> + OP = A , B = + I + </literal> + . + </para> + </listitem> + <listitem> + <para> + Mode 2: A*x = lambda*M*x, M symmetric positive definite + <literal>OP = inv[M]*A, B = M</literal>. (If M can be factored see + remark 3 below) + </para> + </listitem> + <listitem> + <para> + Mode 3: A*x = lambda*M*x, M symmetric positive semi-definite. + <literal>OP = Real_Part{ inv[A - sigma*M]*M }, B = M</literal>. + shift-and-invert mode (in real arithmetic) + </para> + <para> + If <literal>OP*x = amu*x</literal>, then + </para> + <para> + <literal> + amu = 1/2 * [ 1/(lambda-sigma) + + 1/(lambda-conjg(sigma))] + </literal> + . + </para> + <para> + Note: If sigma is real, i.e. imaginary part of sigma is zero; + <literal> + Real_Part{ inv[A - sigma*M]*M } == inv[A - + sigma*M]*M + </literal> + <literal> + amu == + 1/(lambda-sigma) + </literal> + . + </para> + </listitem> + <listitem> + <para> + Mode 4: A*x = lambda*M*x, M symmetric semi-definite <literal> + OP + = Imaginary_Part{ inv[A - sigma*M]*M } , B = M + </literal> + . + shift-and-invert mode (in real arithmetic) + </para> + <para> + If <literal>OP*x = amu*x</literal>, then <literal> + amu = 1/2i * [ + 1/(lambda-sigma) - 1/(lambda-conjg(sigma)) ] + </literal> + . + </para> + </listitem> + </itemizedlist> + <para> + 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. + </para> + <para> + 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 <literal>[A - sigma * M] * w = v</literal> or + <literal>M * w = v</literal>, 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. + </para> + </refsection> + <refsection> + <title>Example</title> + <programlisting role="example"> + <![CDATA[ +// The following sets dimensions for this problem. +nx = 10; +nev = 3; +ncv = 6; +bmat = 'I'; +which = 'LM'; +// Local Arrays +iparam = zeros(11, 1); +ipntr = zeros(14, 1); +_select = zeros(ncv, 1); +dr = zeros(nev + 1, 1); +di = zeros(nev + 1, 1); +z = zeros(nx, nev + 1); +resid = zeros(nx, 1); +v = zeros(nx, ncv); +workd = zeros(3 * nx, 1); +workev = zeros(3 * ncv, 1); +workl = zeros(3 * ncv * ncv + 6 * ncv, 1); +// Build the test matrix +A = diag(10 * ones(nx, 1)); +A(1:$-1,2:$) = A(1:$-1,2:$) + diag(6 * ones(nx-1,1)); +A(2:$,1:$-1) = A(2:$,1:$-1) + diag(-6 * ones(nx-1,1)); +tol = 0; +ido = 0; +ishfts = 1; +maxitr = 300; +mode1 = 1; +iparam(1) = ishfts; +iparam(3) = maxitr; +iparam(7) = mode1; +sigmar = 0; // the real part of the shift +sigmai = 0; // the imaginary part of the shift +info_dnaupd = 0; +// M A I N L O O P (Reverse communication) +while(ido <> 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); +]]> + </programlisting> + </refsection> + <refsection> + <title>Remarks</title> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 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 + </para> + <programlisting> + 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). + </programlisting> + <para> + 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). + </para> + </refsection> + <refsection role="see also"> + <title>See Also</title> + <simplelist type="inline"> + <member> + <link linkend="dsaupd">dsaupd</link> + </member> + <member> + <link linkend="dneupd">dneupd</link> + </member> + </simplelist> + </refsection> + <refsection> + <title>Bibliography</title> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 3. B.N. Parlett, "The Symmetric Eigenvalue Problem". Prentice-Hall, + 1980. + </para> + <para> + 4. B.N. Parlett, B. Nour-Omid, "Towards a Black Box Lanczos + Program", Computer Physics Communications, 53 (1989), pp 169-179. + </para> + <para> + 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. + </para> + <para> + 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). + </para> + <para> + 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. + </para> + <para> + 8. R.B. Lehoucq, D.C. Sorensen, "Implementation of Some Spectral + Transformations in a k-Step Arnoldi Method". In Preparation. + </para> + </refsection> + <refsection> + <title>Used Functions</title> + <para>Based on ARPACK routine dnaupd</para> + </refsection> + <refsection> + <title>履歴</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revremark> + 関数は廃止され,<link linkend="eigs">eigs</link>に代替されました. + </revremark> + </revision> + </revhistory> + </refsection> +</refentry> 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 @@ +<?xml version="1.0" encoding="UTF-8"?> +<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="dneupd" xml:lang="ja"> + <refnamediv> + <refname>dneupd</refname> + <refpurpose> + 暗黙のうちに再開されるArnoldi反復へのインターフェイスで, + 実線形演算子の小数の固有値/ベクトルの組を近似する + A * z = lambda * B * z の固有値を収束的近似により計算します. + <emphasis role="bold"> + この関数は廃止されました. <link linkend="eigs">eigs</link>を使用してください + </emphasis> + </refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>Calling Sequence</title> + <synopsis> + [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) + </synopsis> + </refsynopsisdiv> + <refsection> + <title>Arguments</title> + <variablelist> + <varlistentry> + <term>RVEC</term> + <listitem> + <para>Integer. (INPUT)</para> + <para> + 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. + </para> + <itemizedlist> + <listitem> + <para>RVEC = 0 Compute Ritz values only.</para> + </listitem> + <listitem> + <para>RVEC = 1 Compute the Ritz vectors or Schur vectors.</para> + </listitem> + </itemizedlist> + <para>See Remarks below.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>HOWMANY</term> + <listitem> + <para>Character. (INPUT) </para> + <para> + Specifies the form of the basis for the invariant subspace + corresponding to the converged Ritz values that is to be + computed. + </para> + <itemizedlist> + <listitem> + <para>'A': Compute NEV Ritz vectors;</para> + </listitem> + <listitem> + <para>'P': Compute NEV Schur vectors;</para> + </listitem> + <listitem> + <para> + 'S': compute some of the Ritz vectors, specified by the + integer array SELECT. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>SELECT</term> + <listitem> + <para>Integer array of dimension NCV. (INPUT) </para> + <para> + 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. + </para> + <para> + If HOWMANY = 'A' or 'P', SELECT is used as internal + workspace. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>DR</term> + <listitem> + <para>Double precision array of dimension NEV + 1. (OUTPUT)</para> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>DI</term> + <listitem> + <para>Double precision array of dimension NEV + 1. (OUTPUT) </para> + <para> + On exit, DI contains the imaginary part of the Ritz value + approximations to the eigenvalues of A * z = lambda * B * z associated + with DR. + </para> + <para> + 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). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Z</term> + <listitem> + <para>Double precision N by NEV + 1 array </para> + <para>if RVEC = 1 and HOWMANY = 'A'. (OUTPUT) </para> + <para> + 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. + </para> + <para> + If RVEC = 0 or HOWMANY = 'P', then Z is not referenced. + </para> + <para> + 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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>SIGMAR</term> + <listitem> + <para>Double precision (INPUT) </para> + <para> + If IPARAM(7) = 3 or 4, represents the real part of the + shift. + </para> + <para>Not referenced if IPARAM(7) = 1 or 2.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>SIGMAI</term> + <listitem> + <para>Double precision (INPUT) </para> + <para> + If IPARAM(7) = 3 or 4, represents the imaginary part of the + shift. + </para> + <para> + Not referenced if IPARAM(7) = 1 or 2. See remark 3 + below. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>WORKEV</term> + <listitem> + <para> + Double precision work array of dimension 3 * NCV. + (WORKSPACE) + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + 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 . + </para> + <para> + These arguments MUST NOT BE MODIFIED between the last call to + DNAUPD and the call to DNEUPD . + </para> + <para> + Three of these parameters (V, WORKL, INFO) are also output + parameters. + </para> + <variablelist> + <varlistentry> + <term>V</term> + <listitem> + <para>Double precision N by NCV array. (INPUT/OUTPUT) </para> + <para> + Upon INPUT: the NCV columns of V contain the Arnoldi basis + vectors for OP as constructed by DNAUPD. + </para> + <para> + 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. + </para> + <para> + 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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>WORKL</term> + <listitem> + <para> + Double precision work array of length LWORKL. + (OUTPUT/WORKSPACE) + </para> + <para> + WORKL(1:ncv*ncv+3*ncv) contains information obtained in dnaupd + . They are not changed by dneupd . + </para> + <para> + 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. + </para> + <para> + Note: IPNTR(9:13) contains the pointer into WORKL for + addresses of the above information computed by dneupd . + </para> + <itemizedlist> + <listitem> + <para> + IPNTR(9): pointer to the real part of the NCV RITZ values + of the original system. + </para> + </listitem> + <listitem> + <para> + IPNTR(10): pointer to the imaginary part of the NCV RITZ + values of the original system. + </para> + </listitem> + <listitem> + <para> + IPNTR(11): pointer to the NCV corresponding error + bounds. + </para> + </listitem> + <listitem> + <para> + IPNTR(12): pointer to the NCV by NCV upper + quasi-triangular Schur matrix for H. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>INFO</term> + <listitem> + <para>Integer. (OUTPUT).</para> + <para>Error flag on output.</para> + <itemizedlist> + <listitem> + <para>0: Normal exit.</para> + </listitem> + <listitem> + <para> + 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. + </para> + <para> + NOTE: Not necessary if Z and V share the same space. + Please notify the authors if this error occurs. + </para> + </listitem> + <listitem> + <para>-1: N must be positive.</para> + </listitem> + <listitem> + <para>-2: NEV must be positive.</para> + </listitem> + <listitem> + <para>-3: NCV-NEV >= 2 and less than or equal to N.</para> + </listitem> + <listitem> + <para> + -5: WHICH must be one of 'LM', 'SM', 'LR', 'SR', 'LI', + 'SI'. + </para> + </listitem> + <listitem> + <para>-6: BMAT must be one of 'I' or 'G'.</para> + </listitem> + <listitem> + <para> + -7: Length of private work WORKL array is not + sufficient. + </para> + </listitem> + <listitem> + <para> + -8: Error return from calculation of a real Schur form. + Informational error from LAPACK routine dlahqr. + </para> + </listitem> + <listitem> + <para> + -9: Error return from calculation of eigenvectors. + Informational error from LAPACK routine dtrevc. + </para> + </listitem> + <listitem> + <para>-10: IPARAM(7) must be 1, 2, 3, 4.</para> + </listitem> + <listitem> + <para>-11: IPARAM(7) = 1 and BMAT = 'G' are incompatible.</para> + </listitem> + <listitem> + <para>-12: HOWMANY = 'S' not yet implemented. </para> + </listitem> + <listitem> + <para>-13: HOWMANY must be one of 'A' or 'P' if RVEC = 1.</para> + </listitem> + <listitem> + <para> + -14: DNAUPD did not find any eigenvalues to sufficient + accuracy. + </para> + </listitem> + <listitem> + <para> + -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. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Description</title> + <para> + This subroutine returns the converged approximations to eigenvalues + of A * z = lambda * B * z and (optionally): + </para> + <orderedlist> + <listitem> + <para>The corresponding approximate eigenvectors;</para> + </listitem> + <listitem> + <para> + An orthonormal basis for the associated approximate invariant + subspace; + </para> + </listitem> + <listitem> + <para>Both.</para> + </listitem> + </orderedlist> + <para> + There is negligible additional cost to obtain eigenvectors. An + orthonormal basis is always computed. + </para> + <para> + There is an additional storage cost of n*nev if both are requested + (in this case a separate array Z must be supplied). + </para> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + The computed orthonormal basis for the invariant subspace + corresponding to these Ritz values is referred to as a Schur basis. + </para> + <para> + 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. + </para> + <para> + For a brief description, see definitions of IPARAM(7), MODE and + WHICH in the documentation of DNAUPD . + </para> + </refsection> + <refsection> + <title>Remarks</title> + <orderedlist> + <listitem> + <para>Currently only HOWMNY = 'A' and 'P' are implemented. </para> + <para>Let trans(X) denote the transpose of X. </para> + </listitem> + <listitem> + <para> + 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 + </para> + <para> + A * V(:,1:IPARAM(5)) = V(:,1:IPARAM(5)) * T, and + trans(V(:,1:IPARAM(5))) * V(:,1:IPARAM(5)) = I + </para> + <para>are approximately satisfied. </para> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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 + </para> + <para>trans(Z(:,I)) * A * Z(:,I) if DI(I) = 0. </para> + <para> + 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 + </para> + <para> + trans(Z(:,I)) * A * Z(:,I) + trans(Z(:,I+1)) * A * Z(:,I+1), + </para> + <para> + trans(Z(:,I)) * A * Z(:,I+1) - trans(Z(:,I+1)) * A * Z(:,I), + </para> + <para>respectively. </para> + <para> + Another possibility is to set RVEC = 1 and HOWMANY = 'P' and + compute + </para> + <para>trans(V(:,1:IPARAM(5))) * A * V(:,1:IPARAM(5)) </para> + <para> + and then an upper quasi-triangular matrix of order IPARAM(5) is + computed. See remark 2 above. + </para> + </listitem> + </orderedlist> + </refsection> + <refsection> + <title>Example</title> + <programlisting role="example"> + <![CDATA[ +// The following sets dimensions for this problem. +nx = 10; +nev = 3; +ncv = 6; +bmat = 'I'; +which = 'LM'; +// Local Arrays +iparam = zeros(11, 1); +ipntr = zeros(14, 1); +_select = zeros(ncv, 1); +dr = zeros(nev + 1, 1); +di = zeros(nev + 1, 1); +z = zeros(nx, nev + 1); +resid = zeros(nx, 1); +v = zeros(nx, ncv); +workd = zeros(3 * nx, 1); +workev = zeros(3 * ncv, 1); +workl = zeros(3 * ncv * ncv + 6 * ncv, 1); +// Build the test matrix +A = diag(10 * ones(nx, 1)); +A(1:$-1,2:$) = A(1:$-1,2:$) + diag(6 * ones(nx-1,1)); +A(2:$,1:$-1) = A(2:$,1:$-1) + diag(-6 * ones(nx-1,1)); +tol = 0; +ido = 0; +ishfts = 1; +maxitr = 300; +mode1 = 1; +iparam(1) = ishfts; +iparam(3) = maxitr; +iparam(7) = mode1; +sigmar = 0; // the real part of the shift +sigmai = 0; // the imaginary part of the shift +info_dnaupd = 0; +// M A I N L O O P (Reverse communication) +while(ido <> 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); +]]> + </programlisting> + </refsection> + <refsection role="see also"> + <title>See Also</title> + <simplelist type="inline"> + <member> + <link linkend="dsaupd">dsaupd</link> + </member> + <member> + <link linkend="dnaupd">dnaupd</link> + </member> + </simplelist> + </refsection> + <refsection> + <title>Bibliography</title> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 3. B.N. Parlett, "The Symmetric Eigenvalue Problem". Prentice-Hall, + 1980. + </para> + <para> + 4. B.N. Parlett, B. Nour-Omid, "Towards a Black Box Lanczos + Program", Computer Physics Communications, 53 (1989), pp 169-179. + </para> + <para> + 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. + </para> + <para> + 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). + </para> + <para> + 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. + </para> + <para> + 8. R.B. Lehoucq, D.C. Sorensen, "Implementation of Some Spectral + Transformations in a k-Step Arnoldi Method". In Preparation. + </para> + </refsection> + <refsection> + <title>Used Functions</title> + <para>Based on ARPACK routine dneupd</para> + </refsection> + <refsection> + <title>履歴</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revremark> + 関数は廃止され,<link linkend="eigs">eigs</link>に代替されました. + </revremark> + </revision> + </revhistory> + </refsection> +</refentry> 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 @@ +<?xml version="1.0" encoding="UTF-8"?> +<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="dsaupd" xml:lang="ja"> + <refnamediv> + <refname>dsaupd</refname> + <refpurpose> + 暗黙のうちに再開されるArnoldi反復へのインターフェイスで, + 実対称線形演算子の小数の固有値/ベクトルの組を近似的に計算します. + <emphasis role="bold"> + この関数は廃止されました. <link linkend="eigs">eigs</link>を使用してください + </emphasis> + </refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>Calling Sequence</title> + <synopsis>[IDO, RESID, V, IPARAM, IPNTR, WORKD, WORKL, INFO] = dsaupd(ID0, BMAT, N, WHICH, NEV, TOL, RESID, NCV, V, IPARAM, IPNTR, WORKD, WORKL, INFO)</synopsis> + </refsynopsisdiv> + <refsection> + <title>Arguments</title> + <variablelist> + <varlistentry> + <term>ID0</term> + <listitem> + <para>Integer. (INPUT/OUTPUT) </para> + <para> + 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. + </para> + <para> + The operand is given in WORKD(IPNTR(1)), the result must be put + in WORKD(IPNTR(2)). (If Mode = 2 see remark 5 below) + </para> + <itemizedlist> + <listitem> + <para> + IDO = 0: first call to the reverse communication + interface. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + IDO = 3: compute the IPARAM(8) shifts where IPNTR(11) is + the pointer into WORKL for placing the shifts. See remark 6 + below. + </para> + </listitem> + <listitem> + <para>IDO = 99: done</para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>BMAT</term> + <listitem> + <para>Character. (INPUT)</para> + <para> + Specifies the type of the matrix B that defines the semi-inner + product for the operator OP. + </para> + <itemizedlist> + <listitem> + <para>'I': standard eigenvalue problem A * x = lambda * x</para> + </listitem> + <listitem> + <para> + 'G': generalized eigenvalue problem A * x = + lambda * B * x + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>N</term> + <listitem> + <para>Integer. (INPUT)</para> + <para>Dimension of the eigenproblem.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>WHICH</term> + <listitem> + <para>String of length 2. (INPUT)</para> + <para>Specifies which of the Ritz values of OP to compute.</para> + <itemizedlist> + <listitem> + <para> + 'LA' - compute the NEV largest (algebraic) + eigenvalues. + </para> + </listitem> + <listitem> + <para> + 'SA' - compute the NEV smallest (algebraic) + eigenvalues. + </para> + </listitem> + <listitem> + <para> + 'LM' - compute the NEV largest (in magnitude) + eigenvalues. + </para> + </listitem> + <listitem> + <para> + 'SM' - compute the NEV smallest (in magnitude) + eigenvalues. + </para> + </listitem> + <listitem> + <para> + '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) + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>NEV</term> + <listitem> + <para>Integer. (INPUT)</para> + <para> + Number of eigenvalues of OP to be computed. 0 < NEV < + N. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>TOL</term> + <listitem> + <para>scalar. (INPUT)</para> + <para> + 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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>RESID</term> + <listitem> + <para>Array of length N. (INPUT/OUTPUT)</para> + <para> + On INPUT: If INFO = 0, a random initial residual vector is + used, else RESID contains the initial residual vector, possibly from + a previous run. + </para> + <para>On OUTPUT: RESID contains the final residual vector.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>NCV</term> + <listitem> + <para>Integer. (INPUT)</para> + <para> + Number of columns of the matrix V (less than or equal to N). + </para> + <para> + 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). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>V</term> + <listitem> + <para>N by NCV array. (OUTPUT) </para> + <para>The NCV columns of V contain the Lanczos basis vectors.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>IPARAM</term> + <listitem> + <para>array of length 11. (INPUT/OUTPUT)</para> + <itemizedlist> + <listitem> + <para> + 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. + </para> + <itemizedlist> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para> + IPARAM(2) = LEVEC. No longer referenced. See remark 2 + below. + </para> + </listitem> + <listitem> + <para>IPARAM(3) = MXITER </para> + <para> + On INPUT: maximum number of Arnoldi update iterations + allowed. + </para> + <para> + On OUTPUT: actual number of Arnoldi update iterations + taken. + </para> + </listitem> + <listitem> + <para> + IPARAM(4) = NB: blocksize to be used in the recurrence. + The code currently works only for NB = 1. + </para> + </listitem> + <listitem> + <para> + IPARAM(5) = NCONV: number of "converged" Ritz values. This + represents the number of Ritz values that satisfy the + convergence criterion. + </para> + </listitem> + <listitem> + <para> + IPARAM(6) = IUPD No longer referenced. Implicit restarting + is ALWAYS used. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para>IPARAM(9) = NUMOP, </para> + <para>IPARAM(10) = NUMOPB, </para> + <para> + 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. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>IPNTR</term> + <listitem> + <para> + array of length 11. (OUTPUT) + </para> + <para> + Pointer to mark the starting locations in + the WORKD and WORKL arrays for matrices/vectors used by the Lanczos + iteration. + </para> + <itemizedlist> + <listitem> + <para> + IPNTR(1): pointer to the current operand vector X in + WORKD. + </para> + </listitem> + <listitem> + <para> + IPNTR(2): pointer to the current result vector Y in + WORKD. + </para> + </listitem> + <listitem> + <para> + IPNTR(3): pointer to the vector B * X in WORKD when used + in the shift-and-invert mode. + </para> + </listitem> + <listitem> + <para> + IPNTR(4): pointer to the next available location in WORKL + that is untouched by the program. + </para> + </listitem> + <listitem> + <para> + IPNTR(5): pointer to the NCV by 2 tridiagonal matrix T in + WORKL. + </para> + </listitem> + <listitem> + <para> + IPNTR(6): pointer to the NCV RITZ values array in + WORKL. + </para> + </listitem> + <listitem> + <para> + IPNTR(7): pointer to the Ritz estimates in array WORKL + associated with the Ritz values located in RITZ in WORKL. + </para> + </listitem> + <listitem> + <para> + IPNTR(11): pointer to the NP shifts in WORKL. See Remark 6 + below. + </para> + </listitem> + </itemizedlist> + <para> + Note: IPNTR(8:10) is only referenced by dseupd . See Remark + 2. + </para> + <itemizedlist> + <listitem> + <para> + IPNTR(8): pointer to the NCV RITZ values of the original + system. + </para> + </listitem> + <listitem> + <para> + IPNTR(9): pointer to the NCV corresponding error + bounds. + </para> + </listitem> + <listitem> + <para> + 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 + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>WORKD</term> + <listitem> + <para>work array of length 3 * N. (REVERSE COMMUNICATION) </para> + <para> + 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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>WORKL</term> + <listitem> + <para> + work array of length at least NCV ** 2 + 8 * NCV. + (OUTPUT/WORKSPACE) + </para> + <para> + Private (replicated) array on each PE or array allocated on + the front end. See Data Distribution Note below. add here the + parameter description. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>INFO</term> + <listitem> + <para>Integer. (INPUT/OUTPUT)</para> + <para> + If INFO = 0, a randomly initial residual vector is used, else + RESID contains the initial residual vector, possibly from a previous + run. + </para> + <para>Error flag on output.</para> + <itemizedlist> + <listitem> + <para>0: Normal exit.</para> + </listitem> + <listitem> + <para> + 1: Maximum number of iterations taken. All possible + eigenvalues of OP has been found. IPARAM(5) returns the number + of wanted converged Ritz values. + </para> + </listitem> + <listitem> + <para> + 2: No longer an informational error. Deprecated starting + with release 2 of ARPACK. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para>-1: N must be positive.</para> + </listitem> + <listitem> + <para>-2: NEV must be positive.</para> + </listitem> + <listitem> + <para> + -3: NCV must be greater than NEV and less than or equal to + N. + </para> + </listitem> + <listitem> + <para> + -4: The maximum number of Arnoldi update iterations + allowed must be greater than zero. + </para> + </listitem> + <listitem> + <para> + -5: WHICH must be one of 'LM', 'SM', 'LA', 'SA' or + 'BE'. + </para> + </listitem> + <listitem> + <para>-6: BMAT must be one of 'I' or 'G'.</para> + </listitem> + <listitem> + <para> + -7: Length of private work array WORKL is not + sufficient. + </para> + </listitem> + <listitem> + <para> + -8: Error return from trid. eigenvalue calculation; + Informatinal error from LAPACK routine dsteqr. + </para> + </listitem> + <listitem> + <para>-9: Starting vector is zero.</para> + </listitem> + <listitem> + <para>-10: IPARAM(7) must be 1, 2, 3, 4, 5.</para> + </listitem> + <listitem> + <para>-11: IPARAM(7) = 1 and BMAT = 'G' are incompatable.</para> + </listitem> + <listitem> + <para>-12: IPARAM(1) must be equal to 0 or 1.</para> + </listitem> + <listitem> + <para>-13: NEV and WHICH = 'BE' are incompatable.</para> + </listitem> + <listitem> + <para> + -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. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Description</title> + <para> + 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.<literal> + B * OP = + (OP`) * B + </literal> + . + </para> + <para> + Another way to express this condition is <literal> + < x,OPy > = + < OPx,y > where <z,w > = z`Bw + </literal> + . + </para> + <para> + In the standard eigenproblem B is the identity matrix. ( A` denotes + transpose of A) + </para> + <para> + The computed approximate eigenvalues are called Ritz values and the + corresponding approximate eigenvectors are called Ritz vectors. + </para> + <para> + dsaupd is usually called iteratively to solve one of the following + problems: + </para> + <itemizedlist> + <listitem> + <para> + Mode 1: A * x = lambda * x, A symmetric ===> OP = A and B = + I. + </para> + </listitem> + <listitem> + <para> + 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) + </para> + </listitem> + <listitem> + <para> + 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 + </para> + </listitem> + <listitem> + <para> + 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 + </para> + </listitem> + <listitem> + <para> + 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 + </para> + </listitem> + </itemizedlist> + <para> + 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 <literal> + [A - sigma * M] * w = v or M * w = + v + </literal> + , + </para> + <para> + 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. + </para> + </refsection> + <refsection> + <title>Remarks</title> + <para> + 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 . + </para> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 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). + </para> + </refsection> + <refsection> + <title>Example</title> + <programlisting role="example"> + <![CDATA[ +// The following sets dimensions for this problem. +nx = 10; +nev = 3; +ncv = 6; +bmat = 'I'; +which = 'LM'; +// Local Arrays +iparam = zeros(11, 1); +ipntr = zeros(14, 1); +_select = zeros(ncv, 1); +d = zeros(nev, 1); +z = zeros(nx, nev); +resid = zeros(nx, 1); +v = zeros(nx, ncv); +workd = zeros(3 * nx, 1); +workl = zeros(ncv * ncv + 8 * ncv, 1); +// Build the symmetric test matrix +A = diag(10 * ones(nx,1)); +A(1:$-1,2:$) = A(1:$-1,2:$) + diag(6 * ones(nx-1,1)); +A(2:$,1:$-1) = A(2:$,1:$-1) + diag(6 * ones(nx-1,1)); +tol = 0; +ido = 0; +ishfts = 1; +maxitr = 300; +mode1 = 1; +iparam(1) = ishfts; +iparam(3) = maxitr; +iparam(7) = mode1; +sigma = 0; // the real part of the shift +info_dsaupd = 0; +// M A I N L O O P (Reverse communication) +while(ido <> 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); +]]> + </programlisting> + </refsection> + <refsection role="see also"> + <title>See Also</title> + <simplelist type="inline"> + <member> + <link linkend="dnaupd">dnaupd</link> + </member> + <member> + <link linkend="dseupd">dseupd</link> + </member> + </simplelist> + </refsection> + <refsection> + <title>Bibliography</title> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 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). + </para> + </refsection> + <refsection> + <title>Used Functions</title> + <para>Based on ARPACK routine dsaupd</para> + </refsection> + <refsection> + <title>履歴</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revremark> + 関数は廃止され,<link linkend="eigs">eigs</link>に代替されました. + </revremark> + </revision> + </revhistory> + </refsection> +</refentry> 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 @@ +<?xml version="1.0" encoding="UTF-8"?> +<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="dseupd" xml:lang="ja"> + <refnamediv> + <refname>dseupd</refname> + <refpurpose> + 暗黙のうちに再開されるArnoldi反復へのインターフェイスで, + A * z = lambda * B * z の固有値を収束的近似により計算します. + <emphasis role="bold"> + この関数は廃止されました. <link linkend="eigs">eigs</link>を使用してください + </emphasis> + </refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>Calling Sequence</title> + <synopsis> + [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) + </synopsis> + </refsynopsisdiv> + <refsection> + <title>Arguments</title> + <variablelist> + <varlistentry> + <term>RVEC</term> + <listitem> + <para>Integer. (INPUT) </para> + <para> + Specifies whether Ritz vectors corresponding to the Ritz value + approximations to the eigenproblem A * z = lambda * B * z are + computed. + </para> + <itemizedlist> + <listitem> + <para>RVEC = 0 Compute Ritz values only.</para> + </listitem> + <listitem> + <para>RVEC = 1 Compute Ritz vectors.</para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>HOWMNY</term> + <listitem> + <para>Character*1. (INPUT) </para> + <para> + Specifies how many Ritz vectors are wanted and the form of Z + the matrix of Ritz vectors. See remark 1 below. + </para> + <itemizedlist> + <listitem> + <para>'A': compute NEV Ritz vectors;</para> + </listitem> + <listitem> + <para> + 'S': compute some of the Ritz vectors, specified by the + integer array SELECT. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>SELECT</term> + <listitem> + <para>Integer array of dimension NCV. (INPUT/WORKSPACE) </para> + <para> + 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. + </para> + <para> + If HOWMANY = 'A' , SELECT is used as a workspace for + reordering the Ritz values. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>D</term> + <listitem> + <para>Double precision array of dimension NEV. (OUTPUT) </para> + <para> + On exit, D contains the Ritz value approximations to the + eigenvalues of A * z = lambda * B * z. The values are returned in + ascending order. + </para> + <para> + 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. + </para> + <para> + If IPARAM(7) = 1, 2 then the Ritz values of OP are the same as + the those of A * z = lambda * B * z. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Z</term> + <listitem> + <para>Double precision N by NEV array.</para> + <para> + 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. + </para> + <para>If RVEC = 0 then Z is not referenced. </para> + <para> + NOTE: The array Z may be set equal to first NEV columns of the + Arnoldi/Lanczos basis array V computed by DSAUPD . + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>SIGMA</term> + <listitem> + <para>Double precision (INPUT) </para> + <para> + If IPARAM(7) = 3, 4, 5 represents the shift. Not referenced if + IPARAM(7) = 1 or 2. + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + 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 . + </para> + <para> + These arguments MUST NOT BE MODIFIED between the last call to + DSAUPD and the call to DSEUPD. + </para> + <para> + Two of these parameters (WORKL, INFO) are also output + parameters. + </para> + <variablelist> + <varlistentry> + <term>WORKL</term> + <listitem> + <para> + Double precision work array of length LWORKL. + (OUTPUT/WORKSPACE) + </para> + <para> + WORKL(1:4*ncv) contains information obtained in dsaupd. They + are not changed by dseupd. + </para> + <para> + WORKL(4*ncv+1:ncv*ncv+8*ncv) holds the untransformed Ritz + values, the computed error estimates, and the associated eigenvector + matrix of H. + </para> + <para> + Note: IPNTR(8:10) contains the pointer into WORKL for + addresses of the above information computed by dseupd . + </para> + <itemizedlist> + <listitem> + <para> + IPNTR(8): pointer to the NCV RITZ values of the original + system. + </para> + </listitem> + <listitem> + <para> + IPNTR(9): pointer to the NCV corresponding error bounds. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>INFO</term> + <listitem> + <para>Integer. (OUTPUT) </para> + <para>Error flag on output.</para> + <itemizedlist> + <listitem> + <para>0: Normal exit.</para> + </listitem> + <listitem> + <para>-1: N must be positive.</para> + </listitem> + <listitem> + <para>-2: NEV must be positive.</para> + </listitem> + <listitem> + <para> + -3: NCV must be greater than NEV and less than or equal to + N. + </para> + </listitem> + <listitem> + <para> + -5: WHICH must be one of 'LM', 'SM', 'LA', 'SA' or + 'BE'. + </para> + </listitem> + <listitem> + <para>-6: BMAT must be one of 'I' or 'G'.</para> + </listitem> + <listitem> + <para> + -7: Length of private work WORKL array is not + sufficient. + </para> + </listitem> + <listitem> + <para> + -8: Error return from trid. eigenvalue calculation; + Information error from LAPACK routine dsteqr. + </para> + </listitem> + <listitem> + <para>-9: Starting vector is zero.</para> + </listitem> + <listitem> + <para>-10: IPARAM(7) must be 1, 2, 3, 4, 5.</para> + </listitem> + <listitem> + <para>-11: IPARAM(7) = 1 and BMAT = 'G' are incompatible.</para> + </listitem> + <listitem> + <para>-12: NEV and WHICH = 'BE' are incompatible.</para> + </listitem> + <listitem> + <para> + -14: DSAUPD did not find any eigenvalues to sufficient + accuracy. + </para> + </listitem> + <listitem> + <para>-15: HOWMNY must be one of 'A' or 'S' if RVEC = 1.</para> + </listitem> + <listitem> + <para>-16: HOWMNY = 'S' not yet implemented.</para> + </listitem> + <listitem> + <para> + -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. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Description</title> + <para> + This subroutine returns the converged approximations to eigenvalues + of A * z = lambda * B * z and (optionally): + </para> + <orderedlist> + <listitem> + <para>the corresponding approximate eigenvectors,</para> + </listitem> + <listitem> + <para> + an orthonormal (Lanczos) basis for the associated approximate + invariant subspace, + </para> + </listitem> + <listitem> + <para>Both. </para> + </listitem> + </orderedlist> + <para> + 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). + </para> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + The computed orthonormal basis for the invariant subspace + corresponding to these Ritz values is referred to as a Lanczos basis. + </para> + <para> + 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. + </para> + <para> + The approximate eigenvalues of the original problem are returned in + ascending algebraic order. + </para> + <para> + 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. + </para> + </refsection> + <refsection> + <title>Remarks</title> + <para> + 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. + </para> + </refsection> + <refsection> + <title>Example</title> + <programlisting role="example"> + <![CDATA[ +// The following sets dimensions for this problem. +nx = 10; +nev = 3; +ncv = 6; +bmat = 'I'; +which = 'LM'; +// Local Arrays +iparam = zeros(11, 1); +ipntr = zeros(14, 1); +_select = zeros(ncv, 1); +d = zeros(nev, 1); +z = zeros(nx, nev); +resid = zeros(nx, 1); +v = zeros(nx, ncv); +workd = zeros(3 * nx, 1); +workl = zeros(ncv * ncv + 8 * ncv, 1); +// Build the symmetric test matrix +A = diag(10 * ones(nx,1)); +A(1:$-1,2:$) = A(1:$-1,2:$) + diag(6 * ones(nx-1,1)); +A(2:$,1:$-1) = A(2:$,1:$-1) + diag(6 * ones(nx-1,1)); +tol = 0; +ido = 0; +ishfts = 1; +maxitr = 300; +mode1 = 1; +iparam(1) = ishfts; +iparam(3) = maxitr; +iparam(7) = mode1; +sigma = 0; // the real part of the shift +info_dsaupd = 0; +// M A I N L O O P (Reverse communication) +while(ido <> 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); +]]> + </programlisting> + </refsection> + <refsection role="see also"> + <title>See Also</title> + <simplelist type="inline"> + <member> + <link linkend="dsaupd">dsaupd</link> + </member> + <member> + <link linkend="dneupd">dneupd</link> + </member> + </simplelist> + </refsection> + <refsection> + <title>Bibliography</title> + <para> + 1. D.C. Sorensen, "Implicit Application of Polynomial Filters in + k-Step Arnoldi Method", SIAM J. Matr. Anal. Apps., 13 (1992), pp + 357-385. + </para> + <para> + 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. + </para> + <para> + 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). + </para> + </refsection> + <refsection> + <title>Used Functions</title> + <para>Based on ARPACK routine dseupd</para> + </refsection> + <refsection> + <title>履歴</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revremark> + 関数は廃止され,<link linkend="eigs">eigs</link>に代替されました. + </revremark> + </revision> + </revhistory> + </refsection> +</refentry> 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 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab + * Copyright (C) 2012 - Scilab Enterprises - Adeline CARNIS + * + * 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 + * + --> +<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="eigs" xml:lang="ja"> + <refnamediv> + <refname>eigs</refname> + <refpurpose> + 行列の最大固有値と固有ベクトルを計算 + </refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>呼び出し手順</title> + <synopsis> + 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]]]]) + </synopsis> + </refsynopsisdiv> + <refsection> + <title>引数</title> + <variablelist> + <varlistentry> + <term>A </term> + <listitem> + <para>通常または疎, 実数または複素数, 対称または非対称正方行列</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Af </term> + <listitem> + <para>関数</para> + </listitem> + </varlistentry> + <varlistentry> + <term>n </term> + <listitem> + <para> + スカラー, Aが関数の場合のみ <literal>A</literal> 定義 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>B</term> + <listitem> + <para> + <literal> A</literal>と同じ次元の + 疎, 実数または複素数, 正方行列 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>k</term> + <listitem> + <para>整数, 計算する固有値の数</para> + </listitem> + </varlistentry> + <varlistentry> + <term>sigma</term> + <listitem> + <para>実スカラーまたは長さ2の文字列</para> + </listitem> + </varlistentry> + <varlistentry> + <term>opts</term> + <listitem> + <para>構造体</para> + </listitem> + </varlistentry> + <varlistentry> + <term>d</term> + <listitem> + <para>実数または複素数の固有値ベクトルまたは対角行列 (対角項に固有値)</para> + </listitem> + </varlistentry> + <varlistentry> + <term>v</term> + <listitem> + <para> + 実数または複素数の固有ベクトル行列 + </para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>説明</title> + <para> + eigs関数の目的は,疎で大きな行列の最大固有値を計算することです. + </para> + <variablelist> + <varlistentry> + <term>d = eigs(A) または d = eigs(Af, n)</term> + <listitem> + <para> + は,固有値問題<literal>A * v = lambda * v</literal>を解きます. + このコールは,大きさが最大の6個の固有値を有する + ベクトル <literal>d</literal>を返します. + <literal>A</literal> は正方行列で, + 対称または非対称, 実数または複素数, 通常または複素数 + とすることができます. + </para> + <para> + <literal>A</literal> は関数<literal>Af</literal>で + 表すことも可能です.この場合, + ベクトル引数の長さを指定するスカラー<literal>n</literal>を + 定義する必要があります. + この関数は,以下のヘッダを有する必要があります: + </para> + <programlisting role="no-scilab-exec"> + <![CDATA[ +function y = A ( x ) + ]]> + </programlisting> + <para> + この関数 <literal>Af</literal> は以下の4つの式の1つを返す必要があります: + <itemizedlist> + <listitem> + <term>A * x</term> + <para> sigmaが指定されないか文字列が'SM'以外の場合.</para> + </listitem> + <listitem> + <term>A \ x</term> + <para>sigmaが0または'SM'の場合.</para> + </listitem> + <listitem> + <term>(A - sigma * I) \ x</term> + <para>標準固有値問題の場合, ただし I は単位行列.</para> + </listitem> + <listitem> + <term>(A - sigma * B) \ x</term> + <para> 一般化固有値問題の場合.</para> + </listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>[d, v] = eigs(A) or [d, v] = eigs(Af, n)</term> + <listitem> + <para> + は,6個の最大固有値を対角項に有する対角行列 <literal>d</literal> を返します. + <literal>v</literal> は n行6列の行列で, + その列は返された固有値に対応する6個の固有値ベクトルです. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>d = eigs(A, B)</term> + <listitem> + <para> + は,正定行列<literal>B</literal>を指定して, + 一般化固有値問題 <literal>A * v = lambda * B * v </literal> + を解きます. + </para> + <itemizedlist> + <listitem> + <para> + <literal>B</literal> が指定されない場合, + <literal>B = []</literal> が使用されます. + </para> + </listitem> + <listitem> + <para> + <literal>B</literal> が指定された場合, + <literal>B</literal> はAと同じ大きさとする必要があります. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>d = eigs(A, B, k)</term> + <listitem> + <para> + は,<literal>k</literal>個の固有値をベクトル<literal>d</literal>に返します. + <literal>k</literal> が指定されない場合, + <literal>k = min(n, 6)</literal>, ただし, nはAの行数となります. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>d = eigs(A, B, k, sigma)</term> + <listitem> + <para> + は,<literal>sigma</literal>で定義された<literal>k</literal>個の固有値を + ベクトル<literal>d</literal>に返します. + <literal>sigma</literal> は,0を含む実数または複素数,または文字列 + とすることができます. + sigma が長さ2の文字列の場合, 以下の値のどれかとします : + </para> + <itemizedlist> + <listitem> + <para> + <literal>'LM'</literal> は,大きさが最大の<varname>k</varname>個の + 固有値を計算します(デフォルト). + </para> + </listitem> + <listitem> + <para> + <literal>'SM'</literal> は,大きさが最小の<varname>k</varname>個の + 固有値を計算します(sigma = 0 と同じ). + </para> + </listitem> + <listitem> + <para> + <literal>'LA'</literal> は,実対称問題のみに適用され, + <varname>k</varname>個の代数的最大固有値を計算します. + </para> + </listitem> + <listitem> + <para> + <literal>'SA'</literal> は,実対称問題のみに適用され, + <varname>k</varname>個の代数的最小固有値を計算します. + </para> + </listitem> + <listitem> + <para> + <literal>'BE'</literal> は,実対称問題のみに適用され, + スペクトラムの各端から半分づつ,<varname>k</varname>個の固有値を計算します. + </para> + </listitem> + <listitem> + <para> + <literal>'LR'</literal> は,実非対称または複素問題のみに適用され, + <varname>k</varname>個の実部最大の固有値を計算します. + </para> + </listitem> + <listitem> + <para> + <literal>'SR'</literal> は,実非対称または複素問題のみに適用され, + <varname>k</varname>個の実部最小の固有値を計算します. + </para> + </listitem> + <listitem> + <para> + <literal>'LI'</literal> は,実非対称または複素問題のみに適用され, + <varname>k</varname>個の虚部最大の固有値を計算します. + </para> + </listitem> + <listitem> + <para> + <literal>'SI'</literal> は,実非対称または複素問題のみに適用され, + <varname>k</varname>個の虚部最小の固有値を計算します. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>d = eigs(A, B, k, sigma, opts)</term> + <listitem> + <para> + <literal> opts </literal> 構造体が指定された場合, + <literal>k</literal> 個の固有値を計算する際に + 異なるオプションを使用できます: + </para> + <itemizedlist> + <listitem> + <para> + <term>tol</term> + <para> + 所要の収束閾値. デフォルトで, <literal>tol = %eps</literal>. + </para> + </para> + </listitem> + <listitem> + <para> + <term>maxiter</term> + <para> + 最大反復回数. デフォルトで, <literal>maxiter = 300</literal>. + </para> + </para> + </listitem> + <listitem> + <para> + <term>ncv</term> + <para> + 使用するLanzcos基底ベクトルの数. + 実非対称問題の場合, <literal>ncv</literal>の値は + <literal>2 * k + 1 </literal>以上とする必要があり, + デフォルトで <literal>ncv = min(max(2 * k + 1, 20), nA) </literal>です. + 実対称または複素数問題の場合,<literal>ncv</literal>は + <literal>2 * k </literal>以上とする必要があり, + デフォルトで<literal> ncv = min(max(2 * k, 20), nA) </literal> + です.ただし,<literal> nA = size(A, 2) </literal>. + </para> + </para> + </listitem> + <listitem> + <para> + <term>resid</term> + <para> + 初期残差ベクトルを有する開始ベクトルで, + 前回実行時の値を使用することもできます. + デフォルトで,<literal>resid</literal> はランダムな + 初期値ベクトルです. + </para> + </para> + </listitem> + <listitem> + <para> + <term>cholB</term> + <para> + <literal>B</literal>ではなく + <literal>chol(B)</literal>を指定します. + デフォルトで + , <literal>cholB</literal> は %f です. + </para> + </para> + </listitem> + <listitem> + <para> + <term>isreal</term> + <para> + <literal>Af</literal> が指定された場合, + <literal>isreal</literal> を定義できます. + デフォルトで, <literal>isreal</literal> は %t です. + この引数は,<literal>A</literal>が行列の場合, + 指定する必要がありません. + </para> + </para> + </listitem> + <listitem> + <para> + <term>issym</term> + <para> + <literal>Af</literal> が指定された場合, + <literal>issym</literal> を定義できます. + デフォルトで <literal>issym</literal> は %f です. + この引数は,<literal>A</literal>が行列の場合, + 指定する必要がありません. + </para> + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>参考文献</title> + <para> + この関数はR. Lehoucq, K. Maschhoff, D. Sorensen, および C. Yang.により書かれた + ARPACKパッケージに基づいています. + </para> + <itemizedlist> + <listitem> + <para>実対称問題用のDSAUPD および DSEUPD ルーチン,</para> + </listitem> + <listitem> + <para>実非対称行列用のDNAUPD および DNEUPD ルーチン.</para> + </listitem> + <listitem> + <para>複素問題用のZNAUPD および ZNEUPD.</para> + </listitem> + </itemizedlist> + </refsection> + <refsection> + <title>実対称問題の例</title> + <programlisting role="example"> + <![CDATA[ +clear opts +A = diag(10*ones(10,1)); +A(1:$-1,2:$) = A(1:$-1,2:$) + diag(6*ones(9,1)); +A(2:$,1:$-1) = A(2:$,1:$-1) + diag(6*ones(9,1)); +B = eye(10,10); +k = 8; +sigma = 'SM'; +opts.cholB = %t; +d = eigs(A) +[d, v] = eigs(A) +d = eigs(A, B, k, sigma) +[d, v] = eigs(A, B, k, sigma) +d = eigs(A, B, k, sigma, opts) +[d, v] = eigs(A, B, k, sigma, opts) +// 疎行列 +AS = sparse(A); +BS = sparse(B); +d = eigs(AS) +[d, v] = eigs(AS) +d = eigs(AS, BS, k, sigma) +[d, v] = eigs(AS, BS, k, sigma) +d = eigs(AS, BS, k, sigma, opts) +[d, v] = eigs(AS, BS, k, sigma, opts) +// 関数 +clear opts +function y = fn(x) + y = A * x; +endfunction +opts.isreal = %t; +opts.issym = %t; +d = eigs(fn, 10, [], k, 'LM', opts) +function y = fn(x) + y = A \ x; +endfunction +d = eigs(fn, 10, [], k, 'SM', opts) +function y = fn(x) + y = (A - 4 * eye(10,10)) \ x; +endfunction +d = eigs(fn, 10, [], k, 4, opts) + ]]> + </programlisting> + </refsection> + <refsection> + <title>実非対称問題の例</title> + <programlisting role="example"> + <![CDATA[ + clear opts + A = diag(10*ones(10,1)); + A(1:$-1,2:$) = A(1:$-1,2:$) + diag(6*ones(9,1)); + A(2:$,1:$-1) = A(2:$,1:$-1) + diag(-6*ones(9,1)); + B = eye(10,10); + k = 8; + sigma = 'SM'; + opts.cholB = %t; + d = eigs(A) +[d, v] = eigs(A) + d = eigs(A, B, k, sigma) + [d, v] = eigs(A, B, k, sigma) + d = eigs(A, B, k, sigma, opts) + [d, v] = eigs(A, B, k, sigma, opts) +// 疎行列 + AS = sparse(A); + BS = sparse(B); +d = eigs(AS) +[d, v] = eigs(AS) + d = eigs(AS, BS, k, sigma) + [d, v] = eigs(AS, BS, k, sigma) + d = eigs(AS, BS, k, sigma, opts) + [d, v] = eigs(AS, BS, k, sigma, opts) + // 関数 +clear opts +function y = fn(x) + y = A * x; +endfunction +opts.isreal = %t; +opts.issym = %f; +d = eigs(fn, 10, [], k, 'LM', opts) +function y = fn(x) + y = A \ x; +endfunction +d = eigs(fn, 10, [], k, 'SM', opts) +function y = fn(x) + y = (A - 4 * eye(10,10)) \ x; +endfunction +d = eigs(fn, 10, [], k, 4, opts) + ]]> + </programlisting> + </refsection> + <refsection> + <title>複素問題の例</title> + <programlisting role="example"> + <![CDATA[ + clear opts + A = diag(10*ones(10,1) + %i * ones(10,1)); + A(1:$-1,2:$) = A(1:$-1,2:$) + diag(6*ones(9,1)); + A(2:$,1:$-1) = A(2:$,1:$-1) + diag(-6*ones(9,1)); + B = eye(10,10); + k = 8; + sigma = 'LM'; + opts.cholB = %t; + d = eigs(A) +[d, v] = eigs(A) + d = eigs(A, B, k, sigma) + [d, v] = eigs(A, B, k, sigma) + d = eigs(A, B, k, sigma, opts) + [d, v] = eigs(A, B, k, sigma, opts) + // 疎行列 + AS = sparse(A); + BS = sparse(B); + d = eigs(AS) +[d, v] = eigs(AS) + d = eigs(AS, BS, k, sigma) + [d, v] = eigs(AS, BS, k, sigma) + d = eigs(AS, BS, k, sigma, opts) + [d, v] = eigs(AS, BS, k, sigma, opts) + // 関数 +clear opts +function y = fn(x) + y = A * x; +endfunction +opts.isreal = %f; +opts.issym = %f; +d = eigs(fn, 10, [], k, 'LM', opts) +function y = fn(x) + y = A \ x; +endfunction +d = eigs(fn, 10, [], k, 'SM', opts) +function y = fn(x) + y = (A - 4 * eye(10,10)) \ x; +endfunction +d = eigs(fn, 10, [], k, 4, opts) + ]]> + </programlisting> + </refsection> + <refsection role="see also"> + <title>参照</title> + <simplelist type="inline"> + <member> + <link linkend="spec">spec</link> + </member> + </simplelist> + </refsection> + <refsection> + <title>履歴</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revremark> + 関数が導入されました. + dnaupd, dneupd, dsaupd, dseupd, znaupd および zneupdは廃止されました. + </revremark> + </revision> + </revhistory> + </refsection> +</refentry> 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 @@ +<?xml version="1.0" encoding="UTF-8"?> +<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="znaupd" xml:lang="ja"> + <refnamediv> + <refname>znaupd</refname> + <refpurpose> + 暗黙のうちに再開されるArnoldi反復へのインターフェイスで, + エルミート準正定実行列Bにより定義される準内積に関する + 複素線形演算子 OP の小数の固有値/ベクトルの組を近似的に計算します. + <emphasis role="bold"> + この関数は廃止されました. <link linkend="eigs">eigs</link>を使用してください + </emphasis> + </refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>Calling Sequence</title> + <synopsis>[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)</synopsis> + </refsynopsisdiv> + <refsection> + <title>Arguments</title> + <variablelist> + <varlistentry> + <term>IDO</term> + <listitem> + <para>Integer. (INPUT/OUTPUT) </para> + <para> + 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. + </para> + <para> + The operand is given in WORKD(IPNTR(1)), the result must be + put in WORKD(IPNTR(2)). + </para> + <itemizedlist> + <listitem> + <para> + IDO = 0: first call to the reverse communication interface + </para> + </listitem> + <listitem> + <para> + 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. + </para> + <para> + This is for the initialization phase to force the starting + vector into the range of OP. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + IDO = 3: compute and return the shifts in the first NP + locations of WORKL. + </para> + </listitem> + <listitem> + <para>IDO = 99: done </para> + </listitem> + </itemizedlist> + <para> + 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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>BMAT</term> + <listitem> + <para>Character. (INPUT) </para> + <para> + specifies the type of the matrix B that defines the + semi-inner product for the operator OP. + </para> + <itemizedlist> + <listitem> + <para>'I': standard eigenvalue problem A * x = lambda * x</para> + </listitem> + <listitem> + <para> + 'G': generalized eigenvalue problem A * x = + lambda * M * x + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>N</term> + <listitem> + <para>Integer. (INPUT) </para> + <para>Dimension of the eigenproblem.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>WHICH</term> + <listitem> + <para>string of length 2. (INPUT) </para> + <itemizedlist> + <listitem> + <para> + 'LM': want the NEV eigenvalues of largest + magnitude. + </para> + </listitem> + <listitem> + <para> + 'SM': want the NEV eigenvalues of smallest + magnitude. + </para> + </listitem> + <listitem> + <para> + 'LR': want the NEV eigenvalues of largest real + part. + </para> + </listitem> + <listitem> + <para> + 'SR': want the NEV eigenvalues of smallest real part. + </para> + </listitem> + <listitem> + <para> + 'LI': want the NEV eigenvalues of largest imaginary + part. + </para> + </listitem> + <listitem> + <para> + 'SI': want the NEV eigenvalues of smallest imaginary + part. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>NEV</term> + <listitem> + <para>Integer. (INPUT) </para> + <para> + Number of eigenvalues of OP to be computed. 0 < NEV < + N - 1. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>TOL</term> + <listitem> + <para>Double precision scalar. (INPUT) </para> + <para> + 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). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>RESID</term> + <listitem> + <para>Complex*16 array of length N. (INPUT/OUTPUT) </para> + <para> + 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. + </para> + <para>On OUTPUT: RESID contains the final residual vector.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>NCV</term> + <listitem> + <para>Integer. (INPUT) </para> + <para> + Number of columns of the matrix V. NCV must satisfy the two + inequalities 2 <= NCV - NEV and NCV <= N. + </para> + <para> + 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.) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>V</term> + <listitem> + <para>Complex*16 array N by NCV. (OUTPUT) </para> + <para>Contains the final set of Arnoldi basis vectors.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>IPARAM</term> + <listitem> + <para>Integer array of length 11. (INPUT/OUTPUT) </para> + <itemizedlist> + <listitem> + <para> + 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. + </para> + <itemizedlist> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + ISHIFT = 2: other choice of internal shift to be + defined. + </para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para>IPARAM(2) = No longer referenced</para> + </listitem> + <listitem> + <para>IPARAM(3) = MXITER </para> + <para> + On INPUT: maximum number of Arnoldi update iterations + allowed. + </para> + <para> + On OUTPUT: actual number of Arnoldi update iterations + taken. + </para> + </listitem> + <listitem> + <para> + IPARAM(4) = NB: blocksize to be used in the recurrence. + The code currently works only for NB = 1. + </para> + </listitem> + <listitem> + <para> + IPARAM(5) = NCONV: number of "converged" Ritz values. This + represents the number of Ritz values that satisfy the + convergence criterion. + </para> + </listitem> + <listitem> + <para> + IPARAM(6) = IUPD No longer referenced. Implicit restarting + is ALWAYS used. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para>IPARAM(9) = NUMOP, </para> + <para>IPARAM(10) = NUMOPB, </para> + <para> + 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. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>IPNTR</term> + <listitem> + <para>Integer array of length 14. (OUTPUT) </para> + <para> + Pointer to mark the starting locations in the WORKD and WORKL + arrays for matrices/vectors used by the Arnoldi iteration. + </para> + <itemizedlist> + <listitem> + <para> + IPNTR(1): pointer to the current operand vector X in + WORKD. + </para> + </listitem> + <listitem> + <para> + IPNTR(2): pointer to the current result vector Y in + WORKD. + </para> + </listitem> + <listitem> + <para> + IPNTR(3): pointer to the vector B * X in WORKD when used + in the shift-and-invert mode. + </para> + </listitem> + <listitem> + <para> + IPNTR(4): pointer to the next available location in WORKL + that is untouched by the program. + </para> + </listitem> + <listitem> + <para> + IPNTR(5): pointer to the NCV by NCV upper Hessenberg + matrix H in WORKL. + </para> + </listitem> + <listitem> + <para>IPNTR(6): pointer to the ritz value array RITZ </para> + </listitem> + <listitem> + <para> + IPNTR(7): pointer to the (projected) ritz vector array Q + </para> + </listitem> + <listitem> + <para> + IPNTR(8): pointer to the error BOUNDS array in WORKL. + </para> + </listitem> + <listitem> + <para> + IPNTR(14): pointer to the NP shifts in WORKL. See Remark 5 + below. + </para> + </listitem> + </itemizedlist> + <para> + Note: IPNTR(9:13) is only referenced by zneupd. See Remark 2 + below. + </para> + <itemizedlist> + <listitem> + <para> + IPNTR(9): pointer to the NCV RITZ values of the original + system. + </para> + </listitem> + <listitem> + <para>IPNTR(10): Not Used </para> + </listitem> + <listitem> + <para> + IPNTR(11): pointer to the NCV corresponding error + bounds. + </para> + </listitem> + <listitem> + <para> + IPNTR(12): pointer to the NCV by NCV upper triangular + Schur matrix for H. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>WORKD</term> + <listitem> + <para> + Complex*16 work array of length 3 * N. (REVERSE COMMUNICATION) + </para> + <para> + Distributed array to be used in the basic Arnoldi iteration + for reverse communication. + </para> + <para> + The user should not use WORKD as temporary workspace during + the iteration !!!!!!!!!! + </para> + <para>See Data Distribution Note below.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>WORKL</term> + <listitem> + <para> + Complex*16 work array of length 3 * NCV ** 2 + 5 * NCV. (OUTPUT/WORKSPACE) + </para> + <para> + Private (replicated) array on each PE or array allocated on + the front end. See Data Distribution Note below. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>RWORK</term> + <listitem> + <para> + Double precision work array of length NCV (WORKSPACE) Private + (replicated) array on each PE or array allocated on the front + end. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>INFO</term> + <listitem> + <para>Integer. (INPUT/OUTPUT) </para> + <para> + If INFO == 0, a randomly initial residual vector is used. + </para> + <para> + If INFO ~= 0, RESID contains the initial residual vector, + possibly from a previous run. + </para> + <para>Error flag on output.</para> + <itemizedlist> + <listitem> + <para>0: Normal exit.</para> + </listitem> + <listitem> + <para> + 1: Maximum number of iterations taken. All possible + eigenvalues of OP has been found. IPARAM(5) returns the number + of wanted converged Ritz values. + </para> + </listitem> + <listitem> + <para> + 2: No longer an informational error. Deprecated starting + with release 2 of ARPACK. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para>-1: N must be positive.</para> + </listitem> + <listitem> + <para>-2: NEV must be positive.</para> + </listitem> + <listitem> + <para>-3: NCV-NEV >= 1 and less than or equal to N.</para> + </listitem> + <listitem> + <para> + -4: The maximum number of Arnoldi update iteration must be + greater than zero. + </para> + </listitem> + <listitem> + <para> + -5: WHICH must be one of 'LM', 'SM', 'LR', 'SR', 'LI', + 'SI'. + </para> + </listitem> + <listitem> + <para>-6: BMAT must be one of 'I' or 'G'.</para> + </listitem> + <listitem> + <para>-7: Length of private work array is not sufficient.</para> + </listitem> + <listitem> + <para> + -8: Error return from LAPACK eigenvalue + calculation. + </para> + </listitem> + <listitem> + <para>-9: Starting vector is zero.</para> + </listitem> + <listitem> + <para>-10: IPARAM(7) must be 1, 2, 3.</para> + </listitem> + <listitem> + <para>-11: IPARAM(7) = 1 and BMAT = 'G' are incompatible.</para> + </listitem> + <listitem> + <para>-12: IPARAM(1) must be equal to 0 or 1.</para> + </listitem> + <listitem> + <para> + -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. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Description</title> + <para> + 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. + </para> + <para> + NOTE: if both OP and B are real, then dsaupd or dnaupd should be + used. + </para> + <para> + 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: + </para> + <itemizedlist> + <listitem> + <para>Mode 1: A * x = lambda * x. </para> + <para>===> OP = A and B = I.</para> + </listitem> + <listitem> + <para>Mode 2: A * x = lambda * M * x, M hermitian positive definite </para> + <para>===> OP = inv[M] * A and B = M. </para> + <para>===> (If M can be factored see remark 3 below) </para> + </listitem> + <listitem> + <para>Mode 3: A * x = lambda * M * x, M hermitian semi-definite </para> + <para>===> OP = inv[A - sigma * M] * M and B = M. </para> + <para> + ===> shift-and-invert mode If OP * x = amu * x, then lambda = + sigma + 1/amu. + </para> + </listitem> + </itemizedlist> + <para> + 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 + </para> + <para>[A - sigma * M] * w = v or M * w = v, </para> + <para> + 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. + </para> + </refsection> + <refsection> + <title>Remarks</title> + <orderedlist> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + <listitem> + <para> + When IPARAM(1) = 0, and IDO = 3, the user needs to provide the + NP = IPARAM(8) complex shifts in locations + </para> + <para> + WORKL(IPNTR(14)), WORKL(IPNTR(14)+1), ... , WORKL(IPNTR(14)+NP). + </para> + <para> + 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 + </para> + <para> + WORKL(IPNTR(8)), WORKL(IPNTR(8)+1), ... , + WORKL(IPNTR(8)+NCV-1). + </para> + </listitem> + </orderedlist> + </refsection> + <refsection> + <title>Example</title> + <programlisting role="example"> + <![CDATA[ +// The following sets dimensions for this problem. +nx = 10; +nev = 3; +ncv = 6; +bmat = 'I'; +which = 'LM'; +// Local Arrays +iparam = zeros(11, 1); +ipntr = zeros(14, 1); +_select = zeros(ncv, 1); +d = zeros(nev + 1, 1) + 0 * %i; +z = zeros(nx, nev) + 0* %i; +resid = zeros(nx, 1) + 0 * %i; +v = zeros(nx, ncv) + 0 * %i; +workd = zeros(3 * nx, 1) + 0 * %i; +workev = zeros(2 * ncv, 1) + 0 * %i; +rwork = zeros(ncv, 1); +workl = zeros(3 * ncv * ncv + 5 *ncv, 1) + 0 * %i; +// Build the complex test matrix +A = diag(10 * ones(nx,1) + %i * ones(nx,1)); +A(1:$-1,2:$) = A(1:$-1,2:$) + diag(6 * ones(nx - 1,1)); +A(2:$,1:$-1) = A(2:$,1:$-1) + diag(-6 * ones(nx - 1,1)); +tol = 0; +ido = 0; +ishfts = 1; +maxitr = 300; +mode1 = 1; +iparam(1) = ishfts; +iparam(3) = maxitr; +iparam(7) = mode1; +sigma = complex(0); +info_znaupd = 0; +// M A I N L O O P (Reverse communication) +while(ido <> 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); +]]> + </programlisting> + </refsection> + <refsection role="see also"> + <title>See Also</title> + <simplelist type="inline"> + <member> + <link linkend="dnaupd">dnaupd</link> + </member> + <member> + <link linkend="dnaupd">dneupd</link> + </member> + <member> + <link linkend="dnaupd">zneupd</link> + </member> + </simplelist> + </refsection> + <refsection> + <title>Bibliography</title> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 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). + </para> + </refsection> + <refsection> + <title>Used Functions</title> + <para>Based on ARPACK routine znaupd</para> + </refsection> + <refsection> + <title>履歴</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revremark> + 関数は廃止され,<link linkend="eigs">eigs</link>に代替されました. + </revremark> + </revision> + </revhistory> + </refsection> +</refentry> 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 @@ +<?xml version="1.0" encoding="UTF-8"?> +<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="zneupd" xml:lang="ja"> + <refnamediv> + <refname>zneupd</refname> + <refpurpose> + 暗黙のうちに再開されるArnoldi反復へのインターフェイスで, + A * z = lambda * B * z の固有値を収束的近似により計算します. + <emphasis role="bold"> + この関数は廃止されました. <link linkend="eigs">eigs</link>を使用してください + </emphasis> + </refpurpose> + </refnamediv> + <refsynopsisdiv> + <title>Calling Sequence</title> + <synopsis> + [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) + </synopsis> + </refsynopsisdiv> + <refsection> + <title>Arguments</title> + <variablelist> + <varlistentry> + <term>RVEC</term> + <listitem> + <para>Integer. (INPUT) </para> + <para> + 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. + </para> + <itemizedlist> + <listitem> + <para>RVEC = 0 Compute Ritz values only.</para> + </listitem> + <listitem> + <para> + RVEC = 1 Compute Ritz vectors or Schur vectors. See + Remarks below. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>HOWMANY</term> + <listitem> + <para>Character. (INPUT) </para> + <para> + Specifies the form of the basis for the invariant subspace + corresponding to the converged Ritz values that is to be computed. + </para> + <itemizedlist> + <listitem> + <para>'A': Compute NEV Ritz vectors;</para> + </listitem> + <listitem> + <para>'P': Compute NEV Schur vectors;</para> + </listitem> + <listitem> + <para> + 'S': compute some of the Ritz vectors, specified by the + integer array SELECT. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>SELECT</term> + <listitem> + <para>Integer array of dimension NCV. (INPUT) </para> + <para> + 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. + </para> + <para> + If HOWMANY = 'A' or 'P', SELECT need not be initialized but it + is used as internal workspace. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>D</term> + <listitem> + <para>Complex*16 array of dimension NEV + 1. (OUTPUT) </para> + <para> + On exit, D contains the Ritz approximations to the eigenvalues + lambda for A * z = lambda * B * z. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Z</term> + <listitem> + <para>Complex*16 N by NEV array. (OUTPUT) </para> + <para>On exit, </para> + <para> + 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. + </para> + <para> + If RVEC = 0 or HOWMANY = 'P', then Z is NOT REFERENCED. + </para> + <para> + 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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>SIGMA</term> + <listitem> + <para>Complex*16. (INPUT) </para> + <para>If IPARAM(7) = 3 then SIGMA represents the shift. </para> + <para>Not referenced if IPARAM(7) = 1 or 2.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>WORKev</term> + <listitem> + <para>Complex*16 work array of dimension 2 * NCV. (WORKSPACE)</para> + </listitem> + </varlistentry> + </variablelist> + <para> + 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. + </para> + <para> + These arguments MUST NOT BE MODIFIED between the last call to + ZNAUPD and the call to ZNEUPD. + </para> + <para> + Three of these parameters (V, WORKL and INFO) are also output + parameters. + </para> + <variablelist> + <varlistentry> + <term>V</term> + <listitem> + <para>Complex*16 N by NCV array. (INPUT/OUTPUT) </para> + <para> + Upon INPUT: the NCV columns of V contain the Arnoldi basis + vectors for OP as constructed by ZNAUPD. + </para> + <para> + Upon OUTPUT: If RVEC = 1 the first NCONV = IPARAM(5) columns + contain approximate Schur vectors that span the desired invariant + subspace. + </para> + <para> + 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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>WORKL</term> + <listitem> + <para> + Double precision work array of length LWORKL. + (OUTPUT/WORKSPACE) + </para> + <para> + WORKL(1:ncv * ncv + 2 * ncv) contains information obtained in + znaupd. They are not changed by zneupd. + </para> + <para> + 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. + </para> + <para> + Note: IPNTR(9:13) contains the pointer into WORKL for + addresses of the above information computed by zneupd. + </para> + <itemizedlist> + <listitem> + <para> + IPNTR(9): pointer to the NCV RITZ values of the original + system. + </para> + </listitem> + <listitem> + <para>IPNTR(10): Not used </para> + </listitem> + <listitem> + <para> + IPNTR(11): pointer to the NCV corresponding error + estimates. + </para> + </listitem> + <listitem> + <para> + IPNTR(12): pointer to the NCV by NCV upper triangular + Schur matrix for H. + </para> + </listitem> + <listitem> + <para> + 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. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term>INFO</term> + <listitem> + <para>Integer. (OUTPUT) </para> + <para>Error flag on output.</para> + <itemizedlist> + <listitem> + <para>0: Normal exit.</para> + </listitem> + <listitem> + <para> + 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. + </para> + <para> + NOTE: Not necessary if Z and V share the same space. + Please notify the authors if this error occurs. + </para> + </listitem> + <listitem> + <para>-1: N must be positive.</para> + </listitem> + <listitem> + <para>-2: NEV must be positive.</para> + </listitem> + <listitem> + <para>-3: NCV-NEV >= 1 and less than or equal to N.</para> + </listitem> + <listitem> + <para> + -5: WHICH must be one of 'LM', 'SM', 'LR', 'SR', 'LI', + 'SI'. + </para> + </listitem> + <listitem> + <para>-6: BMAT must be one of 'I' or 'G'.</para> + </listitem> + <listitem> + <para> + -7: Length of private work WORKL array is not + sufficient. + </para> + </listitem> + <listitem> + <para> + -8: Error return from LAPACK eigenvalue calculation. This + should never happened. + </para> + </listitem> + <listitem> + <para> + -9: Error return from calculation of eigenvectors. + Informational error from LAPACK routine ztrevc. + </para> + </listitem> + <listitem> + <para>-10: IPARAM(7) must be 1, 2, 3.</para> + </listitem> + <listitem> + <para>-11: IPARAM(7) = 1 and BMAT = 'G' are incompatible.</para> + </listitem> + <listitem> + <para>-12: HOWMANY = 'S' not yet implemented.</para> + </listitem> + <listitem> + <para> + -13: HOWMANY must be one of 'A' or 'P' if RVEC = .true. + </para> + </listitem> + <listitem> + <para> + -14: ZNAUPD did not find any eigenvalues to sufficient + accuracy. + </para> + </listitem> + <listitem> + <para> + -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. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Description</title> + <para> + This subroutine returns the converged approximations to eigenvalues + of A * z = lambda * B * z and (optionally): + </para> + <orderedlist> + <listitem> + <para>The corresponding approximate eigenvectors; </para> + </listitem> + <listitem> + <para> + An orthonormal basis for the associated approximate invariant + subspace; + </para> + </listitem> + <listitem> + <para>Both.</para> + </listitem> + </orderedlist> + <para> + There is negligible additional cost to obtain eigenvectors. An + orthonormal basis is always computed. + </para> + <para> + There is an additional storage cost of n*nev if both are requested + (in this case a separate array Z must be supplied). + </para> + <para> + 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. + </para> + <para>ZNAUPD must be called before this routine is called. </para> + <para> + 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. + </para> + <para> + The computed orthonormal basis for the invariant subspace + corresponding to these Ritz values is referred to as a Schur basis. + </para> + <para> + 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. + </para> + </refsection> + <refsection> + <title>Remarks</title> + <orderedlist> + <listitem> + <para>Currently only HOWMNY = 'A' and 'P' are implemented. </para> + </listitem> + <listitem> + <para> + Schur vectors are an orthogonal representation for the basis of + Ritz vectors. Thus, their numerical properties are often superior. + </para> + <para>If RVEC = 1 then the relationship </para> + <para>A * V(:,1:IPARAM(5)) = V(:,1:IPARAM(5)) * T, </para> + <para>and </para> + <para>transpose( V(:,1:IPARAM(5)) ) * V(:,1:IPARAM(5)) = I </para> + <para> + are approximately satisfied. Here T is the leading submatrix of + order IPARAM(5) of the upper triangular matrix stored + workl(ipntr(12)). + </para> + </listitem> + </orderedlist> + </refsection> + <refsection> + <title>Example</title> + <programlisting role="example"> + <![CDATA[ +// The following sets dimensions for this problem. +nx = 10; +nev = 3; +ncv = 6; +bmat = 'I'; +which = 'LM'; +// Local Arrays +iparam = zeros(11, 1); +ipntr = zeros(14, 1); +_select = zeros(ncv, 1); +d = zeros(nev + 1, 1) + 0 * %i; +z = zeros(nx, nev) + 0* %i; +resid = zeros(nx, 1) + 0 * %i; +v = zeros(nx, ncv) + 0 * %i; +workd = zeros(3 * nx, 1) + 0 * %i; +workev = zeros(2 * ncv, 1) + 0 * %i; +rwork = zeros(ncv, 1); +workl = zeros(3 * ncv * ncv + 5 *ncv, 1) + 0 * %i; +// Build the complex test matrix +A = diag(10 * ones(nx,1) + %i * ones(nx,1)); +A(1:$-1,2:$) = A(1:$-1,2:$) + diag(6 * ones(nx - 1,1)); +A(2:$,1:$-1) = A(2:$,1:$-1) + diag(-6 * ones(nx - 1,1)); +tol = 0; +ido = 0; +ishfts = 1; +maxitr = 300; +mode1 = 1; +iparam(1) = ishfts; +iparam(3) = maxitr; +iparam(7) = mode1; +sigma = complex(0); +info_znaupd = 0; +// M A I N L O O P (Reverse communication) +while(ido <> 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); +]]> + </programlisting> + </refsection> + <refsection role="see also"> + <title>See Also</title> + <simplelist type="inline"> + <member> + <link linkend="dnaupd">znaupd</link> + </member> + <member> + <link linkend="dnaupd">dnaupd</link> + </member> + <member> + <link linkend="dnaupd">dneupd</link> + </member> + </simplelist> + </refsection> + <refsection> + <title>Bibliography</title> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 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). + </para> + </refsection> + <refsection> + <title>Used Functions</title> + <para>Based on ARPACK routine zneupd</para> + </refsection> + <refsection> + <title>履歴</title> + <revhistory> + <revision> + <revnumber>5.4.0</revnumber> + <revremark> + 関数は廃止され,<link linkend="eigs">eigs</link>に代替されました. + </revremark> + </revision> + </revhistory> + </refsection> +</refentry> 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); + |