added japanese translation of arnoldi module.
[scilab.git] / scilab / modules / arnoldi / help / ja_JP / dnaupd.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2
3 <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">
4     
5     <refnamediv>
6         
7         <refname>dnaupd</refname>
8         
9         <refpurpose>
10             
11             暗黙のうちに再開されるArnoldi反復へのインターフェイスで,
12             
13             実線形演算子の小数の固有値/ベクトルの組を近似的に計算します.
14             
15             <emphasis role="bold">
16                 
17                 この関数は廃止されました. <link linkend="eigs">eigs</link>を使用してください
18                 
19             </emphasis>
20             
21         </refpurpose>
22         
23     </refnamediv>
24     
25     <refsynopsisdiv>
26         
27         <title>Calling Sequence</title>
28         
29         <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>
30         
31     </refsynopsisdiv>
32     
33     <refsection>
34         
35         <title>Arguments</title>
36         
37         <variablelist>
38             
39             <varlistentry>
40                 
41                 <term>ID0</term>
42                 
43                 <listitem>
44                     
45                     <para>
46                         
47                         Integer. (INPUT/OUTPUT)
48                         
49                     </para>
50                     
51                     <para>
52                         
53                         Reverse communication flag. IDO must
54                         
55                         be zero on the first call to dnaupd. IDO will be set internally to
56                         
57                         indicate the type of operation to be performed. Control is then
58                         
59                         given back to the calling routine which has the responsibility to
60                         
61                         carry out the requested operation and call dnaupd with the result.
62                         
63                         The operand is given in WORKD(IPNTR(1)), the result must be put in
64                         
65                         WORKD(IPNTR(2)).
66                         
67                     </para>
68                     
69                     <itemizedlist>
70                         
71                         <listitem>
72                             
73                             <para>
74                                 
75                                 IDO = 0: first call to the reverse communication
76                                 
77                                 interface.
78                                 
79                             </para>
80                             
81                         </listitem>
82                         
83                         <listitem>
84                             
85                             <para>
86                                 
87                                 IDO = -1: compute Y = OP * X where IPNTR(1) is the pointer
88                                 
89                                 into WORKD for X, IPNTR(2) is the pointer into WORKD for Y. This
90                                 
91                                 is for the initialization phase to force the starting vector
92                                 
93                                 into the range of OP.
94                                 
95                             </para>
96                             
97                         </listitem>
98                         
99                         <listitem>
100                             
101                             <para>
102                                 
103                                 IDO = 1: compute Y = OP * X where IPNTR(1) is the pointer
104                                 
105                                 into WORKD for X, IPNTR(2) is the pointer into WORKD for Y. In
106                                 
107                                 mode 3 and 4, the vector B * X is already available in
108                                 
109                                 WORKD(ipntr(3)). It does not need to be recomputed in forming OP
110                                 
111                                 * X.
112                                 
113                             </para>
114                             
115                         </listitem>
116                         
117                         <listitem>
118                             
119                             <para>
120                                 
121                                 IDO = 2: compute Y = B * X where IPNTR(1) is the pointer
122                                 
123                                 into WORKD for X, IPNTR(2) is the pointer into WORKD for
124                                 
125                                 Y.
126                                 
127                             </para>
128                             
129                         </listitem>
130                         
131                         <listitem>
132                             
133                             <para>
134                                 
135                                 IDO = 3: compute the IPARAM(8) real and imaginary parts of
136                                 
137                                 the shifts where INPTR(14) is the pointer into WORKL for placing
138                                 
139                                 the shifts. See Remark 5 below.
140                                 
141                             </para>
142                             
143                         </listitem>
144                         
145                         <listitem>
146                             
147                             <para>IDO = 99: done.</para>
148                             
149                         </listitem>
150                         
151                     </itemizedlist>
152                     
153                 </listitem>
154                 
155             </varlistentry>
156             
157             <varlistentry>
158                 
159                 <term>BMAT</term>
160                 
161                 <listitem>
162                     
163                     <para>
164                         
165                         Character. (INPUT)
166                         
167                     </para>
168                     
169                     <para>
170                         
171                         specifies the type of the matrix B that defines the
172                         
173                         semi-inner product for the operator OP.
174                         
175                     </para>
176                     
177                     <itemizedlist>
178                         
179                         <listitem>
180                             
181                             <para>'I' - standard eigenvalue problem A * x = lambda * x</para>
182                             
183                         </listitem>
184                         
185                         <listitem>
186                             
187                             <para>
188                                 
189                                 'G' - generalized eigenvalue problem A * x =
190                                 
191                                 lambda * B * x
192                                 
193                             </para>
194                             
195                         </listitem>
196                         
197                     </itemizedlist>
198                     
199                 </listitem>
200                 
201             </varlistentry>
202             
203             <varlistentry>
204                 
205                 <term>N</term>
206                 
207                 <listitem>
208                     
209                     <para>Integer. (INPUT)</para>
210                     
211                     <para>dimension of the eigenproblem.</para>
212                     
213                 </listitem>
214                 
215             </varlistentry>
216             
217             <varlistentry>
218                 
219                 <term>WHICH</term>
220                 
221                 <listitem>
222                     
223                     <para>
224                         
225                         string of length 2. (INPUT)
226                         
227                     </para>
228                     
229                     <para>
230                         
231                         Specifies which of the Ritz values of OP to
232                         
233                         compute.
234                         
235                     </para>
236                     
237                     <itemizedlist>
238                         
239                         <listitem>
240                             
241                             <para>
242                                 
243                                 'LM' - want the NEV eigenvalues of largest
244                                 
245                                 magnitude.
246                                 
247                             </para>
248                             
249                         </listitem>
250                         
251                         <listitem>
252                             
253                             <para>
254                                 
255                                 'SM' - want the NEV eigenvalues of smallest
256                                 
257                                 magnitude.
258                                 
259                             </para>
260                             
261                         </listitem>
262                         
263                         <listitem>
264                             
265                             <para>
266                                 
267                                 'LR' - want the NEV eigenvalues of largest real
268                                 
269                                 part.
270                                 
271                             </para>
272                             
273                         </listitem>
274                         
275                         <listitem>
276                             
277                             <para>
278                                 
279                                 'SR' - want the NEV eigenvalues of smallest real
280                                 
281                                 part.
282                                 
283                             </para>
284                             
285                         </listitem>
286                         
287                         <listitem>
288                             
289                             <para>
290                                 
291                                 'LI' - want the NEV eigenvalues of largest imaginary
292                                 
293                                 part.
294                                 
295                             </para>
296                             
297                         </listitem>
298                         
299                         <listitem>
300                             
301                             <para>
302                                 
303                                 'SI' - want the NEV eigenvalues of smallest imaginary
304                                 
305                                 part.
306                                 
307                             </para>
308                             
309                         </listitem>
310                         
311                     </itemizedlist>
312                     
313                 </listitem>
314                 
315             </varlistentry>
316             
317             <varlistentry>
318                 
319                 <term>NEV</term>
320                 
321                 <listitem>
322                     
323                     <para>
324                         
325                         Integer. (INPUT)
326                         
327                     </para>
328                     
329                     <para>
330                         
331                         number of eigenvalues of OP to be computed. 0 &lt;
332                         
333                         NEV &lt; N-1.
334                         
335                     </para>
336                     
337                 </listitem>
338                 
339             </varlistentry>
340             
341             <varlistentry>
342                 
343                 <term>TOL</term>
344                 
345                 <listitem>
346                     
347                     <para>
348                         
349                         scalar. (INPUT)
350                         
351                     </para>
352                     
353                     <para>
354                         
355                         Stopping criterion: the relative accuracy of the Ritz
356                         
357                         value is considered acceptable if BOUNDS(I) &lt;= TOL*ABS(RITZ(I)).
358                         
359                         If TOL &lt;= 0. is passed the machine precision is set.
360                         
361                     </para>
362                     
363                 </listitem>
364                 
365             </varlistentry>
366             
367             <varlistentry>
368                 
369                 <term>RESID</term>
370                 
371                 <listitem>
372                     
373                     <para>array of length N. (INPUT/OUTPUT)</para>
374                     
375                     <para>
376                         
377                         On INPUT: If INFO = 0, a random initial residual vector is
378                         
379                         used, else RESID contains the initial residual vector, possibly from
380                         
381                         a previous run.
382                         
383                     </para>
384                     
385                     <para>On OUTPUT: RESID contains the final residual vector.</para>
386                     
387                 </listitem>
388                 
389             </varlistentry>
390             
391             <varlistentry>
392                 
393                 <term>NCV</term>
394                 
395                 <listitem>
396                     
397                     <para>
398                         
399                         Integer. (INPUT)
400                         
401                     </para>
402                     
403                     <para>
404                         
405                         number of columns of the matrix V. NCV must satisfy
406                         
407                         the two inequalities 2 &lt;= NCV - NEV and NCV &lt;= N.
408                         
409                     </para>
410                     
411                     <para>
412                         
413                         This will indicate how many Arnoldi vectors are generated at
414                         
415                         each iteration.
416                         
417                     </para>
418                     
419                     <para>
420                         
421                         After the startup phase in which NEV Arnoldi vectors are
422                         
423                         generated, the algorithm generates approximately NCV - NEV Arnoldi
424                         
425                         vectors at each subsequent update iteration. Most of the cost in
426                         
427                         generating each Arnoldi vector is in the matrix-vector operation
428                         
429                         OP * x.
430                         
431                     </para>
432                     
433                     <para>
434                         
435                         NOTE: 2 &lt;= NCV - NEV in order that complex conjugate pairs of
436                         
437                         Ritz values are kept together. (See remark 4 below)
438                         
439                     </para>
440                     
441                 </listitem>
442                 
443             </varlistentry>
444             
445             <varlistentry>
446                 
447                 <term>V</term>
448                 
449                 <listitem>
450                     
451                     <para>
452                         
453                         N by NCV array. (OUTPUT)
454                         
455                     </para>
456                     
457                     <para>
458                         
459                         Contains the final set of Arnoldi basis
460                         
461                         vectors.
462                         
463                     </para>
464                     
465                 </listitem>
466                 
467             </varlistentry>
468             
469             <varlistentry>
470                 
471                 <term>IPARAM</term>
472                 
473                 <listitem>
474                     
475                     <para>array of length 11. (INPUT/OUTPUT)</para>
476                     
477                     <itemizedlist>
478                         
479                         <listitem>
480                             
481                             <para>
482                                 
483                                 IPARAM(1) = ISHIFT: method for selecting the implicit
484                                 
485                                 shifts. The shifts selected at each iteration are used to
486                                 
487                                 restart the Arnoldi iteration in an implicit fashion.
488                                 
489                             </para>
490                             
491                             <itemizedlist>
492                                 
493                                 <listitem>
494                                     
495                                     <para>
496                                         
497                                         ISHIFT = 0: the shifts are provided by the user via
498                                         
499                                         reverse communication. The real and imaginary parts of the
500                                         
501                                         NCV eigenvalues of the Hessenberg matrix H are returned in
502                                         
503                                         the part of the WORKL array corresponding to RITZR and
504                                         
505                                         RITZI. See remark 5 below.
506                                         
507                                     </para>
508                                     
509                                 </listitem>
510                                 
511                                 <listitem>
512                                     
513                                     <para>
514                                         
515                                         ISHIFT = 1: exact shifts with respect to the current
516                                         
517                                         Hessenberg matrix H. This is equivalent to restarting the
518                                         
519                                         iteration with a starting vector that is a linear
520                                         
521                                         combination of approximate Schur vectors associated with the
522                                         
523                                         "wanted" Ritz values.
524                                         
525                                     </para>
526                                     
527                                 </listitem>
528                                 
529                             </itemizedlist>
530                             
531                         </listitem>
532                         
533                         <listitem>
534                             
535                             <para>IPARAM(2) = LEVEC. No longer referenced.</para>
536                             
537                         </listitem>
538                         
539                         <listitem>
540                             
541                             <para>IPARAM(3) = MXITER </para>
542                             
543                             <para>
544                                 
545                                 On INPUT: maximum number of Arnoldi update iterations
546                                 
547                                 allowed.
548                                 
549                             </para>
550                             
551                             <para>
552                                 
553                                 On OUTPUT: actual number of Arnoldi update iterations
554                                 
555                                 taken.
556                                 
557                             </para>
558                             
559                         </listitem>
560                         
561                         <listitem>
562                             
563                             <para>
564                                 
565                                 IPARAM(4) = NB: blocksize to be used in the recurrence.
566                                 
567                                 The code currently works only for NB = 1.
568                                 
569                             </para>
570                             
571                         </listitem>
572                         
573                         <listitem>
574                             
575                             <para>
576                                 
577                                 IPARAM(5) = NCONV: number of "converged" Ritz values. This
578                                 
579                                 represents the number of Ritz values that satisfy the
580                                 
581                                 convergence criterion.
582                                 
583                             </para>
584                             
585                         </listitem>
586                         
587                         <listitem>
588                             
589                             <para>
590                                 
591                                 IPARAM(6) = IUPD No longer referenced. Implicit restarting
592                                 
593                                 is ALWAYS used.
594                                 
595                             </para>
596                             
597                         </listitem>
598                         
599                         <listitem>
600                             
601                             <para>
602                                 
603                                 IPARAM(7) = MODE On INPUT determines what type of
604                                 
605                                 eigenproblem is being solved. Must be 1,2,3,4; See under
606                                 
607                                 Description of dnaupd for the five modes available.
608                                 
609                             </para>
610                             
611                         </listitem>
612                         
613                         <listitem>
614                             
615                             <para>
616                                 
617                                 IPARAM(8) = NP When ido = 3 and the user provides shifts
618                                 
619                                 through reverse communication (IPARAM(1)=0), dnaupd returns NP,
620                                 
621                                 the number of shifts the user is to provide.
622                                 
623                             </para>
624                             
625                             <para>0 &lt; NP &lt;= NCV-NEV. See Remark 5 below.</para>
626                             
627                         </listitem>
628                         
629                         <listitem>
630                             
631                             <para>IPARAM(9) = NUMOP, </para>
632                             
633                             <para>IPARAM(10) = NUMOPB, </para>
634                             
635                             <para>IPARAM(11) = NUMREO, </para>
636                             
637                             <para>
638                                 
639                                 On OUTPUT: NUMOP = total number of OP*x operations, NUMOPB
640                                 
641                                 = total number of B*x operations if BMAT='G', NUMREO = total
642                                 
643                                 number of steps of re-orthogonalization.
644                                 
645                             </para>
646                             
647                         </listitem>
648                         
649                     </itemizedlist>
650                     
651                 </listitem>
652                 
653             </varlistentry>
654             
655             <varlistentry>
656                 
657                 <term>IPNTR</term>
658                 
659                 <listitem>
660                     
661                     <para>
662                         
663                         array of length 14. (OUTPUT)
664                         
665                     </para>
666                     
667                     <para>
668                         
669                         Pointer to mark the starting locations in
670                         
671                         the WORKD and WORKL arrays for matrices/vectors used by the Arnoldi
672                         
673                         iteration.
674                         
675                     </para>
676                     
677                     <itemizedlist>
678                         
679                         <listitem>
680                             
681                             <para>
682                                 
683                                 IPNTR(1): pointer to the current operand vector X in
684                                 
685                                 WORKD.
686                                 
687                             </para>
688                             
689                         </listitem>
690                         
691                         <listitem>
692                             
693                             <para>
694                                 
695                                 IPNTR(2): pointer to the current result vector Y in
696                                 
697                                 WORKD.
698                                 
699                             </para>
700                             
701                         </listitem>
702                         
703                         <listitem>
704                             
705                             <para>
706                                 
707                                 IPNTR(3): pointer to the vector B * X in WORKD when used
708                                 
709                                 in the shift-and-invert mode.
710                                 
711                             </para>
712                             
713                         </listitem>
714                         
715                         <listitem>
716                             
717                             <para>
718                                 
719                                 IPNTR(4): pointer to the next available location in WORKL
720                                 
721                                 that is untouched by the program.
722                                 
723                             </para>
724                             
725                         </listitem>
726                         
727                         <listitem>
728                             
729                             <para>
730                                 
731                                 IPNTR(5): pointer to the NCV by NCV upper Hessenberg
732                                 
733                                 matrix H in WORKL.
734                                 
735                             </para>
736                             
737                         </listitem>
738                         
739                         <listitem>
740                             
741                             <para>
742                                 
743                                 IPNTR(6): pointer to the real part of the ritz value array
744                                 
745                                 RITZR in WORKL.
746                                 
747                             </para>
748                             
749                         </listitem>
750                         
751                         <listitem>
752                             
753                             <para>
754                                 
755                                 IPNTR(7): pointer to the imaginary part of the ritz value
756                                 
757                                 array RITZI in WORKL.
758                                 
759                             </para>
760                             
761                         </listitem>
762                         
763                         <listitem>
764                             
765                             <para>
766                                 
767                                 IPNTR(8): pointer to the Ritz estimates in array WORKL
768                                 
769                                 associated with the Ritz values located in RITZR and RITZI in
770                                 
771                                 WORKL.
772                                 
773                             </para>
774                             
775                         </listitem>
776                         
777                         <listitem>
778                             
779                             <para>
780                                 
781                                 IPNTR(14): pointer to the NP shifts in WORKL. See Remark 5
782                                 
783                                 below.
784                                 
785                             </para>
786                             
787                         </listitem>
788                         
789                     </itemizedlist>
790                     
791                     <para>
792                         
793                         Note: IPNTR(9:13) is only referenced by dneupd . See Remark
794                         
795                         2.
796                         
797                     </para>
798                     
799                     <itemizedlist>
800                         
801                         <listitem>
802                             
803                             <para>
804                                 
805                                 IPNTR(9): pointer to the real part of the NCV RITZ values
806                                 
807                                 of the original system.
808                                 
809                             </para>
810                             
811                         </listitem>
812                         
813                         <listitem>
814                             
815                             <para>
816                                 
817                                 IPNTR(10): pointer to the imaginary part of the NCV RITZ
818                                 
819                                 values of the original system.
820                                 
821                             </para>
822                             
823                         </listitem>
824                         
825                         <listitem>
826                             
827                             <para>
828                                 
829                                 IPNTR(11): pointer to the NCV corresponding error
830                                 
831                                 bounds.
832                                 
833                             </para>
834                             
835                         </listitem>
836                         
837                         <listitem>
838                             
839                             <para>
840                                 
841                                 IPNTR(12):pointer to the NCV by NCV upper quasi-triangular
842                                 
843                                 Schur matrix for H.
844                                 
845                             </para>
846                             
847                         </listitem>
848                         
849                         <listitem>
850                             
851                             <para>
852                                 
853                                 IPNTR(13): pointer to the NCV by NCV matrix of
854                                 
855                                 eigenvectors of the upper Hessenberg matrix H. Only referenced
856                                 
857                                 by dneupd if RVEC = 1 See Remark 2 below.
858                                 
859                             </para>
860                             
861                         </listitem>
862                         
863                     </itemizedlist>
864                     
865                 </listitem>
866                 
867             </varlistentry>
868             
869             <varlistentry>
870                 
871                 <term>WORKD</term>
872                 
873                 <listitem>
874                     
875                     <para>
876                         
877                         Double precision work array of length 3 * N. (REVERSE
878                         
879                         COMMUNICATION)
880                         
881                     </para>
882                     
883                     <para>
884                         
885                         Distributed array to be used in the basic Arnoldi iteration
886                         
887                         for reverse communication. The user should not use WORKD as
888                         
889                         temporary workspace during the iteration. Upon termination
890                         
891                         WORKD(1:N) contains B*RESID(1:N). If an invariant subspace
892                         
893                         associated with the converged Ritz values is desired, see remark 2
894                         
895                         below, subroutine dneupd uses this output. See Data Distribution
896                         
897                         Note below.
898                         
899                     </para>
900                     
901                 </listitem>
902                 
903             </varlistentry>
904             
905             <varlistentry>
906                 
907                 <term>WORKL</term>
908                 
909                 <listitem>
910                     
911                     <para>
912                         
913                         work array of length at least 3 * NCV ** 2 + 6 * NCV.
914                         
915                         (OUTPUT/WORKSPACE)
916                         
917                     </para>
918                     
919                     <para>
920                         
921                         Private (replicated) array on each PE or array
922                         
923                         allocated on the front end. See Data Distribution Note below.
924                         
925                     </para>
926                     
927                 </listitem>
928                 
929             </varlistentry>
930             
931             <varlistentry>
932                 
933                 <term>INFO</term>
934                 
935                 <listitem>
936                     
937                     <para>Integer. (INPUT/OUTPUT)</para>
938                     
939                     <para>
940                         
941                         If INFO == 0, a randomly initial residual vector is used, else
942                         
943                         RESID contains the initial residual vector, possibly from a previous
944                         
945                         run.
946                         
947                     </para>
948                     
949                     <para>Error flag on output.</para>
950                     
951                     <itemizedlist>
952                         
953                         <listitem>
954                             
955                             <para>0: Normal exit.</para>
956                             
957                         </listitem>
958                         
959                         <listitem>
960                             
961                             <para>
962                                 
963                                 1: Maximum number of iterations taken. All possible
964                                 
965                                 eigenvalues of OP has been found. IPARAM(5) returns the number
966                                 
967                                 of wanted converged Ritz values.
968                                 
969                             </para>
970                             
971                         </listitem>
972                         
973                         <listitem>
974                             
975                             <para>
976                                 
977                                 2: No longer an informational error. Deprecated starting
978                                 
979                                 with release 2 of ARPACK.
980                                 
981                             </para>
982                             
983                         </listitem>
984                         
985                         <listitem>
986                             
987                             <para>
988                                 
989                                 3: No shifts could be applied during a cycle of the
990                                 
991                                 Implicitly restarted Arnoldi iteration. One possibility is to
992                                 
993                                 increase the size of NCV relative to NEV. See remark 4
994                                 
995                                 below.
996                                 
997                             </para>
998                             
999                         </listitem>
1000                         
1001                         <listitem>
1002                             
1003                             <para>-1: N must be positive.</para>
1004                             
1005                         </listitem>
1006                         
1007                         <listitem>
1008                             
1009                             <para>-2: NEV must be positive.</para>
1010                             
1011                         </listitem>
1012                         
1013                         <listitem>
1014                             
1015                             <para>-3: NCV-NEV &gt;= 2 and less than or equal to N.</para>
1016                             
1017                         </listitem>
1018                         
1019                         <listitem>
1020                             
1021                             <para>
1022                                 
1023                                 -4: The maximum number of Arnoldi update iterations
1024                                 
1025                                 allowed must be greater than zero.
1026                                 
1027                             </para>
1028                             
1029                         </listitem>
1030                         
1031                         <listitem>
1032                             
1033                             <para>
1034                                 
1035                                 -5: WHICH must be one of 'LM', 'SM', 'LR', 'SR', 'LI',
1036                                 
1037                                 'SI'.
1038                                 
1039                             </para>
1040                             
1041                         </listitem>
1042                         
1043                         <listitem>
1044                             
1045                             <para>-6: BMAT must be one of 'I' or 'G'.</para>
1046                             
1047                         </listitem>
1048                         
1049                         <listitem>
1050                             
1051                             <para>
1052                                 
1053                                 -7: Length of private work array WORKL is not
1054                                 
1055                                 sufficient.
1056                                 
1057                             </para>
1058                             
1059                         </listitem>
1060                         
1061                         <listitem>
1062                             
1063                             <para>
1064                                 
1065                                 -8: Error return from LAPACK eigenvalue
1066                                 
1067                                 calculation.
1068                                 
1069                             </para>
1070                             
1071                         </listitem>
1072                         
1073                         <listitem>
1074                             
1075                             <para>-9: Starting vector is zero.</para>
1076                             
1077                         </listitem>
1078                         
1079                         <listitem>
1080                             
1081                             <para>-10: IPARAM(7) must be 1, 2, 3, 4.</para>
1082                             
1083                         </listitem>
1084                         
1085                         <listitem>
1086                             
1087                             <para>-11: IPARAM(7) = 1 and BMAT = 'G' are incompatable.</para>
1088                             
1089                         </listitem>
1090                         
1091                         <listitem>
1092                             
1093                             <para>-12: IPARAM(1) must be equal to 0 or 1.</para>
1094                             
1095                         </listitem>
1096                         
1097                         <listitem>
1098                             
1099                             <para>
1100                                 
1101                                 -9999: Could not build an Arnoldi factorization. IPARAM(5)
1102                                 
1103                                 returns the size of the current Arnoldi factorization. The user
1104                                 
1105                                 is advised to check that enough workspace and array storage has
1106                                 
1107                                 been allocated.
1108                                 
1109                             </para>
1110                             
1111                         </listitem>
1112                         
1113                     </itemizedlist>
1114                     
1115                 </listitem>
1116                 
1117             </varlistentry>
1118             
1119         </variablelist>
1120         
1121     </refsection>
1122     
1123     <refsection>
1124         
1125         <title>Description</title>
1126         
1127         <para>
1128             
1129             Reverse communication interface for the Implicitly Restarted Arnoldi
1130             
1131             iteration. This subroutine computes approximations to a few eigenpairs of
1132             
1133             a linear operator "OP" with respect to a semi-inner product defined by a
1134             
1135             symmetric positive semi-definite real matrix B. B may be the identity
1136             
1137             matrix. NOTE: If the linear operator "OP" is real and symmetric with
1138             
1139             respect to the real positive semi-definite symmetric matrix B, i.e. B*OP =
1140             
1141             (OP`)*B, then subroutine dsaupd should be used instead.
1142             
1143         </para>
1144         
1145         <para>
1146             
1147             The computed approximate eigenvalues are called Ritz values and the
1148             
1149             corresponding approximate eigenvectors are called Ritz vectors.
1150             
1151         </para>
1152         
1153         <para>
1154             
1155             dnaupd is usually called iteratively to solve one of the following
1156             
1157             problems:
1158             
1159         </para>
1160         
1161         <itemizedlist>
1162             
1163             <listitem>
1164                 
1165                 <para>
1166                     
1167                     Mode 1: A*x = lambda*x. <literal>
1168                         
1169                         OP = A , B =
1170                         
1171                         I
1172                         
1173                     </literal>
1174                     
1175                     .
1176                     
1177                 </para>
1178                 
1179             </listitem>
1180             
1181             <listitem>
1182                 
1183                 <para>
1184                     
1185                     Mode 2: A*x = lambda*M*x, M symmetric positive definite
1186                     
1187                     <literal>OP = inv[M]*A, B = M</literal>. (If M can be factored see
1188                     
1189                     remark 3 below)
1190                     
1191                 </para>
1192                 
1193             </listitem>
1194             
1195             <listitem>
1196                 
1197                 <para>
1198                     
1199                     Mode 3: A*x = lambda*M*x, M symmetric positive semi-definite.
1200                     
1201                     <literal>OP = Real_Part{ inv[A - sigma*M]*M }, B = M</literal>.
1202                     
1203                     shift-and-invert mode (in real arithmetic)
1204                     
1205                 </para>
1206                 
1207                 <para>
1208                     
1209                     If <literal>OP*x = amu*x</literal>, then
1210                     
1211                 </para>
1212                 
1213                 <para>
1214                     
1215                     <literal>
1216                         
1217                         amu = 1/2 * [ 1/(lambda-sigma) +
1218                         
1219                         1/(lambda-conjg(sigma))]
1220                         
1221                     </literal>
1222                     
1223                     .
1224                     
1225                 </para>
1226                 
1227                 <para>
1228                     
1229                     Note: If sigma is real, i.e. imaginary part of sigma is zero;
1230                     
1231                     <literal>
1232                         
1233                         Real_Part{ inv[A - sigma*M]*M } == inv[A -
1234                         
1235                         sigma*M]*M
1236                         
1237                     </literal>
1238                     
1239                     <literal>
1240                         
1241                         amu ==
1242                         
1243                         1/(lambda-sigma)
1244                         
1245                     </literal>
1246                     
1247                     .
1248                     
1249                 </para>
1250                 
1251             </listitem>
1252             
1253             <listitem>
1254                 
1255                 <para>
1256                     
1257                     Mode 4: A*x = lambda*M*x, M symmetric semi-definite <literal>
1258                         
1259                         OP
1260                         
1261                         = Imaginary_Part{ inv[A - sigma*M]*M } , B = M
1262                         
1263                     </literal>
1264                     
1265                     .
1266                     
1267                     shift-and-invert mode (in real arithmetic)
1268                     
1269                 </para>
1270                 
1271                 <para>
1272                     
1273                     If <literal>OP*x = amu*x</literal>, then <literal>
1274                         
1275                         amu = 1/2i * [
1276                         
1277                         1/(lambda-sigma) - 1/(lambda-conjg(sigma)) ]
1278                         
1279                     </literal>
1280                     
1281                     .
1282                     
1283                 </para>
1284                 
1285             </listitem>
1286             
1287         </itemizedlist>
1288         
1289         <para>
1290             
1291             Both mode 3 and 4 give the same enhancement to eigenvalues close to
1292             
1293             the (complex) shift sigma. However, as lambda goes to infinity, the
1294             
1295             operator OP in mode 4 dampens the eigenvalues more strongly than does OP
1296             
1297             defined in mode 3.
1298             
1299         </para>
1300         
1301         <para>
1302             
1303             NOTE: The action of w &lt;- inv[A - sigma * M] * v or w &lt;- inv[M] * v
1304             
1305             should be accomplished either by a direct method using a sparse matrix
1306             
1307             factorization and solving <literal>[A - sigma * M] * w = v</literal> or
1308             
1309             <literal>M * w = v</literal>, or through an iterative method for solving
1310             
1311             these systems. If an iterative method is used, the convergence test must
1312             
1313             be more stringent than the accuracy requirements for the eigenvalue
1314             
1315             approximations.
1316             
1317         </para>
1318         
1319     </refsection>
1320     
1321     <refsection>
1322         
1323         <title>Example</title>
1324         
1325         <programlisting role="example">
1326             
1327             <![CDATA[
1328 // The following sets dimensions for this problem.
1329
1330 nx    = 10;
1331
1332 nev   = 3;
1333 ncv   = 6;
1334 bmat  = 'I';
1335 which = 'LM';
1336
1337 // Local Arrays
1338
1339 iparam  = zeros(11, 1);
1340 ipntr   = zeros(14, 1);
1341 _select = zeros(ncv, 1);
1342 dr       = zeros(nev + 1, 1);
1343 di      = zeros(nev + 1, 1);
1344 z       = zeros(nx, nev + 1);
1345 resid   = zeros(nx, 1);
1346 v       = zeros(nx, ncv);
1347 workd   = zeros(3 * nx, 1);
1348 workev  = zeros(3 * ncv, 1);
1349 workl   = zeros(3 * ncv * ncv + 6 * ncv, 1);
1350
1351 // Build the test matrix
1352
1353 A            = diag(10 * ones(nx, 1));
1354 A(1:$-1,2:$) = A(1:$-1,2:$) + diag(6 * ones(nx-1,1));
1355 A(2:$,1:$-1) = A(2:$,1:$-1) + diag(-6 * ones(nx-1,1));
1356
1357 tol    = 0;
1358 ido    = 0;
1359
1360 ishfts = 1;
1361 maxitr = 300;
1362 mode1  = 1;
1363
1364 iparam(1) = ishfts;
1365 iparam(3) = maxitr;
1366 iparam(7) = mode1;
1367
1368 sigmar = 0; // the real part of the shift
1369 sigmai = 0; // the imaginary part of the shift
1370 info_dnaupd = 0;
1371
1372 // M A I N   L O O P (Reverse communication)
1373
1374 while(ido <> 99)
1375   // Repeatedly call the routine DNAUPD and take actions indicated by parameter IDO until
1376   // either convergence is indicated or maxitr has been exceeded.
1377
1378   [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);
1379
1380   if(info_dnaupd < 0)
1381     printf('\nError with dnaupd, info = %d\n',info_dnaupd);
1382     printf('Check the documentation of dnaupd\n\n');
1383   end
1384
1385   if(ido == -1 | ido == 1)
1386     // Perform matrix vector multiplication
1387     workd(ipntr(2):ipntr(2) + nx -1) = A * workd(ipntr(1):ipntr(1) + nx - 1);
1388   end
1389 end
1390
1391 // Post-Process using DNEUPD.
1392 rvec    = 1;
1393 howmany = 'A';
1394 info_dneupd = 0;
1395
1396 [dr, di, z, resid, v, iparam, ipntr, workd, workl, info_dneupd] = dneupd(rvec, howmany, _select, dr, di, z, sigmar, sigmai, workev, ...
1397                                                                        bmat, nx, which, nev, tol, resid, ncv, v, ...
1398                                                                        iparam, ipntr, workd, workl, info_dneupd);
1399
1400 if(info_dneupd < 0)
1401   printf('\nError with dneupd, info = %d\n', info_dneupd);
1402   printf('Check the documentation of dneupd.\n\n');
1403 end
1404
1405 printf('\nDNSIMP\n');
1406 printf('======\n');
1407 printf('\n');
1408 printf('Size of the matrix is %d\n', nx);
1409 printf('The number of Ritz values requested is %d\n', nev);
1410 printf('The number of Arnoldi vectors generated (NCV) is %d\n', ncv);
1411 printf('What portion of the spectrum: %s\n', which);
1412 printf('The number of Implicit Arnoldi update iterations taken is %d\n', iparam(3));
1413 printf('The number of OP*x is %d\n', iparam(9));
1414 printf('The convergence criterion is %d\n', tol);
1415
1416 ]]>
1417             
1418         </programlisting>
1419         
1420     </refsection>
1421     
1422     <refsection>
1423         
1424         <title>Remarks</title>
1425         
1426         <para>
1427             
1428             1. The computed Ritz values are approximate eigenvalues of OP. The
1429             
1430             selection of WHICH should be made with this in mind when Mode = 3 and 4.
1431             
1432             After convergence, approximate eigenvalues of the original problem may be
1433             
1434             obtained with the ARPACK subroutine dneupd.
1435             
1436         </para>
1437         
1438         <para>
1439             
1440             2. If a basis for the invariant subspace corresponding to the
1441             
1442             converged Ritz values is needed, the user must call dneupd immediately
1443             
1444             following completion of dnaupd. This is new starting with release 2 of
1445             
1446             ARPACK.
1447             
1448         </para>
1449         
1450         <para>
1451             
1452             3. If M can be factored into a Cholesky factorization M = LL` then
1453             
1454             Mode = 2 should not be selected. Instead one should use Mode = 1 with OP =
1455             
1456             inv(L) * A * inv(L`). Appropriate triangular linear systems should be solved
1457             
1458             with L and L` rather than computing inverses. After convergence, an
1459             
1460             approximate eigenvector z of the original problem is recovered by solving
1461             
1462             L`z = x where x is a Ritz vector of OP.
1463             
1464         </para>
1465         
1466         <para>
1467             
1468             4. At present there is no a-priori analysis to guide the selection
1469             
1470             of NCV relative to NEV. The only formal requirement is that NCV &gt; NEV +
1471             
1472             2. However, it is recommended that NCV &gt;= 2 * NEV + 1. If many problems of
1473             
1474             the same type are to be solved, one should experiment with increasing NCV
1475             
1476             while keeping NEV fixed for a given test problem. This will usually
1477             
1478             decrease the required number of OP*x operations but it also increases the
1479             
1480             work and storage required to maintain the orthogonal basis vectors. The
1481             
1482             optimal "cross-over" with respect to CPU time is problem dependent and
1483             
1484             must be determined empirically. See Chapter 8 of Reference 2 for further
1485             
1486             information.
1487             
1488         </para>
1489         
1490         <para>
1491             
1492             5. When IPARAM(1) = 0, and IDO = 3, the user needs to provide the NP
1493             
1494             = IPARAM(8) real and imaginary parts of the shifts in locations
1495             
1496         </para>
1497         
1498         <programlisting>
1499             
1500             real part                  imaginary part
1501             
1502             -----------------------    --------------
1503             
1504             1   WORKL(IPNTR(14))           WORKL(IPNTR(14) + NP)
1505             
1506             2   WORKL(IPNTR(14) + 1)         WORKL(IPNTR(14) + NP + 1)
1507             
1508             .                          .
1509             
1510             .                          .
1511             
1512             .                          .
1513             
1514             NP  WORKL(IPNTR(14) + NP - 1)      WORKL(IPNTR(14) + 2 * NP - 1).
1515             
1516         </programlisting>
1517         
1518         <para>
1519             
1520             Only complex conjugate pairs of shifts may be applied and the pairs
1521             
1522             must be placed in consecutive locations. The real part of the eigenvalues
1523             
1524             of the current upper Hessenberg matrix are located in WORKL(IPNTR(6))
1525             
1526             through WORKL(IPNTR(6) + NCV - 1) and the imaginary part in WORKL(IPNTR(7))
1527             
1528             through WORKL(IPNTR(7) + NCV - 1). They are ordered according to the order
1529             
1530             defined by WHICH. The complex conjugate pairs are kept together and the
1531             
1532             associated Ritz estimates are located in WORKL(IPNTR(8)),
1533             
1534             WORKL(IPNTR(8)+1), ... , WORKL(IPNTR(8) + NCV - 1).
1535             
1536         </para>
1537         
1538     </refsection>
1539     
1540     <refsection role="see also">
1541         
1542         <title>See Also</title>
1543         
1544         <simplelist type="inline">
1545             
1546             <member>
1547                 
1548                 <link linkend="dsaupd">dsaupd</link>
1549                 
1550             </member>
1551             
1552             <member>
1553                 
1554                 <link linkend="dneupd">dneupd</link>
1555                 
1556             </member>
1557             
1558         </simplelist>
1559         
1560     </refsection>
1561     
1562     <refsection>
1563         
1564         <title>Bibliography</title>
1565         
1566         <para>
1567             
1568             1. D.C. Sorensen, "Implicit Application of Polynomial Filters in a
1569             
1570             k-Step Arnoldi Method", SIAM J. Matr. Anal. Apps., 13 (1992), pp
1571             
1572             357-385.
1573             
1574         </para>
1575         
1576         <para>
1577             
1578             2. R.B. Lehoucq, "Analysis and Implementation of an Implicitly
1579             
1580             Restarted Arnoldi Iteration", Rice University Technical Report TR95-13,
1581             
1582             Department of Computational and Applied Mathematics.
1583             
1584         </para>
1585         
1586         <para>
1587             
1588             3. B.N. Parlett, "The Symmetric Eigenvalue Problem". Prentice-Hall,
1589             
1590             1980.
1591             
1592         </para>
1593         
1594         <para>
1595             
1596             4. B.N. Parlett, B. Nour-Omid, "Towards a Black Box Lanczos
1597             
1598             Program", Computer Physics Communications, 53 (1989), pp 169-179.
1599             
1600         </para>
1601         
1602         <para>
1603             
1604             5. B. Nour-Omid, B.N. Parlett, T. Ericson, P.S. Jensen, "How to
1605             
1606             Implement the Spectral Transformation", Math. Comp., 48 (1987), pp
1607             
1608             663-673.
1609             
1610         </para>
1611         
1612         <para>
1613             
1614             6. R.G. Grimes, J.G. Lewis and H.D. Simon, "A Shifted Block Lanczos
1615             
1616             Algorithm for Solving Sparse Symmetric Generalized Eigenproblems", SIAM J.
1617             
1618             Matr. Anal. Apps., January (1993).
1619             
1620         </para>
1621         
1622         <para>
1623             
1624             7. L. Reichel, W.B. Gragg, "Algorithm 686: FORTRAN Subroutines for
1625             
1626             Updating the QR decomposition", ACM TOMS, December 1990, Volume 16 Number
1627             
1628             4, pp 369-377.
1629             
1630         </para>
1631         
1632         <para>
1633             
1634             8. R.B. Lehoucq, D.C. Sorensen, "Implementation of Some Spectral
1635             
1636             Transformations in a k-Step Arnoldi Method". In Preparation.
1637             
1638         </para>
1639         
1640     </refsection>
1641     
1642     <refsection>
1643         
1644         <title>Used Functions</title>
1645         
1646         <para>Based on ARPACK routine dnaupd</para>
1647         
1648     </refsection>
1649     
1650     <refsection>
1651         
1652         <title>履歴</title>
1653         
1654         <revhistory>
1655             
1656             <revision>
1657                 
1658                 <revnumber>5.4.0</revnumber>
1659                 
1660                 <revremark>
1661                     
1662                     関数は廃止され,<link linkend="eigs">eigs</link>に代替されました.
1663                     
1664                 </revremark>
1665                 
1666             </revision>
1667             
1668         </revhistory>
1669         
1670     </refsection>
1671     
1672 </refentry>
1673