home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / SCSL / dsbgvx.z / dsbgvx
Encoding:
Text File  |  2002-10-03  |  9.6 KB  |  265 lines
  1.  
  2.  
  3.  
  4. DDDDSSSSBBBBGGGGVVVVXXXX((((3333SSSS))))                                                          DDDDSSSSBBBBGGGGVVVVXXXX((((3333SSSS))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      DSBGVX - compute selected eigenvalues, and optionally, eigenvectors of a
  10.      real generalized symmetric-definite banded eigenproblem, of the form
  11.      A*x=(lambda)*B*x
  12.  
  13. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  14.      SUBROUTINE DSBGVX( JOBZ, RANGE, UPLO, N, KA, KB, AB, LDAB, BB, LDBB, Q,
  15.                         LDQ, VL, VU, IL, IU, ABSTOL, M, W, Z, LDZ, WORK,
  16.                         IWORK, IFAIL, INFO )
  17.  
  18.          CHARACTER      JOBZ, RANGE, UPLO
  19.  
  20.          INTEGER        IL, INFO, IU, KA, KB, LDAB, LDBB, LDQ, LDZ, M, N
  21.  
  22.          DOUBLE         PRECISION ABSTOL, VL, VU
  23.  
  24.          INTEGER        IFAIL( * ), IWORK( * )
  25.  
  26.          DOUBLE         PRECISION AB( LDAB, * ), BB( LDBB, * ), Q( LDQ, * ),
  27.                         W( * ), WORK( * ), Z( LDZ, * )
  28.  
  29. IIIIMMMMPPPPLLLLEEEEMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
  30.      These routines are part of the SCSL Scientific Library and can be loaded
  31.      using either the -lscs or the -lscs_mp option.  The -lscs_mp option
  32.      directs the linker to use the multi-processor version of the library.
  33.  
  34.      When linking to SCSL with -lscs or -lscs_mp, the default integer size is
  35.      4 bytes (32 bits). Another version of SCSL is available in which integers
  36.      are 8 bytes (64 bits).  This version allows the user access to larger
  37.      memory sizes and helps when porting legacy Cray codes.  It can be loaded
  38.      by using the -lscs_i8 option or the -lscs_i8_mp option. A program may use
  39.      only one of the two versions; 4-byte integer and 8-byte integer library
  40.      calls cannot be mixed.
  41.  
  42. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  43.      DSBGVX computes selected eigenvalues, and optionally, eigenvectors of a
  44.      real generalized symmetric-definite banded eigenproblem, of the form
  45.      A*x=(lambda)*B*x. Here A and B are assumed to be symmetric and banded,
  46.      and B is also positive definite.  Eigenvalues and eigenvectors can be
  47.      selected by specifying either all eigenvalues, a range of values or a
  48.      range of indices for the desired eigenvalues.
  49.  
  50.  
  51. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  52.      JOBZ    (input) CHARACTER*1
  53.              = 'N':  Compute eigenvalues only;
  54.              = 'V':  Compute eigenvalues and eigenvectors.
  55.  
  56.      RANGE   (input) CHARACTER*1
  57.              = 'A': all eigenvalues will be found.
  58.              = 'V': all eigenvalues in the half-open interval (VL,VU] will be
  59.              found.  = 'I': the IL-th through IU-th eigenvalues will be found.
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. DDDDSSSSBBBBGGGGVVVVXXXX((((3333SSSS))))                                                          DDDDSSSSBBBBGGGGVVVVXXXX((((3333SSSS))))
  71.  
  72.  
  73.  
  74.      UPLO    (input) CHARACTER*1
  75.              = 'U':  Upper triangles of A and B are stored;
  76.              = 'L':  Lower triangles of A and B are stored.
  77.  
  78.      N       (input) INTEGER
  79.              The order of the matrices A and B.  N >= 0.
  80.  
  81.      KA      (input) INTEGER
  82.              The number of superdiagonals of the matrix A if UPLO = 'U', or
  83.              the number of subdiagonals if UPLO = 'L'.  KA >= 0.
  84.  
  85.      KB      (input) INTEGER
  86.              The number of superdiagonals of the matrix B if UPLO = 'U', or
  87.              the number of subdiagonals if UPLO = 'L'.  KB >= 0.
  88.  
  89.      AB      (input/output) DOUBLE PRECISION array, dimension (LDAB, N)
  90.              On entry, the upper or lower triangle of the symmetric band
  91.              matrix A, stored in the first ka+1 rows of the array.  The j-th
  92.              column of A is stored in the j-th column of the array AB as
  93.              follows:  if UPLO = 'U', AB(ka+1+i-j,j) = A(i,j) for max(1,j-
  94.              ka)<=i<=j; if UPLO = 'L', AB(1+i-j,j)    = A(i,j) for
  95.              j<=i<=min(n,j+ka).
  96.  
  97.              On exit, the contents of AB are destroyed.
  98.  
  99.      LDAB    (input) INTEGER
  100.              The leading dimension of the array AB.  LDAB >= KA+1.
  101.  
  102.      BB      (input/output) DOUBLE PRECISION array, dimension (LDBB, N)
  103.              On entry, the upper or lower triangle of the symmetric band
  104.              matrix B, stored in the first kb+1 rows of the array.  The j-th
  105.              column of B is stored in the j-th column of the array BB as
  106.              follows:  if UPLO = 'U', BB(ka+1+i-j,j) = B(i,j) for max(1,j-
  107.              kb)<=i<=j; if UPLO = 'L', BB(1+i-j,j)    = B(i,j) for
  108.              j<=i<=min(n,j+kb).
  109.  
  110.              On exit, the factor S from the split Cholesky factorization B =
  111.              S**T*S, as returned by DPBSTF.
  112.  
  113.      LDBB    (input) INTEGER
  114.              The leading dimension of the array BB.  LDBB >= KB+1.
  115.  
  116.      Q       (output) DOUBLE PRECISION array, dimension (LDQ, N)
  117.              If JOBZ = 'V', the n-by-n matrix used in the reduction of A*x =
  118.              (lambda)*B*x to standard form, i.e. C*x = (lambda)*x, and
  119.              consequently C to tridiagonal form.  If JOBZ = 'N', the array Q
  120.              is not referenced.
  121.  
  122.      LDQ     (input) INTEGER
  123.              The leading dimension of the array Q.  If JOBZ = 'N', LDQ >= 1.
  124.              If JOBZ = 'V', LDQ >= max(1,N).
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. DDDDSSSSBBBBGGGGVVVVXXXX((((3333SSSS))))                                                          DDDDSSSSBBBBGGGGVVVVXXXX((((3333SSSS))))
  137.  
  138.  
  139.  
  140.      VL      (input) DOUBLE PRECISION
  141.              VU      (input) DOUBLE PRECISION If RANGE='V', the lower and
  142.              upper bounds of the interval to be searched for eigenvalues. VL <
  143.              VU.  Not referenced if RANGE = 'A' or 'I'.
  144.  
  145.      IL      (input) INTEGER
  146.              IU      (input) INTEGER If RANGE='I', the indices (in ascending
  147.              order) of the smallest and largest eigenvalues to be returned.  1
  148.              <= IL <= IU <= N, if N > 0; IL = 1 and IU = 0 if N = 0.  Not
  149.              referenced if RANGE = 'A' or 'V'.
  150.  
  151.      ABSTOL  (input) DOUBLE PRECISION
  152.              The absolute error tolerance for the eigenvalues.  An approximate
  153.              eigenvalue is accepted as converged when it is determined to lie
  154.              in an interval [a,b] of width less than or equal to
  155.  
  156.              ABSTOL + EPS *   max( |a|,|b| ) ,
  157.  
  158.              where EPS is the machine precision.  If ABSTOL is less than or
  159.              equal to zero, then  EPS*|T|  will be used in its place, where
  160.              |T| is the 1-norm of the tridiagonal matrix obtained by reducing
  161.              A to tridiagonal form.
  162.  
  163.              Eigenvalues will be computed most accurately when ABSTOL is set
  164.              to twice the underflow threshold 2*DLAMCH('S'), not zero.  If
  165.              this routine returns with INFO>0, indicating that some
  166.              eigenvectors did not converge, try setting ABSTOL to
  167.              2*DLAMCH('S').
  168.  
  169.      M       (output) INTEGER
  170.              The total number of eigenvalues found.  0 <= M <= N.  If RANGE =
  171.              'A', M = N, and if RANGE = 'I', M = IU-IL+1.
  172.  
  173.      W       (output) DOUBLE PRECISION array, dimension (N)
  174.              If INFO = 0, the eigenvalues in ascending order.
  175.  
  176.      Z       (output) DOUBLE PRECISION array, dimension (LDZ, N)
  177.              If JOBZ = 'V', then if INFO = 0, Z contains the matrix Z of
  178.              eigenvectors, with the i-th column of Z holding the eigenvector
  179.              associated with W(i).  The eigenvectors are normalized so
  180.              Z**T*B*Z = I.  If JOBZ = 'N', then Z is not referenced.
  181.  
  182.      LDZ     (input) INTEGER
  183.              The leading dimension of the array Z.  LDZ >= 1, and if JOBZ =
  184.              'V', LDZ >= max(1,N).
  185.  
  186.      WORK    (workspace/output) DOUBLE PRECISION array, dimension (7N)
  187.  
  188.      IWORK   (workspace/output) INTEGER array, dimension (5N)
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. DDDDSSSSBBBBGGGGVVVVXXXX((((3333SSSS))))                                                          DDDDSSSSBBBBGGGGVVVVXXXX((((3333SSSS))))
  203.  
  204.  
  205.  
  206.      IFAIL   (input) INTEGER array, dimension (M)
  207.              If JOBZ = 'V', then if INFO = 0, the first M elements of IFAIL
  208.              are zero.  If INFO > 0, then IFAIL contains the indices of the
  209.              eigenvalues that failed to converge.  If JOBZ = 'N', then IFAIL
  210.              is not referenced.
  211.  
  212.      INFO    (output) INTEGER
  213.              = 0 : successful exit
  214.              < 0 : if INFO = -i, the i-th argument had an illegal value
  215.              <= N: if INFO = i, then i eigenvectors failed to converge.  Their
  216.              indices are stored in IFAIL.  > N : DPBSTF returned an error
  217.              code; i.e., if INFO = N + i, for 1 <= i <= N, then the leading
  218.              minor of order i of B is not positive definite.  The
  219.              factorization of B could not be completed and no eigenvalues or
  220.              eigenvectors were computed.
  221.  
  222. FFFFUUUURRRRTTTTHHHHEEEERRRR DDDDEEEETTTTAAAAIIIILLLLSSSS
  223.      Based on contributions by
  224.         Mark Fahey, Department of Mathematics, Univ. of Kentucky, USA
  225.  
  226.  
  227. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  228.      INTRO_LAPACK(3S), INTRO_SCSL(3S)
  229.  
  230.      This man page is available only online.
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.