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