added japanese translation of arnoldi module.
[scilab.git] / scilab / modules / arnoldi / help / ja_JP / dsaupd.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="dsaupd" xml:lang="ja">
4     
5     <refnamediv>
6         
7         <refname>dsaupd</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] = dsaupd(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>Integer. (INPUT/OUTPUT) </para>
46                     
47                     <para>
48                         
49                         Reverse communication flag. IDO must be zero on the first call
50                         
51                         to dsaupd . IDO will be set internally to indicate the type of
52                         
53                         operation to be performed. Control is then given back to the calling
54                         
55                         routine which has the responsibility to carry out the requested
56                         
57                         operation and call dsaupd with the result.
58                         
59                     </para>
60                     
61                     <para>
62                         
63                         The operand is given in WORKD(IPNTR(1)), the result must be put
64                         
65                         in WORKD(IPNTR(2)). (If Mode = 2 see remark 5 below)
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, 4 and 5, 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) shifts where IPNTR(11) is
136                                 
137                                 the pointer into WORKL for placing the shifts. See remark 6
138                                 
139                                 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>Character. (INPUT)</para>
164                     
165                     <para>
166                         
167                         Specifies the type of the matrix B that defines the semi-inner
168                         
169                         product for the operator OP.
170                         
171                     </para>
172                     
173                     <itemizedlist>
174                         
175                         <listitem>
176                             
177                             <para>'I': standard eigenvalue problem A * x = lambda * x</para>
178                             
179                         </listitem>
180                         
181                         <listitem>
182                             
183                             <para>
184                                 
185                                 'G': generalized eigenvalue problem A * x =
186                                 
187                                 lambda * B * x
188                                 
189                             </para>
190                             
191                         </listitem>
192                         
193                     </itemizedlist>
194                     
195                 </listitem>
196                 
197             </varlistentry>
198             
199             <varlistentry>
200                 
201                 <term>N</term>
202                 
203                 <listitem>
204                     
205                     <para>Integer. (INPUT)</para>
206                     
207                     <para>Dimension of the eigenproblem.</para>
208                     
209                 </listitem>
210                 
211             </varlistentry>
212             
213             <varlistentry>
214                 
215                 <term>WHICH</term>
216                 
217                 <listitem>
218                     
219                     <para>String of length 2. (INPUT)</para>
220                     
221                     <para>Specifies which of the Ritz values of OP to compute.</para>
222                     
223                     <itemizedlist>
224                         
225                         <listitem>
226                             
227                             <para>
228                                 
229                                 'LA' - compute the NEV largest (algebraic)
230                                 
231                                 eigenvalues.
232                                 
233                             </para>
234                             
235                         </listitem>
236                         
237                         <listitem>
238                             
239                             <para>
240                                 
241                                 'SA' - compute the NEV smallest (algebraic)
242                                 
243                                 eigenvalues.
244                                 
245                             </para>
246                             
247                         </listitem>
248                         
249                         <listitem>
250                             
251                             <para>
252                                 
253                                 'LM' - compute the NEV largest (in magnitude)
254                                 
255                                 eigenvalues.
256                                 
257                             </para>
258                             
259                         </listitem>
260                         
261                         <listitem>
262                             
263                             <para>
264                                 
265                                 'SM' - compute the NEV smallest (in magnitude)
266                                 
267                                 eigenvalues.
268                                 
269                             </para>
270                             
271                         </listitem>
272                         
273                         <listitem>
274                             
275                             <para>
276                                 
277                                 'BE' - compute NEV eigenvalues, half from each end of the
278                                 
279                                 spectrum. When NEV is odd, compute one more from the high end
280                                 
281                                 than from the low end. (see remark 1 below)
282                                 
283                             </para>
284                             
285                         </listitem>
286                         
287                     </itemizedlist>
288                     
289                 </listitem>
290                 
291             </varlistentry>
292             
293             <varlistentry>
294                 
295                 <term>NEV</term>
296                 
297                 <listitem>
298                     
299                     <para>Integer. (INPUT)</para>
300                     
301                     <para>
302                         
303                         Number of eigenvalues of OP to be computed. 0 &lt; NEV &lt;
304                         
305                         N.
306                         
307                     </para>
308                     
309                 </listitem>
310                 
311             </varlistentry>
312             
313             <varlistentry>
314                 
315                 <term>TOL</term>
316                 
317                 <listitem>
318                     
319                     <para>scalar. (INPUT)</para>
320                     
321                     <para>
322                         
323                         Stopping criterion: the relative accuracy of the Ritz value is
324                         
325                         considered acceptable if BOUNDS(I) &lt;= TOL * ABS(RITZ(I)). If TOL
326                         
327                         &lt;= 0. is passed the machine precision is set.
328                         
329                     </para>
330                     
331                 </listitem>
332                 
333             </varlistentry>
334             
335             <varlistentry>
336                 
337                 <term>RESID</term>
338                 
339                 <listitem>
340                     
341                     <para>Array of length N. (INPUT/OUTPUT)</para>
342                     
343                     <para>
344                         
345                         On INPUT: If INFO = 0, a random initial residual vector is
346                         
347                         used, else RESID contains the initial residual vector, possibly from
348                         
349                         a previous run.
350                         
351                     </para>
352                     
353                     <para>On OUTPUT: RESID contains the final residual vector.</para>
354                     
355                 </listitem>
356                 
357             </varlistentry>
358             
359             <varlistentry>
360                 
361                 <term>NCV</term>
362                 
363                 <listitem>
364                     
365                     <para>Integer. (INPUT)</para>
366                     
367                     <para>
368                         
369                         Number of columns of the matrix V (less than or equal to N).
370                         
371                     </para>
372                     
373                     <para>
374                         
375                         This will indicate how many Lanczos vectors are generated at
376                         
377                         each iteration. After the startup phase in which NEV Lanczos vectors
378                         
379                         are generated, the algorithm generates NCV - NEV Lanczos vectors at
380                         
381                         each subsequent update iteration. Most of the cost in generating
382                         
383                         each Lanczos vector is in the matrix-vector product OP * x. (See
384                         
385                         remark 4 below).
386                         
387                     </para>
388                     
389                 </listitem>
390                 
391             </varlistentry>
392             
393             <varlistentry>
394                 
395                 <term>V</term>
396                 
397                 <listitem>
398                     
399                     <para>N by NCV array. (OUTPUT) </para>
400                     
401                     <para>The NCV columns of V contain the Lanczos basis vectors.</para>
402                     
403                 </listitem>
404                 
405             </varlistentry>
406             
407             <varlistentry>
408                 
409                 <term>IPARAM</term>
410                 
411                 <listitem>
412                     
413                     <para>array of length 11. (INPUT/OUTPUT)</para>
414                     
415                     <itemizedlist>
416                         
417                         <listitem>
418                             
419                             <para>
420                                 
421                                 IPARAM(1) = ISHIFT: method for selecting the implicit
422                                 
423                                 shifts. The shifts selected at each iteration are used to
424                                 
425                                 restart the Arnoldi iteration in an implicit fashion.
426                                 
427                             </para>
428                             
429                             <itemizedlist>
430                                 
431                                 <listitem>
432                                     
433                                     <para>
434                                         
435                                         ISHIFT = 0: the shifts are provided by the user via
436                                         
437                                         reverse communication. The NCV eigenvalues of the current
438                                         
439                                         tridiagonal matrix T are returned in the part of WORKL array
440                                         
441                                         corresponding to RITZ. See remark 6 below.
442                                         
443                                     </para>
444                                     
445                                 </listitem>
446                                 
447                                 <listitem>
448                                     
449                                     <para>
450                                         
451                                         ISHIFT = 1: exact shifts with respect to the reduced
452                                         
453                                         tridiagonal matrix T. This is equivalent to restarting the
454                                         
455                                         iteration with a starting vector that is a linear
456                                         
457                                         combination of Ritz vectors associated with the "wanted"
458                                         
459                                         Ritz values.
460                                         
461                                     </para>
462                                     
463                                 </listitem>
464                                 
465                             </itemizedlist>
466                             
467                         </listitem>
468                         
469                         <listitem>
470                             
471                             <para>
472                                 
473                                 IPARAM(2) = LEVEC. No longer referenced. See remark 2
474                                 
475                                 below.
476                                 
477                             </para>
478                             
479                         </listitem>
480                         
481                         <listitem>
482                             
483                             <para>IPARAM(3) = MXITER </para>
484                             
485                             <para>
486                                 
487                                 On INPUT: maximum number of Arnoldi update iterations
488                                 
489                                 allowed.
490                                 
491                             </para>
492                             
493                             <para>
494                                 
495                                 On OUTPUT: actual number of Arnoldi update iterations
496                                 
497                                 taken.
498                                 
499                             </para>
500                             
501                         </listitem>
502                         
503                         <listitem>
504                             
505                             <para>
506                                 
507                                 IPARAM(4) = NB: blocksize to be used in the recurrence.
508                                 
509                                 The code currently works only for NB = 1.
510                                 
511                             </para>
512                             
513                         </listitem>
514                         
515                         <listitem>
516                             
517                             <para>
518                                 
519                                 IPARAM(5) = NCONV: number of "converged" Ritz values. This
520                                 
521                                 represents the number of Ritz values that satisfy the
522                                 
523                                 convergence criterion.
524                                 
525                             </para>
526                             
527                         </listitem>
528                         
529                         <listitem>
530                             
531                             <para>
532                                 
533                                 IPARAM(6) = IUPD No longer referenced. Implicit restarting
534                                 
535                                 is ALWAYS used.
536                                 
537                             </para>
538                             
539                         </listitem>
540                         
541                         <listitem>
542                             
543                             <para>
544                                 
545                                 IPARAM(7) = MODE On INPUT determines what type of
546                                 
547                                 eigenproblem is being solved. Must be 1,2,3,4,5; See under
548                                 
549                                 Description of dsaupd for the five modes available.
550                                 
551                             </para>
552                             
553                         </listitem>
554                         
555                         <listitem>
556                             
557                             <para>
558                                 
559                                 IPARAM(8) = NP When ido = 3 and the user provides shifts
560                                 
561                                 through reverse communication (IPARAM(1)=0), dsaupd returns NP,
562                                 
563                                 the number of shifts the user is to provide. 0 &lt; NP &lt;=
564                                 
565                                 NCV-NEV. See Remark 6 below.
566                                 
567                             </para>
568                             
569                         </listitem>
570                         
571                         <listitem>
572                             
573                             <para>IPARAM(9) = NUMOP, </para>
574                             
575                             <para>IPARAM(10) = NUMOPB, </para>
576                             
577                             <para>
578                                 
579                                 IPARAM(11) = NUMREO, OUTPUT: NUMOP = total number of OP*x
580                                 
581                                 operations, NUMOPB = total number of B*x operations if BMAT='G',
582                                 
583                                 NUMREO = total number of steps of re-orthogonalization.
584                                 
585                             </para>
586                             
587                         </listitem>
588                         
589                     </itemizedlist>
590                     
591                 </listitem>
592                 
593             </varlistentry>
594             
595             <varlistentry>
596                 
597                 <term>IPNTR</term>
598                 
599                 <listitem>
600                     
601                     <para>
602                         
603                         array of length 11. (OUTPUT)
604                         
605                     </para>
606                     
607                     <para>
608                         
609                         Pointer to mark the starting locations in
610                         
611                         the WORKD and WORKL arrays for matrices/vectors used by the Lanczos
612                         
613                         iteration.
614                         
615                     </para>
616                     
617                     <itemizedlist>
618                         
619                         <listitem>
620                             
621                             <para>
622                                 
623                                 IPNTR(1): pointer to the current operand vector X in
624                                 
625                                 WORKD.
626                                 
627                             </para>
628                             
629                         </listitem>
630                         
631                         <listitem>
632                             
633                             <para>
634                                 
635                                 IPNTR(2): pointer to the current result vector Y in
636                                 
637                                 WORKD.
638                                 
639                             </para>
640                             
641                         </listitem>
642                         
643                         <listitem>
644                             
645                             <para>
646                                 
647                                 IPNTR(3): pointer to the vector B * X in WORKD when used
648                                 
649                                 in the shift-and-invert mode.
650                                 
651                             </para>
652                             
653                         </listitem>
654                         
655                         <listitem>
656                             
657                             <para>
658                                 
659                                 IPNTR(4): pointer to the next available location in WORKL
660                                 
661                                 that is untouched by the program.
662                                 
663                             </para>
664                             
665                         </listitem>
666                         
667                         <listitem>
668                             
669                             <para>
670                                 
671                                 IPNTR(5): pointer to the NCV by 2 tridiagonal matrix T in
672                                 
673                                 WORKL.
674                                 
675                             </para>
676                             
677                         </listitem>
678                         
679                         <listitem>
680                             
681                             <para>
682                                 
683                                 IPNTR(6): pointer to the NCV RITZ values array in
684                                 
685                                 WORKL.
686                                 
687                             </para>
688                             
689                         </listitem>
690                         
691                         <listitem>
692                             
693                             <para>
694                                 
695                                 IPNTR(7): pointer to the Ritz estimates in array WORKL
696                                 
697                                 associated with the Ritz values located in RITZ in WORKL.
698                                 
699                             </para>
700                             
701                         </listitem>
702                         
703                         <listitem>
704                             
705                             <para>
706                                 
707                                 IPNTR(11): pointer to the NP shifts in WORKL. See Remark 6
708                                 
709                                 below.
710                                 
711                             </para>
712                             
713                         </listitem>
714                         
715                     </itemizedlist>
716                     
717                     <para>
718                         
719                         Note: IPNTR(8:10) is only referenced by dseupd . See Remark
720                         
721                         2.
722                         
723                     </para>
724                     
725                     <itemizedlist>
726                         
727                         <listitem>
728                             
729                             <para>
730                                 
731                                 IPNTR(8): pointer to the NCV RITZ values of the original
732                                 
733                                 system.
734                                 
735                             </para>
736                             
737                         </listitem>
738                         
739                         <listitem>
740                             
741                             <para>
742                                 
743                                 IPNTR(9): pointer to the NCV corresponding error
744                                 
745                                 bounds.
746                                 
747                             </para>
748                             
749                         </listitem>
750                         
751                         <listitem>
752                             
753                             <para>
754                                 
755                                 IPNTR(10): pointer to the NCV by NCV matrix of
756                                 
757                                 eigenvectors of the tridiagonal matrix T. Only referenced by
758                                 
759                                 dseupd if RVEC = 1. See Remarks
760                                 
761                             </para>
762                             
763                         </listitem>
764                         
765                     </itemizedlist>
766                     
767                 </listitem>
768                 
769             </varlistentry>
770             
771             <varlistentry>
772                 
773                 <term>WORKD</term>
774                 
775                 <listitem>
776                     
777                     <para>work array of length 3 * N. (REVERSE COMMUNICATION) </para>
778                     
779                     <para>
780                         
781                         Distributed array to be used in the basic Arnoldi iteration
782                         
783                         for reverse communication. The user should not use WORKD as
784                         
785                         temporary workspace during the iteration. Upon termination
786                         
787                         WORKD(1:N) contains B*RESID(1:N). If the Ritz vectors are desired
788                         
789                         subroutine dseupd uses this output. See Data Distribution Note
790                         
791                         below.
792                         
793                     </para>
794                     
795                 </listitem>
796                 
797             </varlistentry>
798             
799             <varlistentry>
800                 
801                 <term>WORKL</term>
802                 
803                 <listitem>
804                     
805                     <para>
806                         
807                         work array of length at least NCV ** 2 + 8 * NCV.
808                         
809                         (OUTPUT/WORKSPACE)
810                         
811                     </para>
812                     
813                     <para>
814                         
815                         Private (replicated) array on each PE or array allocated on
816                         
817                         the front end. See Data Distribution Note below. add here the
818                         
819                         parameter description.
820                         
821                     </para>
822                     
823                 </listitem>
824                 
825             </varlistentry>
826             
827             <varlistentry>
828                 
829                 <term>INFO</term>
830                 
831                 <listitem>
832                     
833                     <para>Integer. (INPUT/OUTPUT)</para>
834                     
835                     <para>
836                         
837                         If INFO = 0, a randomly initial residual vector is used, else
838                         
839                         RESID contains the initial residual vector, possibly from a previous
840                         
841                         run.
842                         
843                     </para>
844                     
845                     <para>Error flag on output.</para>
846                     
847                     <itemizedlist>
848                         
849                         <listitem>
850                             
851                             <para>0: Normal exit.</para>
852                             
853                         </listitem>
854                         
855                         <listitem>
856                             
857                             <para>
858                                 
859                                 1: Maximum number of iterations taken. All possible
860                                 
861                                 eigenvalues of OP has been found. IPARAM(5) returns the number
862                                 
863                                 of wanted converged Ritz values.
864                                 
865                             </para>
866                             
867                         </listitem>
868                         
869                         <listitem>
870                             
871                             <para>
872                                 
873                                 2: No longer an informational error. Deprecated starting
874                                 
875                                 with release 2 of ARPACK.
876                                 
877                             </para>
878                             
879                         </listitem>
880                         
881                         <listitem>
882                             
883                             <para>
884                                 
885                                 3: No shifts could be applied during a cycle of the
886                                 
887                                 Implicitly restarted Arnoldi iteration. One possibility is to
888                                 
889                                 increase the size of NCV relative to NEV. See remark 4
890                                 
891                                 below.
892                                 
893                             </para>
894                             
895                         </listitem>
896                         
897                         <listitem>
898                             
899                             <para>-1: N must be positive.</para>
900                             
901                         </listitem>
902                         
903                         <listitem>
904                             
905                             <para>-2: NEV must be positive.</para>
906                             
907                         </listitem>
908                         
909                         <listitem>
910                             
911                             <para>
912                                 
913                                 -3: NCV must be greater than NEV and less than or equal to
914                                 
915                                 N.
916                                 
917                             </para>
918                             
919                         </listitem>
920                         
921                         <listitem>
922                             
923                             <para>
924                                 
925                                 -4: The maximum number of Arnoldi update iterations
926                                 
927                                 allowed must be greater than zero.
928                                 
929                             </para>
930                             
931                         </listitem>
932                         
933                         <listitem>
934                             
935                             <para>
936                                 
937                                 -5: WHICH must be one of 'LM', 'SM', 'LA', 'SA' or
938                                 
939                                 'BE'.
940                                 
941                             </para>
942                             
943                         </listitem>
944                         
945                         <listitem>
946                             
947                             <para>-6: BMAT must be one of 'I' or 'G'.</para>
948                             
949                         </listitem>
950                         
951                         <listitem>
952                             
953                             <para>
954                                 
955                                 -7: Length of private work array WORKL is not
956                                 
957                                 sufficient.
958                                 
959                             </para>
960                             
961                         </listitem>
962                         
963                         <listitem>
964                             
965                             <para>
966                                 
967                                 -8: Error return from trid. eigenvalue calculation;
968                                 
969                                 Informatinal error from LAPACK routine dsteqr.
970                                 
971                             </para>
972                             
973                         </listitem>
974                         
975                         <listitem>
976                             
977                             <para>-9: Starting vector is zero.</para>
978                             
979                         </listitem>
980                         
981                         <listitem>
982                             
983                             <para>-10: IPARAM(7) must be 1, 2, 3, 4, 5.</para>
984                             
985                         </listitem>
986                         
987                         <listitem>
988                             
989                             <para>-11: IPARAM(7) = 1 and BMAT = 'G' are incompatable.</para>
990                             
991                         </listitem>
992                         
993                         <listitem>
994                             
995                             <para>-12: IPARAM(1) must be equal to 0 or 1.</para>
996                             
997                         </listitem>
998                         
999                         <listitem>
1000                             
1001                             <para>-13: NEV and WHICH = 'BE' are incompatable.</para>
1002                             
1003                         </listitem>
1004                         
1005                         <listitem>
1006                             
1007                             <para>
1008                                 
1009                                 -9999: Could not build an Arnoldi factorization. IPARAM(5)
1010                                 
1011                                 returns the size of the current Arnoldi factorization. The user
1012                                 
1013                                 is advised to check that enough workspace and array storage has
1014                                 
1015                                 been allocated.
1016                                 
1017                             </para>
1018                             
1019                         </listitem>
1020                         
1021                     </itemizedlist>
1022                     
1023                 </listitem>
1024                 
1025             </varlistentry>
1026             
1027         </variablelist>
1028         
1029     </refsection>
1030     
1031     <refsection>
1032         
1033         <title>Description</title>
1034         
1035         <para>
1036             
1037             Reverse communication interface for the Implicitly Restarted Arnoldi
1038             
1039             Iteration. For symmetric problems this reduces to a variant of the Lanczos
1040             
1041             method. This method has been designed to compute approximations to a few
1042             
1043             eigenpairs of a linear operator OP that is real and symmetric with respect
1044             
1045             to a real positive semi-definite symmetric matrix B, i.e.<literal>
1046                 
1047                 B * OP =
1048                 
1049                 (OP`) * B
1050                 
1051             </literal>
1052             
1053             .
1054             
1055         </para>
1056         
1057         <para>
1058             
1059             Another way to express this condition is <literal>
1060                 
1061                 &lt; x,OPy &gt; =
1062                 
1063                 &lt; OPx,y &gt; where &lt;z,w &gt; = z`Bw
1064                 
1065             </literal>
1066             
1067             .
1068             
1069         </para>
1070         
1071         <para>
1072             
1073             In the standard eigenproblem B is the identity matrix. ( A` denotes
1074             
1075             transpose of A)
1076             
1077         </para>
1078         
1079         <para>
1080             
1081             The computed approximate eigenvalues are called Ritz values and the
1082             
1083             corresponding approximate eigenvectors are called Ritz vectors.
1084             
1085         </para>
1086         
1087         <para>
1088             
1089             dsaupd is usually called iteratively to solve one of the following
1090             
1091             problems:
1092             
1093         </para>
1094         
1095         <itemizedlist>
1096             
1097             <listitem>
1098                 
1099                 <para>
1100                     
1101                     Mode 1: A * x = lambda * x, A symmetric ===&gt; OP = A and B =
1102                     
1103                     I.
1104                     
1105                 </para>
1106                 
1107             </listitem>
1108             
1109             <listitem>
1110                 
1111                 <para>
1112                     
1113                     Mode 2: A * x = lambda * M * x, A symmetric, M symmetric positive
1114                     
1115                     definite ===&gt; OP = inv[M] * A and B = M. ===&gt; (If M can be
1116                     
1117                     factored see remark 3 below)
1118                     
1119                 </para>
1120                 
1121             </listitem>
1122             
1123             <listitem>
1124                 
1125                 <para>
1126                     
1127                     Mode 3: K * x = lambda * M * x, K symmetric, M symmetric positive
1128                     
1129                     semi-definite ===&gt; OP = (inv[K - sigma * M]) * M and B = M. ===&gt;
1130                     
1131                     Shift-and-Invert mode
1132                     
1133                 </para>
1134                 
1135             </listitem>
1136             
1137             <listitem>
1138                 
1139                 <para>
1140                     
1141                     Mode 4: K * x = lambda * KG * x, K symmetric positive semi-definite,
1142                     
1143                     KG symmetric indefinite ===&gt; OP = (inv[K - sigma * KG]) * K and B = K.
1144                     
1145                     ===&gt; Buckling mode
1146                     
1147                 </para>
1148                 
1149             </listitem>
1150             
1151             <listitem>
1152                 
1153                 <para>
1154                     
1155                     Mode 5: A * x = lambda * M * x, A symmetric, M symmetric positive
1156                     
1157                     semi-definite ===&gt; OP = inv[A - sigma * M] * [A + sigma * M] and B = M.
1158                     
1159                     ===&gt; Cayley transformed mode
1160                     
1161                 </para>
1162                 
1163             </listitem>
1164             
1165         </itemizedlist>
1166         
1167         <para>
1168             
1169             NOTE: The action of w &lt;- inv[A - sigma * M] * v or w &lt;- inv[M] * v
1170             
1171             should be accomplished either by a direct method using a sparse matrix
1172             
1173             factorization and solving <literal>
1174                 
1175                 [A - sigma * M] * w = v or M * w =
1176                 
1177                 v
1178                 
1179             </literal>
1180             
1181             ,
1182             
1183         </para>
1184         
1185         <para>
1186             
1187             or through an iterative method for solving these systems. If an
1188             
1189             iterative method is used, the convergence test must be more stringent than
1190             
1191             the accuracy requirements for the eigenvalue approximations.
1192             
1193         </para>
1194         
1195     </refsection>
1196     
1197     <refsection>
1198         
1199         <title>Remarks</title>
1200         
1201         <para>
1202             
1203             1. The converged Ritz values are always returned in ascending
1204             
1205             algebraic order. The computed Ritz values are approximate eigenvalues of
1206             
1207             OP. The selection of WHICH should be made with this in mind when Mode =
1208             
1209             3, 4, 5. After convergence, approximate eigenvalues of the original problem
1210             
1211             may be obtained with the ARPACK subroutine dseupd .
1212             
1213         </para>
1214         
1215         <para>
1216             
1217             2. If the Ritz vectors corresponding to the converged Ritz values
1218             
1219             are needed, the user must call dseupd immediately following completion of
1220             
1221             dsaupd . This is new starting with version 2.1 of ARPACK.
1222             
1223         </para>
1224         
1225         <para>
1226             
1227             3. If M can be factored into a Cholesky factorization M = LL` then
1228             
1229             Mode = 2 should not be selected. Instead one should use Mode = 1 with OP =
1230             
1231             inv(L) * A * inv(L`). Appropriate triangular linear systems should be solved
1232             
1233             with L and L` rather than computing inverses. After convergence, an
1234             
1235             approximate eigenvector z of the original problem is recovered by solving
1236             
1237             L`z = x where x is a Ritz vector of OP.
1238             
1239         </para>
1240         
1241         <para>
1242             
1243             4. At present there is no a-priori analysis to guide the selection
1244             
1245             of NCV relative to NEV. The only formal requirement is that NCV &gt; NEV.
1246             
1247             However, it is recommended that NCV &gt;= 2 * NEV. If many problems of the
1248             
1249             same type are to be solved, one should experiment with increasing NCV
1250             
1251             while keeping NEV fixed for a given test problem. This will usually
1252             
1253             decrease the required number of OP * x operations but it also increases the
1254             
1255             work and storage required to maintain the orthogonal basis vectors. The
1256             
1257             optimal "cross-over" with respect to CPU time is problem dependent and
1258             
1259             must be determined empirically.
1260             
1261         </para>
1262         
1263         <para>
1264             
1265             5. If IPARAM(7) = 2 then in the Reverse communication interface the
1266             
1267             user must do the following. When IDO = 1, Y = OP * X is to be computed.
1268             
1269             When IPARAM(7) = 2 OP = inv(B) * A. After computing A * X the user must
1270             
1271             overwrite X with A * X. Y is then the solution to the linear set of
1272             
1273             equations B * Y = A * X.
1274             
1275         </para>
1276         
1277         <para>
1278             
1279             6. When IPARAM(1) = 0, and IDO = 3, the user needs to provide the NP
1280             
1281             = IPARAM(8) shifts in locations: 1 WORKL(IPNTR(11)) 2 WORKL(IPNTR(11) + 1) .
1282             
1283             . . NP WORKL(IPNTR(11) + NP - 1). The eigenvalues of the current tridiagonal
1284             
1285             matrix are located in WORKL(IPNTR(6)) through WORKL(IPNTR(6) + NCV - 1). They
1286             
1287             are in the order defined by WHICH. The associated Ritz estimates are
1288             
1289             located in WORKL(IPNTR(8)), WORKL(IPNTR(8) + 1), ... ,
1290             
1291             WORKL(IPNTR(8) + NCV - 1).
1292             
1293         </para>
1294         
1295     </refsection>
1296     
1297     <refsection>
1298         
1299         <title>Example</title>
1300         
1301         <programlisting role="example">
1302             
1303             <![CDATA[
1304
1305 // The following sets dimensions for this problem.
1306
1307 nx    = 10;
1308
1309 nev   = 3;
1310 ncv   = 6;
1311 bmat  = 'I';
1312 which = 'LM';
1313
1314 // Local Arrays
1315
1316 iparam  = zeros(11, 1);
1317 ipntr   = zeros(14, 1);
1318 _select = zeros(ncv, 1);
1319 d       = zeros(nev, 1);
1320 z       = zeros(nx, nev);
1321 resid   = zeros(nx, 1);
1322 v       = zeros(nx, ncv);
1323 workd   = zeros(3 * nx, 1);
1324 workl   = zeros(ncv * ncv + 8 * ncv, 1);
1325
1326 // Build the symmetric test matrix
1327
1328 A            = diag(10 * ones(nx,1));
1329 A(1:$-1,2:$) = A(1:$-1,2:$) + diag(6 * ones(nx-1,1));
1330 A(2:$,1:$-1) = A(2:$,1:$-1) + diag(6 * ones(nx-1,1));
1331
1332 tol    = 0;
1333 ido    = 0;
1334
1335 ishfts = 1;
1336 maxitr = 300;
1337 mode1  = 1;
1338
1339 iparam(1) = ishfts;
1340 iparam(3) = maxitr;
1341 iparam(7) = mode1;
1342
1343 sigma = 0; // the real part of the shift
1344 info_dsaupd = 0;
1345
1346 // M A I N   L O O P (Reverse communication)
1347
1348 while(ido <> 99)
1349   // Repeatedly call the routine DSAUPD and take actions indicated by parameter IDO until
1350   // either convergence is indicated or maxitr has been exceeded.
1351
1352   [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);
1353
1354   if(info_dsaupd < 0)
1355     printf('\nError with dsaupd, info = %d\n',info_dsaupd);
1356     printf('Check the documentation of dsaupd\n\n');
1357   end
1358
1359   if(ido == -1 | ido == 1)
1360     // Perform matrix vector multiplication
1361     workd(ipntr(2):ipntr(2) + nx - 1) = A * workd(ipntr(1):ipntr(1) + nx - 1);
1362   end
1363 end
1364
1365 // Post-Process using DSEUPD.
1366 rvec    = 1;
1367 howmany = 'A';
1368 info_dseupd = 0;
1369
1370 [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, ...
1371                                                                     iparam, ipntr, workd, workl, info_dseupd);
1372
1373 if(info_dseupd < 0)
1374   printf('\nError with dseupd, info = %d\n', info_dseupd);
1375   printf('Check the documentation of dseupd.\n\n');
1376 end
1377
1378
1379 // Done with program dssimp.
1380 printf('\nDSSIMP\n');
1381 printf('======\n');
1382 printf('\n');
1383 printf('Size of the matrix is %d\n', nx);
1384 printf('The number of Ritz values requested is %d\n', nev);
1385 printf('The number of Arnoldi vectors generated (NCV) is %d\n', ncv);
1386 printf('What portion of the spectrum: %s\n', which);
1387 printf('The number of Implicit Arnoldi update iterations taken is %d\n', iparam(3));
1388 printf('The number of OP*x is %d\n', iparam(9));
1389 printf('The convergence criterion is %d\n', tol);
1390
1391 ]]>
1392             
1393         </programlisting>
1394         
1395     </refsection>
1396     
1397     <refsection role="see also">
1398         
1399         <title>See Also</title>
1400         
1401         <simplelist type="inline">
1402             
1403             <member>
1404                 
1405                 <link linkend="dnaupd">dnaupd</link>
1406                 
1407             </member>
1408             
1409             <member>
1410                 
1411                 <link linkend="dseupd">dseupd</link>
1412                 
1413             </member>
1414             
1415         </simplelist>
1416         
1417     </refsection>
1418     
1419     <refsection>
1420         
1421         <title>Bibliography</title>
1422         
1423         <para>
1424             
1425             1. D.C. Sorensen, "Implicit Application of Polynomial Filters in a
1426             
1427             k-Step Arnoldi Method", SIAM J. Matr. Anal. Apps., 13 (1992), pp
1428             
1429             357-385.
1430             
1431         </para>
1432         
1433         <para>
1434             
1435             2. R.B. Lehoucq, "Analysis and Implementation of an Implicitly
1436             
1437             Restarted Arnoldi Iteration", Rice University Technical Report TR95-13,
1438             
1439             Department of Computational and Applied Mathematics.
1440             
1441         </para>
1442         
1443         <para>
1444             
1445             3. B.N. Parlett and Y. Saad, "Complex Shift and Invert Strategies
1446             
1447             for Real Matrices", Linear Algebra and its Applications, vol 88/89, pp
1448             
1449             575-595, (1987).
1450             
1451         </para>
1452         
1453     </refsection>
1454     
1455     <refsection>
1456         
1457         <title>Used Functions</title>
1458         
1459         <para>Based on ARPACK routine dsaupd</para>
1460         
1461     </refsection>
1462     
1463     <refsection>
1464         
1465         <title>履歴</title>
1466         
1467         <revhistory>
1468             
1469             <revision>
1470                 
1471                 <revnumber>5.4.0</revnumber>
1472                 
1473                 <revremark>
1474                     
1475                     関数は廃止され,<link linkend="eigs">eigs</link>に代替されました.
1476                     
1477                 </revremark>
1478                 
1479             </revision>
1480             
1481         </revhistory>
1482         
1483     </refsection>
1484     
1485 </refentry>
1486