added japanese translation of arnoldi module.
[scilab.git] / scilab / modules / arnoldi / help / ja_JP / dseupd.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="dseupd" xml:lang="ja">
4     
5     <refnamediv>
6         
7         <refname>dseupd</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, V, IPARAM, IPNTR, WORKD, WORKL, INFO] = dseupd(RVEC, HOWMANY, SELECT, D, Z, SIGMA, BMAT, N, WHICH,
32             
33             NEV, TOL, RESID, NCV, V, IPARAM, IPNTR, WORKD, WORKL, 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 Ritz vectors corresponding to the Ritz value
56                         
57                         approximations to the eigenproblem A * z = lambda * B * z are
58                         
59                         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>RVEC = 1 Compute Ritz vectors.</para>
74                             
75                         </listitem>
76                         
77                     </itemizedlist>
78                     
79                 </listitem>
80                 
81             </varlistentry>
82             
83             <varlistentry>
84                 
85                 <term>HOWMNY</term>
86                 
87                 <listitem>
88                     
89                     <para>Character*1. (INPUT) </para>
90                     
91                     <para>
92                         
93                         Specifies how many Ritz vectors are wanted and the form of Z
94                         
95                         the matrix of Ritz vectors. See remark 1 below.
96                         
97                     </para>
98                     
99                     <itemizedlist>
100                         
101                         <listitem>
102                             
103                             <para>'A': compute NEV Ritz vectors;</para>
104                             
105                         </listitem>
106                         
107                         <listitem>
108                             
109                             <para>
110                                 
111                                 'S': compute some of the Ritz vectors, specified by the
112                                 
113                                 integer array SELECT.
114                                 
115                             </para>
116                             
117                         </listitem>
118                         
119                     </itemizedlist>
120                     
121                 </listitem>
122                 
123             </varlistentry>
124             
125             <varlistentry>
126                 
127                 <term>SELECT</term>
128                 
129                 <listitem>
130                     
131                     <para>Integer array of dimension NCV. (INPUT/WORKSPACE) </para>
132                     
133                     <para>
134                         
135                         If HOWMANY = 'S', SELECT specifies the Ritz vectors to be
136                         
137                         computed. To select the Ritz vector corresponding to a Ritz value
138                         
139                         D(j), SELECT(j) must be set to 1.
140                         
141                     </para>
142                     
143                     <para>
144                         
145                         If HOWMANY = 'A' , SELECT is used as a workspace for
146                         
147                         reordering the Ritz values.
148                         
149                     </para>
150                     
151                 </listitem>
152                 
153             </varlistentry>
154             
155             <varlistentry>
156                 
157                 <term>D</term>
158                 
159                 <listitem>
160                     
161                     <para>Double precision array of dimension NEV. (OUTPUT) </para>
162                     
163                     <para>
164                         
165                         On exit, D contains the Ritz value approximations to the
166                         
167                         eigenvalues of A * z = lambda * B * z. The values are returned in
168                         
169                         ascending order.
170                         
171                     </para>
172                     
173                     <para>
174                         
175                         If IPARAM(7) = 3, 4, 5 then D represents the Ritz values of OP
176                         
177                         computed by dsaupd transformed to those of the original eigensystem
178                         
179                         A * z = lambda * B * z.
180                         
181                     </para>
182                     
183                     <para>
184                         
185                         If IPARAM(7) = 1, 2 then the Ritz values of OP are the same as
186                         
187                         the those of A * z = lambda * B * z.
188                         
189                     </para>
190                     
191                 </listitem>
192                 
193             </varlistentry>
194             
195             <varlistentry>
196                 
197                 <term>Z</term>
198                 
199                 <listitem>
200                     
201                     <para>Double precision N by NEV array.</para>
202                     
203                     <para>
204                         
205                         If HOWMNY = 'A'. (OUTPUT) On exit, Z contains the
206                         
207                         B-orthonormal Ritz vectors of the eigensystemA * z = lambda * B * z
208                         
209                         corresponding to the Ritz value approximations.
210                         
211                     </para>
212                     
213                     <para>If RVEC = 0 then Z is not referenced. </para>
214                     
215                     <para>
216                         
217                         NOTE: The array Z may be set equal to first NEV columns of the
218                         
219                         Arnoldi/Lanczos basis array V computed by DSAUPD .
220                         
221                     </para>
222                     
223                 </listitem>
224                 
225             </varlistentry>
226             
227             <varlistentry>
228                 
229                 <term>SIGMA</term>
230                 
231                 <listitem>
232                     
233                     <para>Double precision (INPUT) </para>
234                     
235                     <para>
236                         
237                         If IPARAM(7) = 3, 4, 5 represents the shift. Not referenced if
238                         
239                         IPARAM(7) = 1 or 2.
240                         
241                     </para>
242                     
243                 </listitem>
244                 
245             </varlistentry>
246             
247         </variablelist>
248         
249         <para>
250             
251             NOTE: The remaining arguments BMAT, N, WHICH, NEV, TOL, RESID, NCV,
252             
253             V, IPARAM, IPNTR, WORKD, WORKL, LWORKL, INFO must be passed directly to
254             
255             DSEUPD following the last call to DSAUPD .
256             
257         </para>
258         
259         <para>
260             
261             These arguments MUST NOT BE MODIFIED between the last call to
262             
263             DSAUPD and the call to DSEUPD.
264             
265         </para>
266         
267         <para>
268             
269             Two of these parameters (WORKL, INFO) are also output
270             
271             parameters.
272             
273         </para>
274         
275         <variablelist>
276             
277             <varlistentry>
278                 
279                 <term>WORKL</term>
280                 
281                 <listitem>
282                     
283                     <para>
284                         
285                         Double precision work array of length LWORKL.
286                         
287                         (OUTPUT/WORKSPACE)
288                         
289                     </para>
290                     
291                     <para>
292                         
293                         WORKL(1:4*ncv) contains information obtained in dsaupd. They
294                         
295                         are not changed by dseupd.
296                         
297                     </para>
298                     
299                     <para>
300                         
301                         WORKL(4*ncv+1:ncv*ncv+8*ncv) holds the untransformed Ritz
302                         
303                         values, the computed error estimates, and the associated eigenvector
304                         
305                         matrix of H.
306                         
307                     </para>
308                     
309                     <para>
310                         
311                         Note: IPNTR(8:10) contains the pointer into WORKL for
312                         
313                         addresses of the above information computed by dseupd .
314                         
315                     </para>
316                     
317                     <itemizedlist>
318                         
319                         <listitem>
320                             
321                             <para>
322                                 
323                                 IPNTR(8): pointer to the NCV RITZ values of the original
324                                 
325                                 system.
326                                 
327                             </para>
328                             
329                         </listitem>
330                         
331                         <listitem>
332                             
333                             <para>
334                                 
335                                 IPNTR(9): pointer to the NCV corresponding error bounds.
336                                 
337                             </para>
338                             
339                         </listitem>
340                         
341                         <listitem>
342                             
343                             <para>
344                                 
345                                 IPNTR(10): pointer to the NCV by NCV matrix of
346                                 
347                                 eigenvectors of the tridiagonal matrix T. Only referenced by
348                                 
349                                 dseupd if RVEC = 1 See Remarks.
350                                 
351                             </para>
352                             
353                         </listitem>
354                         
355                     </itemizedlist>
356                     
357                 </listitem>
358                 
359             </varlistentry>
360             
361             <varlistentry>
362                 
363                 <term>INFO</term>
364                 
365                 <listitem>
366                     
367                     <para>Integer. (OUTPUT) </para>
368                     
369                     <para>Error flag on output.</para>
370                     
371                     <itemizedlist>
372                         
373                         <listitem>
374                             
375                             <para>0: Normal exit.</para>
376                             
377                         </listitem>
378                         
379                         <listitem>
380                             
381                             <para>-1: N must be positive.</para>
382                             
383                         </listitem>
384                         
385                         <listitem>
386                             
387                             <para>-2: NEV must be positive.</para>
388                             
389                         </listitem>
390                         
391                         <listitem>
392                             
393                             <para>
394                                 
395                                 -3: NCV must be greater than NEV and less than or equal to
396                                 
397                                 N.
398                                 
399                             </para>
400                             
401                         </listitem>
402                         
403                         <listitem>
404                             
405                             <para>
406                                 
407                                 -5: WHICH must be one of 'LM', 'SM', 'LA', 'SA' or
408                                 
409                                 'BE'.
410                                 
411                             </para>
412                             
413                         </listitem>
414                         
415                         <listitem>
416                             
417                             <para>-6: BMAT must be one of 'I' or 'G'.</para>
418                             
419                         </listitem>
420                         
421                         <listitem>
422                             
423                             <para>
424                                 
425                                 -7: Length of private work WORKL array is not
426                                 
427                                 sufficient.
428                                 
429                             </para>
430                             
431                         </listitem>
432                         
433                         <listitem>
434                             
435                             <para>
436                                 
437                                 -8: Error return from trid. eigenvalue calculation;
438                                 
439                                 Information error from LAPACK routine dsteqr.
440                                 
441                             </para>
442                             
443                         </listitem>
444                         
445                         <listitem>
446                             
447                             <para>-9: Starting vector is zero.</para>
448                             
449                         </listitem>
450                         
451                         <listitem>
452                             
453                             <para>-10: IPARAM(7) must be 1, 2, 3, 4, 5.</para>
454                             
455                         </listitem>
456                         
457                         <listitem>
458                             
459                             <para>-11: IPARAM(7) = 1 and BMAT = 'G' are incompatible.</para>
460                             
461                         </listitem>
462                         
463                         <listitem>
464                             
465                             <para>-12: NEV and WHICH = 'BE' are incompatible.</para>
466                             
467                         </listitem>
468                         
469                         <listitem>
470                             
471                             <para>
472                                 
473                                 -14: DSAUPD did not find any eigenvalues to sufficient
474                                 
475                                 accuracy.
476                                 
477                             </para>
478                             
479                         </listitem>
480                         
481                         <listitem>
482                             
483                             <para>-15: HOWMNY must be one of 'A' or 'S' if RVEC = 1.</para>
484                             
485                         </listitem>
486                         
487                         <listitem>
488                             
489                             <para>-16: HOWMNY = 'S' not yet implemented.</para>
490                             
491                         </listitem>
492                         
493                         <listitem>
494                             
495                             <para>
496                                 
497                                 -17: DSEUPD got a different count of the number of
498                                 
499                                 converged Ritz values than DSAUPD got. This indicates the user
500                                 
501                                 probably made an error in passing data from DSAUPD to DSEUPD or
502                                 
503                                 that the data was modified before entering DSEUPD.
504                                 
505                             </para>
506                             
507                         </listitem>
508                         
509                     </itemizedlist>
510                     
511                 </listitem>
512                 
513             </varlistentry>
514             
515         </variablelist>
516         
517     </refsection>
518     
519     <refsection>
520         
521         <title>Description</title>
522         
523         <para>
524             
525             This subroutine returns the converged approximations to eigenvalues
526             
527             of A * z = lambda * B * z and (optionally):
528             
529         </para>
530         
531         <orderedlist>
532             
533             <listitem>
534                 
535                 <para>the corresponding approximate eigenvectors,</para>
536                 
537             </listitem>
538             
539             <listitem>
540                 
541                 <para>
542                     
543                     an orthonormal (Lanczos) basis for the associated approximate
544                     
545                     invariant subspace,
546                     
547                 </para>
548                 
549             </listitem>
550             
551             <listitem>
552                 
553                 <para>Both. </para>
554                 
555             </listitem>
556             
557         </orderedlist>
558         
559         <para>
560             
561             There is negligible additional cost to obtain eigenvectors. An
562             
563             orthonormal (Lanczos) basis is always computed. There is an additional
564             
565             storage cost of n*nev if both are requested (in this case a separate array
566             
567             Z must be supplied).
568             
569         </para>
570         
571         <para>
572             
573             These quantities are obtained from the Lanczos factorization
574             
575             computed by DSAUPD for the linear operator OP prescribed by the MODE
576             
577             selection (see IPARAM(7) in DSAUPD documentation.) DSAUPD must be called
578             
579             before this routine is called.
580             
581         </para>
582         
583         <para>
584             
585             These approximate eigenvalues and vectors are commonly called Ritz
586             
587             values and Ritz vectors respectively. They are referred to as such in the
588             
589             comments that follow.
590             
591         </para>
592         
593         <para>
594             
595             The computed orthonormal basis for the invariant subspace
596             
597             corresponding to these Ritz values is referred to as a Lanczos basis.
598             
599         </para>
600         
601         <para>
602             
603             See documentation in the header of the subroutine DSAUPD for a
604             
605             definition of OP as well as other terms and the relation of computed Ritz
606             
607             values and vectors of OP with respect to the given problem A * z = lambda * B * z.
608             
609         </para>
610         
611         <para>
612             
613             The approximate eigenvalues of the original problem are returned in
614             
615             ascending algebraic order.
616             
617         </para>
618         
619         <para>
620             
621             The user may elect to call this routine once for each desired Ritz
622             
623             vector and store it peripherally if desired. There is also the option of
624             
625             computing a selected set of these vectors with a single call.
626             
627         </para>
628         
629     </refsection>
630     
631     <refsection>
632         
633         <title>Remarks</title>
634         
635         <para>
636             
637             1. The converged Ritz values are always returned in increasing
638             
639             (algebraic) order. c 2. Currently only HOWMNY = 'A' is implemented. It is
640             
641             included at this stage for the user who wants to incorporate it.
642             
643         </para>
644         
645     </refsection>
646     
647     <refsection>
648         
649         <title>Example</title>
650         
651         <programlisting role="example">
652             
653             <![CDATA[ 
654
655 // The following sets dimensions for this problem.
656
657 nx    = 10;
658
659 nev   = 3;
660 ncv   = 6;
661 bmat  = 'I';
662 which = 'LM';
663
664 // Local Arrays
665
666 iparam  = zeros(11, 1);
667 ipntr   = zeros(14, 1);
668 _select = zeros(ncv, 1);
669 d       = zeros(nev, 1);
670 z       = zeros(nx, nev);
671 resid   = zeros(nx, 1); 
672 v       = zeros(nx, ncv);
673 workd   = zeros(3 * nx, 1); 
674 workl   = zeros(ncv * ncv + 8 * ncv, 1);
675
676 // Build the symmetric test matrix
677
678 A            = diag(10 * ones(nx,1));
679 A(1:$-1,2:$) = A(1:$-1,2:$) + diag(6 * ones(nx-1,1));
680 A(2:$,1:$-1) = A(2:$,1:$-1) + diag(6 * ones(nx-1,1));
681
682 tol    = 0;
683 ido    = 0;
684
685 ishfts = 1;
686 maxitr = 300;
687 mode1  = 1;
688
689 iparam(1) = ishfts;
690 iparam(3) = maxitr;
691 iparam(7) = mode1;
692
693 sigma = 0; // the real part of the shift
694 info_dsaupd = 0;
695
696 // M A I N   L O O P (Reverse communication)
697
698 while(ido <> 99)
699   // Repeatedly call the routine DSAUPD and take actions indicated by parameter IDO until
700   // either convergence is indicated or maxitr has been exceeded.
701
702   [ido, resid, v, iparam, ipntr, workd, workl, info_dsaupd] = dsaupd(ido, bmat, nx, which, nev, tol, resid, ncv, v, iparam, ipntr, workd, workl, info_dsaupd);
703   
704   if(info_dsaupd < 0)
705     printf('\nError with dsaupd, info = %d\n',info_dsaupd);
706     printf('Check the documentation of dsaupd\n\n');
707   end
708   
709   if(ido == -1 | ido == 1)
710     // Perform matrix vector multiplication 
711     workd(ipntr(2):ipntr(2) + nx - 1) = A * workd(ipntr(1):ipntr(1) + nx - 1);
712   end
713 end
714
715 // Post-Process using DSEUPD.
716 rvec    = 1;
717 howmany = 'A';
718 info_dseupd = 0;
719
720 [d, z, resid, v, iparam, ipntr, workd, workl, info_dseupd] = dseupd(rvec, howmany, _select, d, z, sigma, bmat, nx, which, nev, tol, resid, ncv, v, ...
721                                                                     iparam, ipntr, workd, workl, info_dseupd);
722
723 if(info_dseupd < 0)
724   printf('\nError with dseupd, info = %d\n', info_dseupd);
725   printf('Check the documentation of dseupd.\n\n');
726 end
727
728
729 // Done with program dssimp.
730 printf('\nDSSIMP\n');
731 printf('======\n');
732 printf('\n');
733 printf('Size of the matrix is %d\n', nx);
734 printf('The number of Ritz values requested is %d\n', nev);
735 printf('The number of Arnoldi vectors generated (NCV) is %d\n', ncv);
736 printf('What portion of the spectrum: %s\n', which);
737 printf('The number of Implicit Arnoldi update iterations taken is %d\n', iparam(3));
738 printf('The number of OP*x is %d\n', iparam(9));
739 printf('The convergence criterion is %d\n', tol);
740
741 ]]>
742             
743         </programlisting>
744         
745     </refsection>
746     
747     <refsection role="see also">
748         
749         <title>See Also</title>
750         
751         <simplelist type="inline">
752             
753             <member>
754                 
755                 <link linkend="dsaupd">dsaupd</link>
756                 
757             </member>
758             
759             <member>
760                 
761                 <link linkend="dneupd">dneupd</link>
762                 
763             </member>
764             
765         </simplelist>
766         
767     </refsection>
768     
769     <refsection>
770         
771         <title>Bibliography</title>
772         
773         <para>
774             
775             1. D.C. Sorensen, "Implicit Application of Polynomial Filters in
776             
777             k-Step Arnoldi Method", SIAM J. Matr. Anal. Apps., 13 (1992), pp
778             
779             357-385.
780             
781         </para>
782         
783         <para>
784             
785             2. R.B. Lehoucq, "Analysis and Implementation of an Implicitly
786             
787             Restarted Arnoldi Iteration", Rice University Technical Report TR95-13,
788             
789             Department of Computational and Applied Mathematics.
790             
791         </para>
792         
793         <para>
794             
795             3. B.N. Parlett and Y. Saad, "Complex Shift and Invert Strategies
796             
797             for Real Matrices", Linear Algebra and its Applications, vol 88/89, pp
798             
799             575-595, (1987).
800             
801         </para>
802         
803     </refsection>
804     
805     <refsection>
806         
807         <title>Used Functions</title>
808         
809         <para>Based on ARPACK routine dseupd</para>
810         
811     </refsection>
812     
813     <refsection>
814         
815         <title>履歴</title>
816         
817         <revhistory>
818             
819             <revision>
820                 
821                 <revnumber>5.4.0</revnumber>
822                 
823                 <revremark>
824                     
825                     関数は廃止され,<link linkend="eigs">eigs</link>に代替されました.
826                     
827                 </revremark>
828                 
829             </revision>
830             
831         </revhistory>
832         
833     </refsection>
834     
835 </refentry>
836