added japanese translation of arnoldi module.
[scilab.git] / scilab / modules / arnoldi / help / ja_JP / zneupd.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="zneupd" xml:lang="ja">
4     
5     <refnamediv>
6         
7         <refname>zneupd</refname>
8         
9         <refpurpose>
10             
11             暗黙のうちに再開されるArnoldi反復へのインターフェイスで,
12             
13             A * z = lambda * B * z の固有値を収束的近似により計算します.
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>
30             
31             [D, Z, RESID, IPARAM, IPNTR, WORKD, WORKL, RWORK, INFO] = zneupd(RVEC, HOWMANY, SELECT, D, Z, SIGMA, WORKev,
32             
33             BMAT, N, WHICH, NEV, TOL, RESID, NCV, V, IPARAM, IPNTR, WORKD, WORKL, RWORK, INFO)
34             
35         </synopsis>
36         
37     </refsynopsisdiv>
38     
39     <refsection>
40         
41         <title>Arguments</title>
42         
43         <variablelist>
44             
45             <varlistentry>
46                 
47                 <term>RVEC</term>
48                 
49                 <listitem>
50                     
51                     <para>Integer. (INPUT) </para>
52                     
53                     <para>
54                         
55                         Specifies whether a basis for the invariant subspace
56                         
57                         corresponding to the converged Ritz value approximations for the
58                         
59                         eigenproblem A * z = lambda * B * z is computed.
60                         
61                     </para>
62                     
63                     <itemizedlist>
64                         
65                         <listitem>
66                             
67                             <para>RVEC = 0 Compute Ritz values only.</para>
68                             
69                         </listitem>
70                         
71                         <listitem>
72                             
73                             <para>
74                                 
75                                 RVEC = 1 Compute Ritz vectors or Schur vectors. See
76                                 
77                                 Remarks below.
78                                 
79                             </para>
80                             
81                         </listitem>
82                         
83                     </itemizedlist>
84                     
85                 </listitem>
86                 
87             </varlistentry>
88             
89             <varlistentry>
90                 
91                 <term>HOWMANY</term>
92                 
93                 <listitem>
94                     
95                     <para>Character. (INPUT) </para>
96                     
97                     <para>
98                         
99                         Specifies the form of the basis for the invariant subspace
100                         
101                         corresponding to the converged Ritz values that is to be computed.
102                         
103                     </para>
104                     
105                     <itemizedlist>
106                         
107                         <listitem>
108                             
109                             <para>'A': Compute NEV Ritz vectors;</para>
110                             
111                         </listitem>
112                         
113                         <listitem>
114                             
115                             <para>'P': Compute NEV Schur vectors;</para>
116                             
117                         </listitem>
118                         
119                         <listitem>
120                             
121                             <para>
122                                 
123                                 'S': compute some of the Ritz vectors, specified by the
124                                 
125                                 integer array SELECT.
126                                 
127                             </para>
128                             
129                         </listitem>
130                         
131                     </itemizedlist>
132                     
133                 </listitem>
134                 
135             </varlistentry>
136             
137             <varlistentry>
138                 
139                 <term>SELECT</term>
140                 
141                 <listitem>
142                     
143                     <para>Integer array of dimension NCV. (INPUT) </para>
144                     
145                     <para>
146                         
147                         If HOWMANY = 'S', SELECT specifies the Ritz vectors to be
148                         
149                         computed. To select the Ritz vector corresponding to a Ritz value
150                         
151                         D(j), SELECT(j) must be set to 1.
152                         
153                     </para>
154                     
155                     <para>
156                         
157                         If HOWMANY = 'A' or 'P', SELECT need not be initialized but it
158                         
159                         is used as internal workspace.
160                         
161                     </para>
162                     
163                 </listitem>
164                 
165             </varlistentry>
166             
167             <varlistentry>
168                 
169                 <term>D</term>
170                 
171                 <listitem>
172                     
173                     <para>Complex*16 array of dimension NEV + 1. (OUTPUT) </para>
174                     
175                     <para>
176                         
177                         On exit, D contains the Ritz approximations to the eigenvalues
178                         
179                         lambda for A * z = lambda * B * z.
180                         
181                     </para>
182                     
183                 </listitem>
184                 
185             </varlistentry>
186             
187             <varlistentry>
188                 
189                 <term>Z</term>
190                 
191                 <listitem>
192                     
193                     <para>Complex*16 N by NEV array. (OUTPUT) </para>
194                     
195                     <para>On exit, </para>
196                     
197                     <para>
198                         
199                         If RVEC = 1 and HOWMANY = 'A', then the columns of Z
200                         
201                         represents approximate eigenvectors (Ritz vectors) corresponding to
202                         
203                         the NCONV = IPARAM(5) Ritz values for eigensystem A * z = lambda * B * z.
204                         
205                     </para>
206                     
207                     <para>
208                         
209                         If RVEC = 0 or HOWMANY = 'P', then Z is NOT REFERENCED.
210                         
211                     </para>
212                     
213                     <para>
214                         
215                         NOTE: If if RVEC = 1 and a Schur basis is not required, the
216                         
217                         array Z may be set equal to first NEV+1 columns of the Arnoldi basis
218                         
219                         array V computed by ZNAUPD. In this case the Arnoldi basis will be
220                         
221                         destroyed and overwritten with the eigenvector basis.
222                         
223                     </para>
224                     
225                 </listitem>
226                 
227             </varlistentry>
228             
229             <varlistentry>
230                 
231                 <term>SIGMA</term>
232                 
233                 <listitem>
234                     
235                     <para>Complex*16. (INPUT) </para>
236                     
237                     <para>If IPARAM(7) = 3 then SIGMA represents the shift. </para>
238                     
239                     <para>Not referenced if IPARAM(7) = 1 or 2.</para>
240                     
241                 </listitem>
242                 
243             </varlistentry>
244             
245             <varlistentry>
246                 
247                 <term>WORKev</term>
248                 
249                 <listitem>
250                     
251                     <para>Complex*16 work array of dimension 2 * NCV. (WORKSPACE)</para>
252                     
253                 </listitem>
254                 
255             </varlistentry>
256             
257         </variablelist>
258         
259         <para>
260             
261             NOTE: The remaining arguments BMAT, N, WHICH, NEV, TOL, RESID, NCV,
262             
263             V, IPARAM, IPNTR, WORKD, WORKL, LWORKL, RWORK, INFO must be passed
264             
265             directly to ZNEUPD following the last call to ZNAUPD.
266             
267         </para>
268         
269         <para>
270             
271             These arguments MUST NOT BE MODIFIED between the last call to
272             
273             ZNAUPD and the call to ZNEUPD.
274             
275         </para>
276         
277         <para>
278             
279             Three of these parameters (V, WORKL and INFO) are also output
280             
281             parameters.
282             
283         </para>
284         
285         <variablelist>
286             
287             <varlistentry>
288                 
289                 <term>V</term>
290                 
291                 <listitem>
292                     
293                     <para>Complex*16 N by NCV array. (INPUT/OUTPUT) </para>
294                     
295                     <para>
296                         
297                         Upon INPUT: the NCV columns of V contain the Arnoldi basis
298                         
299                         vectors for OP as constructed by ZNAUPD.
300                         
301                     </para>
302                     
303                     <para>
304                         
305                         Upon OUTPUT: If RVEC = 1 the first NCONV = IPARAM(5) columns
306                         
307                         contain approximate Schur vectors that span the desired invariant
308                         
309                         subspace.
310                         
311                     </para>
312                     
313                     <para>
314                         
315                         NOTE: If the array Z has been set equal to first NEV+1 columns
316                         
317                         of the array V and RVEC = 1 and HOWMANY = 'A', then the Arnoldi basis
318                         
319                         held by V has been overwritten by the desired Ritz vectors. If a
320                         
321                         separate array Z has been passed then the first NCONV=IPARAM(5)
322                         
323                         columns of V will contain approximate Schur vectors that span the
324                         
325                         desired invariant subspace.
326                         
327                     </para>
328                     
329                 </listitem>
330                 
331             </varlistentry>
332             
333             <varlistentry>
334                 
335                 <term>WORKL</term>
336                 
337                 <listitem>
338                     
339                     <para>
340                         
341                         Double precision work array of length LWORKL.
342                         
343                         (OUTPUT/WORKSPACE)
344                         
345                     </para>
346                     
347                     <para>
348                         
349                         WORKL(1:ncv * ncv + 2 * ncv) contains information obtained in
350                         
351                         znaupd. They are not changed by zneupd.
352                         
353                     </para>
354                     
355                     <para>
356                         
357                         WORKL(ncv * ncv + 2 * ncv + 1:3 * ncv * ncv + 4 * ncv) holds the untransformed
358                         
359                         Ritz values, the untransformed error estimates of the Ritz values,
360                         
361                         the upper triangular matrix for H, and the associated matrix
362                         
363                         representation of the invariant subspace for H.
364                         
365                     </para>
366                     
367                     <para>
368                         
369                         Note: IPNTR(9:13) contains the pointer into WORKL for
370                         
371                         addresses of the above information computed by zneupd.
372                         
373                     </para>
374                     
375                     <itemizedlist>
376                         
377                         <listitem>
378                             
379                             <para>
380                                 
381                                 IPNTR(9): pointer to the NCV RITZ values of the original
382                                 
383                                 system.
384                                 
385                             </para>
386                             
387                         </listitem>
388                         
389                         <listitem>
390                             
391                             <para>IPNTR(10): Not used </para>
392                             
393                         </listitem>
394                         
395                         <listitem>
396                             
397                             <para>
398                                 
399                                 IPNTR(11): pointer to the NCV corresponding error
400                                 
401                                 estimates.
402                                 
403                             </para>
404                             
405                         </listitem>
406                         
407                         <listitem>
408                             
409                             <para>
410                                 
411                                 IPNTR(12): pointer to the NCV by NCV upper triangular
412                                 
413                                 Schur matrix for H.
414                                 
415                             </para>
416                             
417                         </listitem>
418                         
419                         <listitem>
420                             
421                             <para>
422                                 
423                                 IPNTR(13): pointer to the NCV by NCV matrix of
424                                 
425                                 eigenvectors of the upper Hessenberg matrix H. Only referenced
426                                 
427                                 by zneupd if RVEC = 1 See Remark 2 below.
428                                 
429                             </para>
430                             
431                         </listitem>
432                         
433                     </itemizedlist>
434                     
435                 </listitem>
436                 
437             </varlistentry>
438             
439             <varlistentry>
440                 
441                 <term>INFO</term>
442                 
443                 <listitem>
444                     
445                     <para>Integer. (OUTPUT) </para>
446                     
447                     <para>Error flag on output.</para>
448                     
449                     <itemizedlist>
450                         
451                         <listitem>
452                             
453                             <para>0: Normal exit.</para>
454                             
455                         </listitem>
456                         
457                         <listitem>
458                             
459                             <para>
460                                 
461                                 1: The Schur form computed by LAPACK routine csheqr could
462                                 
463                                 not be reordered by LAPACK routine ztrsen. Re-enter subroutine
464                                 
465                                 zneupd with IPARAM(5) = NCV and increase the size of the array D
466                                 
467                                 to have dimension at least dimension NCV and allocate at least
468                                 
469                                 NCV columns for Z.
470                                 
471                             </para>
472                             
473                             <para>
474                                 
475                                 NOTE: Not necessary if Z and V share the same space.
476                                 
477                                 Please notify the authors if this error occurs.
478                                 
479                             </para>
480                             
481                         </listitem>
482                         
483                         <listitem>
484                             
485                             <para>-1: N must be positive.</para>
486                             
487                         </listitem>
488                         
489                         <listitem>
490                             
491                             <para>-2: NEV must be positive.</para>
492                             
493                         </listitem>
494                         
495                         <listitem>
496                             
497                             <para>-3: NCV-NEV &gt;= 1 and less than or equal to N.</para>
498                             
499                         </listitem>
500                         
501                         <listitem>
502                             
503                             <para>
504                                 
505                                 -5: WHICH must be one of 'LM', 'SM', 'LR', 'SR', 'LI',
506                                 
507                                 'SI'.
508                                 
509                             </para>
510                             
511                         </listitem>
512                         
513                         <listitem>
514                             
515                             <para>-6: BMAT must be one of 'I' or 'G'.</para>
516                             
517                         </listitem>
518                         
519                         <listitem>
520                             
521                             <para>
522                                 
523                                 -7: Length of private work WORKL array is not
524                                 
525                                 sufficient.
526                                 
527                             </para>
528                             
529                         </listitem>
530                         
531                         <listitem>
532                             
533                             <para>
534                                 
535                                 -8: Error return from LAPACK eigenvalue calculation. This
536                                 
537                                 should never happened.
538                                 
539                             </para>
540                             
541                         </listitem>
542                         
543                         <listitem>
544                             
545                             <para>
546                                 
547                                 -9: Error return from calculation of eigenvectors.
548                                 
549                                 Informational error from LAPACK routine ztrevc.
550                                 
551                             </para>
552                             
553                         </listitem>
554                         
555                         <listitem>
556                             
557                             <para>-10: IPARAM(7) must be 1, 2, 3.</para>
558                             
559                         </listitem>
560                         
561                         <listitem>
562                             
563                             <para>-11: IPARAM(7) = 1 and BMAT = 'G' are incompatible.</para>
564                             
565                         </listitem>
566                         
567                         <listitem>
568                             
569                             <para>-12: HOWMANY = 'S' not yet implemented.</para>
570                             
571                         </listitem>
572                         
573                         <listitem>
574                             
575                             <para>
576                                 
577                                 -13: HOWMANY must be one of 'A' or 'P' if RVEC = .true.
578                                 
579                             </para>
580                             
581                         </listitem>
582                         
583                         <listitem>
584                             
585                             <para>
586                                 
587                                 -14: ZNAUPD did not find any eigenvalues to sufficient
588                                 
589                                 accuracy.
590                                 
591                             </para>
592                             
593                         </listitem>
594                         
595                         <listitem>
596                             
597                             <para>
598                                 
599                                 -15: ZNEUPD got a different count of the number of
600                                 
601                                 converged Ritz values than ZNAUPD got. This indicates the user
602                                 
603                                 probably made an error in passing data from ZNAUPD to ZNEUPD or
604                                 
605                                 that the data was modified before entering ZNEUPD.
606                                 
607                             </para>
608                             
609                         </listitem>
610                         
611                     </itemizedlist>
612                     
613                 </listitem>
614                 
615             </varlistentry>
616             
617         </variablelist>
618         
619     </refsection>
620     
621     <refsection>
622         
623         <title>Description</title>
624         
625         <para>
626             
627             This subroutine returns the converged approximations to eigenvalues
628             
629             of A * z = lambda * B * z and (optionally):
630             
631         </para>
632         
633         <orderedlist>
634             
635             <listitem>
636                 
637                 <para>The corresponding approximate eigenvectors; </para>
638                 
639             </listitem>
640             
641             <listitem>
642                 
643                 <para>
644                     
645                     An orthonormal basis for the associated approximate invariant
646                     
647                     subspace;
648                     
649                 </para>
650                 
651             </listitem>
652             
653             <listitem>
654                 
655                 <para>Both.</para>
656                 
657             </listitem>
658             
659         </orderedlist>
660         
661         <para>
662             
663             There is negligible additional cost to obtain eigenvectors. An
664             
665             orthonormal basis is always computed.
666             
667         </para>
668         
669         <para>
670             
671             There is an additional storage cost of n*nev if both are requested
672             
673             (in this case a separate array Z must be supplied).
674             
675         </para>
676         
677         <para>
678             
679             The approximate eigenvalues and eigenvectors of A * z = lambda * B * z are
680             
681             derived from approximate eigenvalues and eigenvectors of of the linear
682             
683             operator OP prescribed by the MODE selection in the call to ZNAUPD.
684             
685         </para>
686         
687         <para>ZNAUPD must be called before this routine is called. </para>
688         
689         <para>
690             
691             These approximate eigenvalues and vectors are commonly called Ritz
692             
693             values and Ritz vectors respectively. They are referred to as such in the
694             
695             comments that follow.
696             
697         </para>
698         
699         <para>
700             
701             The computed orthonormal basis for the invariant subspace
702             
703             corresponding to these Ritz values is referred to as a Schur basis.
704             
705         </para>
706         
707         <para>
708             
709             The definition of OP as well as other terms and the relation of
710             
711             computed Ritz values and vectors of OP with respect to the given problem
712             
713             A*z = lambda*B*z may be found in the header of ZNAUPD. For a brief
714             
715             description, see definitions of IPARAM(7), MODE and WHICH in the
716             
717             documentation of ZNAUPD.
718             
719         </para>
720         
721     </refsection>
722     
723     <refsection>
724         
725         <title>Remarks</title>
726         
727         <orderedlist>
728             
729             <listitem>
730                 
731                 <para>Currently only HOWMNY = 'A' and 'P' are implemented. </para>
732                 
733             </listitem>
734             
735             <listitem>
736                 
737                 <para>
738                     
739                     Schur vectors are an orthogonal representation for the basis of
740                     
741                     Ritz vectors. Thus, their numerical properties are often superior.
742                     
743                 </para>
744                 
745                 <para>If RVEC = 1 then the relationship </para>
746                 
747                 <para>A * V(:,1:IPARAM(5)) = V(:,1:IPARAM(5)) * T, </para>
748                 
749                 <para>and </para>
750                 
751                 <para>transpose( V(:,1:IPARAM(5)) ) * V(:,1:IPARAM(5)) = I </para>
752                 
753                 <para>
754                     
755                     are approximately satisfied. Here T is the leading submatrix of
756                     
757                     order IPARAM(5) of the upper triangular matrix stored
758                     
759                     workl(ipntr(12)).
760                     
761                 </para>
762                 
763             </listitem>
764             
765         </orderedlist>
766         
767     </refsection>
768     
769     <refsection>
770         
771         <title>Example</title>
772         
773         <programlisting role="example">
774             
775             <![CDATA[
776 // The following sets dimensions for this problem.
777
778 nx    = 10;
779
780 nev   = 3;
781 ncv   = 6;
782 bmat  = 'I';
783 which = 'LM';
784
785 // Local Arrays
786
787 iparam  = zeros(11, 1);
788 ipntr   = zeros(14, 1);
789 _select = zeros(ncv, 1);
790 d       = zeros(nev + 1, 1) + 0 * %i;
791 z       = zeros(nx, nev) + 0* %i;
792 resid   = zeros(nx, 1) + 0 * %i;
793 v       = zeros(nx, ncv) + 0 * %i;
794 workd   = zeros(3 * nx, 1) + 0 * %i;
795 workev  = zeros(2 * ncv, 1) + 0 * %i;
796 rwork   = zeros(ncv, 1);
797 workl   = zeros(3 * ncv * ncv + 5 *ncv, 1) + 0 * %i;
798
799 // Build the complex test matrix
800 A            = diag(10 * ones(nx,1) + %i * ones(nx,1));
801 A(1:$-1,2:$) = A(1:$-1,2:$) + diag(6 * ones(nx - 1,1));
802 A(2:$,1:$-1) = A(2:$,1:$-1) + diag(-6 * ones(nx - 1,1));
803
804 tol    = 0;
805 ido    = 0;
806
807 ishfts = 1;
808 maxitr = 300;
809 mode1  = 1;
810
811 iparam(1) = ishfts;
812 iparam(3) = maxitr;
813 iparam(7) = mode1;
814
815 sigma = complex(0);
816 info_znaupd = 0;
817 // M A I N   L O O P (Reverse communication)
818 while(ido <> 99)
819   // Repeatedly call the routine ZNAUPD and take actions indicated by parameter IDO until
820   // either convergence is indicated or maxitr has been exceeded.
821
822   [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);
823
824   if(info_znaupd < 0)
825     printf('\nError with znaupd, info = %d\n', info_znaupd);
826     printf('Check the documentation of znaupd\n\n');
827   end
828
829   if(ido == -1 | ido == 1)
830     // Perform matrix vector multiplication
831     workd(ipntr(2):ipntr(2) + nx - 1) = A * workd(ipntr(1):ipntr(1) + nx - 1);
832   end
833 end
834
835 // Post-Process using ZNEUPD.
836
837 rvec    = 1;
838 howmany = 'A';
839 info_zneupd = 0;
840
841 [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, ...
842                                                                     iparam, ipntr, workd, workl, rwork, info_zneupd);
843
844 if(info_zneupd < 0)
845   printf('\nError with zneupd, info = %d\n', info_zneupd);
846   printf('Check the documentation of zneupd.\n\n');
847 end
848
849 // Done with program znsimp.
850 printf('\nZNSIMP\n');
851 printf('======\n');
852 printf('\n');
853 printf('Size of the matrix is %d\n', nx);
854 printf('The number of Ritz values requested is %d\n', nev);
855 printf('The number of Arnoldi vectors generated (NCV) is %d\n', ncv);
856 printf('What portion of the spectrum: %s\n', which);
857 printf('The number of Implicit Arnoldi update iterations taken is %d\n', iparam(3));
858 printf('The number of OP*x is %d\n', iparam(9));
859 printf('The convergence criterion is %d\n', tol);
860
861 ]]>
862             
863         </programlisting>
864         
865     </refsection>
866     
867     <refsection role="see also">
868         
869         <title>See Also</title>
870         
871         <simplelist type="inline">
872             
873             <member>
874                 
875                 <link linkend="dnaupd">znaupd</link>
876                 
877             </member>
878             
879             <member>
880                 
881                 <link linkend="dnaupd">dnaupd</link>
882                 
883             </member>
884             
885             <member>
886                 
887                 <link linkend="dnaupd">dneupd</link>
888                 
889             </member>
890             
891         </simplelist>
892         
893     </refsection>
894     
895     <refsection>
896         
897         <title>Bibliography</title>
898         
899         <para>
900             
901             1. D.C. Sorensen, "Implicit Application of Polynomial Filters in a
902             
903             k-Step Arnoldi Method", SIAM J. Matr. Anal. Apps., 13 (1992), pp
904             
905             357-385.
906             
907         </para>
908         
909         <para>
910             
911             2. R.B. Lehoucq, "Analysis and Implementation of an Implicitly
912             
913             Restarted Arnoldi Iteration", Rice University Technical Report TR95-13,
914             
915             Department of Computational and Applied Mathematics.
916             
917         </para>
918         
919         <para>
920             
921             3. B.N. Parlett and Y. Saad, "Complex Shift and Invert Strategies
922             
923             for Real Matrices", Linear Algebra and its Applications, vol 88/89, pp
924             
925             575-595, (1987).
926             
927         </para>
928         
929     </refsection>
930     
931     <refsection>
932         
933         <title>Used Functions</title>
934         
935         <para>Based on ARPACK routine zneupd</para>
936         
937     </refsection>
938     
939     <refsection>
940         
941         <title>履歴</title>
942         
943         <revhistory>
944             
945             <revision>
946                 
947                 <revnumber>5.4.0</revnumber>
948                 
949                 <revremark>
950                     
951                     関数は廃止され,<link linkend="eigs">eigs</link>に代替されました.
952                     
953                 </revremark>
954                 
955             </revision>
956             
957         </revhistory>
958         
959     </refsection>
960     
961 </refentry>
962