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