← Back to branch summary

~ubuntu-branches/ubuntu/raring/scilab/raring-proposed

« back to all changes in this revision

Viewing changes to modules/arnoldi/help/en_US/dseupd.xml

  • Committer: Package Import Robot
  • Author(s): Sylvestre Ledru
  • Date: 2012-08-30 14:42:38 UTC
  • mfrom: (1.4.7)
  • Revision ID: package-import@ubuntu.com-20120830144238-c1y2og7dbm7m9nig
Tags: 5.4.0-beta-3-1~exp1
* New upstream release
* Update the scirenderer dep
* Get ride of libjhdf5-java dependency

Show diffs side-by-side

added added

removed removed

Lines of Context:
modules/arnoldi/help/en_US/dseupd.xml
1
1
<?xml version="1.0" encoding="UTF-8"?>
2
2
<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" version="5.0-subset Scilab" xml:id="dseupd" xml:lang="en">
3
 
  <refnamediv>
4
 
    <refname>dseupd</refname>
5
 
    <refpurpose>
6
 
      Interface for the Implicitly Restarted Arnoldi Iteration, to
7
 
      compute approximations to the converged approximations to eigenvalues of
8
 
      A * z = lambda * B * z
9
 
    </refpurpose>
10
 
  </refnamediv>
11
 
  <refsynopsisdiv>
12
 
    <title>Calling Sequence</title>
13
 
    <synopsis>
14
 
      [D, Z, RESID, V, IPARAM, IPNTR, WORKD, WORKL, INFO] = dseupd(RVEC, HOWMANY, SELECT, D, Z, SIGMA, BMAT, N, WHICH,
15
 
      NEV, TOL, RESID, NCV, V, IPARAM, IPNTR, WORKD, WORKL, INFO)
16
 
    </synopsis>
17
 
  </refsynopsisdiv>
18
 
  <refsection>
19
 
    <title>Arguments</title>
20
 
    <variablelist>
21
 
      <varlistentry>
22
 
        <term>RVEC</term>
23
 
        <listitem>
24
 
          <para>Integer. (INPUT) </para>
25
 
          <para>
26
 
            Specifies whether Ritz vectors corresponding to the Ritz value
27
 
            approximations to the eigenproblem A * z = lambda * B * z are
28
 
            computed.
29
 
          </para>
30
 
          <itemizedlist>
31
 
            <listitem>
32
 
              <para>RVEC = 0 Compute Ritz values only.</para>
33
 
            </listitem>
34
 
            <listitem>
35
 
              <para>RVEC = 1 Compute Ritz vectors.</para>
36
 
            </listitem>
37
 
          </itemizedlist>
38
 
        </listitem>
39
 
      </varlistentry>
40
 
      <varlistentry>
41
 
        <term>HOWMNY</term>
42
 
        <listitem>
43
 
          <para>Character*1. (INPUT) </para>
44
 
          <para>
45
 
            Specifies how many Ritz vectors are wanted and the form of Z
46
 
            the matrix of Ritz vectors. See remark 1 below.
47
 
          </para>
48
 
          <itemizedlist>
49
 
            <listitem>
50
 
              <para>'A': compute NEV Ritz vectors;</para>
51
 
            </listitem>
52
 
            <listitem>
53
 
              <para>
54
 
                'S': compute some of the Ritz vectors, specified by the
55
 
                integer array SELECT.
56
 
              </para>
57
 
            </listitem>
58
 
          </itemizedlist>
59
 
        </listitem>
60
 
      </varlistentry>
61
 
      <varlistentry>
62
 
        <term>SELECT</term>
63
 
        <listitem>
64
 
          <para>Integer array of dimension NCV. (INPUT/WORKSPACE) </para>
65
 
          <para>
66
 
            If HOWMANY = 'S', SELECT specifies the Ritz vectors to be
67
 
            computed. To select the Ritz vector corresponding to a Ritz value
68
 
            D(j), SELECT(j) must be set to 1.
69
 
          </para>
70
 
          <para>
71
 
            If HOWMANY = 'A' , SELECT is used as a workspace for
72
 
            reordering the Ritz values.
73
 
          </para>
74
 
        </listitem>
75
 
      </varlistentry>
76
 
      <varlistentry>
77
 
        <term>D</term>
78
 
        <listitem>
79
 
          <para>Double precision array of dimension NEV. (OUTPUT) </para>
80
 
          <para>
81
 
            On exit, D contains the Ritz value approximations to the
82
 
            eigenvalues of A * z = lambda * B * z. The values are returned in
83
 
            ascending order.
84
 
          </para>
85
 
          <para>
86
 
            If IPARAM(7) = 3, 4, 5 then D represents the Ritz values of OP
87
 
            computed by dsaupd transformed to those of the original eigensystem
88
 
            A * z = lambda * B * z.
89
 
          </para>
90
 
          <para>
91
 
            If IPARAM(7) = 1, 2 then the Ritz values of OP are the same as
92
 
            the those of A * z = lambda * B * z.
93
 
          </para>
94
 
        </listitem>
95
 
      </varlistentry>
96
 
      <varlistentry>
97
 
        <term>Z</term>
98
 
        <listitem>
99
 
          <para>Double precision N by NEV array.</para>
100
 
          <para>
101
 
            If HOWMNY = 'A'. (OUTPUT) On exit, Z contains the
102
 
            B-orthonormal Ritz vectors of the eigensystemA * z = lambda * B * z
103
 
            corresponding to the Ritz value approximations.
104
 
          </para>
105
 
          <para>If RVEC = 0 then Z is not referenced. </para>
106
 
          <para>
107
 
            NOTE: The array Z may be set equal to first NEV columns of the
108
 
            Arnoldi/Lanczos basis array V computed by DSAUPD .
109
 
          </para>
110
 
        </listitem>
111
 
      </varlistentry>
112
 
      <varlistentry>
113
 
        <term>SIGMA</term>
114
 
        <listitem>
115
 
          <para>Double precision (INPUT) </para>
116
 
          <para>
117
 
            If IPARAM(7) = 3, 4, 5 represents the shift. Not referenced if
118
 
            IPARAM(7) = 1 or 2.
119
 
          </para>
120
 
        </listitem>
121
 
      </varlistentry>
122
 
    </variablelist>
123
 
    <para>
124
 
      NOTE: The remaining arguments BMAT, N, WHICH, NEV, TOL, RESID, NCV,
125
 
      V, IPARAM, IPNTR, WORKD, WORKL, LWORKL, INFO must be passed directly to
126
 
      DSEUPD following the last call to DSAUPD .
127
 
    </para>
128
 
    <para>
129
 
      These arguments MUST NOT BE MODIFIED between the last call to
130
 
      DSAUPD and the call to DSEUPD.
131
 
    </para>
132
 
    <para>
133
 
      Two of these parameters (WORKL, INFO) are also output
134
 
      parameters.
135
 
    </para>
136
 
    <variablelist>
137
 
      <varlistentry>
138
 
        <term>WORKL</term>
139
 
        <listitem>
140
 
          <para>
141
 
            Double precision work array of length LWORKL.
142
 
            (OUTPUT/WORKSPACE)
143
 
          </para>
144
 
          <para>
145
 
            WORKL(1:4*ncv) contains information obtained in dsaupd. They
146
 
            are not changed by dseupd.
147
 
          </para>
148
 
          <para>
149
 
            WORKL(4*ncv+1:ncv*ncv+8*ncv) holds the untransformed Ritz
150
 
            values, the computed error estimates, and the associated eigenvector
151
 
            matrix of H.
152
 
          </para>
153
 
          <para>
154
 
            Note: IPNTR(8:10) contains the pointer into WORKL for
155
 
            addresses of the above information computed by dseupd .
156
 
          </para>
157
 
          <itemizedlist>
158
 
            <listitem>
159
 
              <para>
160
 
                IPNTR(8): pointer to the NCV RITZ values of the original
161
 
                system.
162
 
              </para>
163
 
            </listitem>
164
 
            <listitem>
165
 
              <para>
166
 
                IPNTR(9): pointer to the NCV corresponding error bounds.
167
 
              </para>
168
 
            </listitem>
169
 
            <listitem>
170
 
              <para>
171
 
                IPNTR(10): pointer to the NCV by NCV matrix of
172
 
                eigenvectors of the tridiagonal matrix T. Only referenced by
173
 
                dseupd if RVEC = 1 See Remarks.
174
 
              </para>
175
 
            </listitem>
176
 
          </itemizedlist>
177
 
        </listitem>
178
 
      </varlistentry>
179
 
      <varlistentry>
180
 
        <term>INFO</term>
181
 
        <listitem>
182
 
          <para>Integer. (OUTPUT) </para>
183
 
          <para>Error flag on output.</para>
184
 
          <itemizedlist>
185
 
            <listitem>
186
 
              <para>0: Normal exit.</para>
187
 
            </listitem>
188
 
            <listitem>
189
 
              <para>-1: N must be positive.</para>
190
 
            </listitem>
191
 
            <listitem>
192
 
              <para>-2: NEV must be positive.</para>
193
 
            </listitem>
194
 
            <listitem>
195
 
              <para>
196
 
                -3: NCV must be greater than NEV and less than or equal to
197
 
                N.
198
 
              </para>
199
 
            </listitem>
200
 
            <listitem>
201
 
              <para>
202
 
                -5: WHICH must be one of 'LM', 'SM', 'LA', 'SA' or
203
 
                'BE'.
204
 
              </para>
205
 
            </listitem>
206
 
            <listitem>
207
 
              <para>-6: BMAT must be one of 'I' or 'G'.</para>
208
 
            </listitem>
209
 
            <listitem>
210
 
              <para>
211
 
                -7: Length of private work WORKL array is not
212
 
                sufficient.
213
 
              </para>
214
 
            </listitem>
215
 
            <listitem>
216
 
              <para>
217
 
                -8: Error return from trid. eigenvalue calculation;
218
 
                Information error from LAPACK routine dsteqr.
219
 
              </para>
220
 
            </listitem>
221
 
            <listitem>
222
 
              <para>-9: Starting vector is zero.</para>
223
 
            </listitem>
224
 
            <listitem>
225
 
              <para>-10: IPARAM(7) must be 1, 2, 3, 4, 5.</para>
226
 
            </listitem>
227
 
            <listitem>
228
 
              <para>-11: IPARAM(7) = 1 and BMAT = 'G' are incompatible.</para>
229
 
            </listitem>
230
 
            <listitem>
231
 
              <para>-12: NEV and WHICH = 'BE' are incompatible.</para>
232
 
            </listitem>
233
 
            <listitem>
234
 
              <para>
235
 
                -14: DSAUPD did not find any eigenvalues to sufficient
236
 
                accuracy.
237
 
              </para>
238
 
            </listitem>
239
 
            <listitem>
240
 
              <para>-15: HOWMNY must be one of 'A' or 'S' if RVEC = 1.</para>
241
 
            </listitem>
242
 
            <listitem>
243
 
              <para>-16: HOWMNY = 'S' not yet implemented.</para>
244
 
            </listitem>
245
 
            <listitem>
246
 
              <para>
247
 
                -17: DSEUPD got a different count of the number of
248
 
                converged Ritz values than DSAUPD got. This indicates the user
249
 
                probably made an error in passing data from DSAUPD to DSEUPD or
250
 
                that the data was modified before entering DSEUPD.
251
 
              </para>
252
 
            </listitem>
253
 
          </itemizedlist>
254
 
        </listitem>
255
 
      </varlistentry>
256
 
    </variablelist>
257
 
  </refsection>
258
 
  <refsection>
259
 
    <title>Description</title>
260
 
    <para>
261
 
      This subroutine returns the converged approximations to eigenvalues
262
 
      of A * z = lambda * B * z and (optionally):
263
 
    </para>
264
 
    <orderedlist>
265
 
      <listitem>
266
 
        <para>the corresponding approximate eigenvectors,</para>
267
 
      </listitem>
268
 
      <listitem>
269
 
        <para>
270
 
          an orthonormal (Lanczos) basis for the associated approximate
271
 
          invariant subspace,
272
 
        </para>
273
 
      </listitem>
274
 
      <listitem>
275
 
        <para>Both. </para>
276
 
      </listitem>
277
 
    </orderedlist>
278
 
    <para>
279
 
      There is negligible additional cost to obtain eigenvectors. An
280
 
      orthonormal (Lanczos) basis is always computed. There is an additional
281
 
      storage cost of n*nev if both are requested (in this case a separate array
282
 
      Z must be supplied).
283
 
    </para>
284
 
    <para>
285
 
      These quantities are obtained from the Lanczos factorization
286
 
      computed by DSAUPD for the linear operator OP prescribed by the MODE
287
 
      selection (see IPARAM(7) in DSAUPD documentation.) DSAUPD must be called
288
 
      before this routine is called.
289
 
    </para>
290
 
    <para>
291
 
      These approximate eigenvalues and vectors are commonly called Ritz
292
 
      values and Ritz vectors respectively. They are referred to as such in the
293
 
      comments that follow.
294
 
    </para>
295
 
    <para>
296
 
      The computed orthonormal basis for the invariant subspace
297
 
      corresponding to these Ritz values is referred to as a Lanczos basis.
298
 
    </para>
299
 
    <para>
300
 
      See documentation in the header of the subroutine DSAUPD for a
301
 
      definition of OP as well as other terms and the relation of computed Ritz
302
 
      values and vectors of OP with respect to the given problem A * z = lambda * B * z.
303
 
    </para>
304
 
    <para>
305
 
      The approximate eigenvalues of the original problem are returned in
306
 
      ascending algebraic order.
307
 
    </para>
308
 
    <para>
309
 
      The user may elect to call this routine once for each desired Ritz
310
 
      vector and store it peripherally if desired. There is also the option of
311
 
      computing a selected set of these vectors with a single call.
312
 
    </para>
313
 
  </refsection>
314
 
  <refsection>
315
 
    <title>Remarks</title>
316
 
    <para>
317
 
      1. The converged Ritz values are always returned in increasing
318
 
      (algebraic) order. c 2. Currently only HOWMNY = 'A' is implemented. It is
319
 
      included at this stage for the user who wants to incorporate it.
320
 
    </para>
321
 
  </refsection>
322
 
  <refsection>
323
 
    <title>Example</title>
324
 
    <programlisting role="example">
325
 
      <![CDATA[ 
 
3
    <refnamediv>
 
4
        <refname>dseupd</refname>
 
5
        <refpurpose>
 
6
            Interface for the Implicitly Restarted Arnoldi Iteration, to
 
7
            compute approximations to the converged approximations to eigenvalues of
 
8
            A * z = lambda * B * z
 
9
            <emphasis role="bold">
 
10
                This function is obsolete. Please use <link linkend="eigs">eigs</link>
 
11
            </emphasis>
 
12
        </refpurpose>
 
13
    </refnamediv>
 
14
    <refsynopsisdiv>
 
15
        <title>Calling Sequence</title>
 
16
        <synopsis>
 
17
            [D, Z, RESID, V, IPARAM, IPNTR, WORKD, WORKL, INFO] = dseupd(RVEC, HOWMANY, SELECT, D, Z, SIGMA, BMAT, N, WHICH,
 
18
            NEV, TOL, RESID, NCV, V, IPARAM, IPNTR, WORKD, WORKL, INFO)
 
19
        </synopsis>
 
20
    </refsynopsisdiv>
 
21
    <refsection>
 
22
        <title>Arguments</title>
 
23
        <variablelist>
 
24
            <varlistentry>
 
25
                <term>RVEC</term>
 
26
                <listitem>
 
27
                    <para>Integer. (INPUT) </para>
 
28
                    <para>
 
29
                        Specifies whether Ritz vectors corresponding to the Ritz value
 
30
                        approximations to the eigenproblem A * z = lambda * B * z are
 
31
                        computed.
 
32
                    </para>
 
33
                    <itemizedlist>
 
34
                        <listitem>
 
35
                            <para>RVEC = 0 Compute Ritz values only.</para>
 
36
                        </listitem>
 
37
                        <listitem>
 
38
                            <para>RVEC = 1 Compute Ritz vectors.</para>
 
39
                        </listitem>
 
40
                    </itemizedlist>
 
41
                </listitem>
 
42
            </varlistentry>
 
43
            <varlistentry>
 
44
                <term>HOWMNY</term>
 
45
                <listitem>
 
46
                    <para>Character*1. (INPUT) </para>
 
47
                    <para>
 
48
                        Specifies how many Ritz vectors are wanted and the form of Z
 
49
                        the matrix of Ritz vectors. See remark 1 below.
 
50
                    </para>
 
51
                    <itemizedlist>
 
52
                        <listitem>
 
53
                            <para>'A': compute NEV Ritz vectors;</para>
 
54
                        </listitem>
 
55
                        <listitem>
 
56
                            <para>
 
57
                                'S': compute some of the Ritz vectors, specified by the
 
58
                                integer array SELECT.
 
59
                            </para>
 
60
                        </listitem>
 
61
                    </itemizedlist>
 
62
                </listitem>
 
63
            </varlistentry>
 
64
            <varlistentry>
 
65
                <term>SELECT</term>
 
66
                <listitem>
 
67
                    <para>Integer array of dimension NCV. (INPUT/WORKSPACE) </para>
 
68
                    <para>
 
69
                        If HOWMANY = 'S', SELECT specifies the Ritz vectors to be
 
70
                        computed. To select the Ritz vector corresponding to a Ritz value
 
71
                        D(j), SELECT(j) must be set to 1.
 
72
                    </para>
 
73
                    <para>
 
74
                        If HOWMANY = 'A' , SELECT is used as a workspace for
 
75
                        reordering the Ritz values.
 
76
                    </para>
 
77
                </listitem>
 
78
            </varlistentry>
 
79
            <varlistentry>
 
80
                <term>D</term>
 
81
                <listitem>
 
82
                    <para>Double precision array of dimension NEV. (OUTPUT) </para>
 
83
                    <para>
 
84
                        On exit, D contains the Ritz value approximations to the
 
85
                        eigenvalues of A * z = lambda * B * z. The values are returned in
 
86
                        ascending order.
 
87
                    </para>
 
88
                    <para>
 
89
                        If IPARAM(7) = 3, 4, 5 then D represents the Ritz values of OP
 
90
                        computed by dsaupd transformed to those of the original eigensystem
 
91
                        A * z = lambda * B * z.
 
92
                    </para>
 
93
                    <para>
 
94
                        If IPARAM(7) = 1, 2 then the Ritz values of OP are the same as
 
95
                        the those of A * z = lambda * B * z.
 
96
                    </para>
 
97
                </listitem>
 
98
            </varlistentry>
 
99
            <varlistentry>
 
100
                <term>Z</term>
 
101
                <listitem>
 
102
                    <para>Double precision N by NEV array.</para>
 
103
                    <para>
 
104
                        If HOWMNY = 'A'. (OUTPUT) On exit, Z contains the
 
105
                        B-orthonormal Ritz vectors of the eigensystemA * z = lambda * B * z
 
106
                        corresponding to the Ritz value approximations.
 
107
                    </para>
 
108
                    <para>If RVEC = 0 then Z is not referenced. </para>
 
109
                    <para>
 
110
                        NOTE: The array Z may be set equal to first NEV columns of the
 
111
                        Arnoldi/Lanczos basis array V computed by DSAUPD .
 
112
                    </para>
 
113
                </listitem>
 
114
            </varlistentry>
 
115
            <varlistentry>
 
116
                <term>SIGMA</term>
 
117
                <listitem>
 
118
                    <para>Double precision (INPUT) </para>
 
119
                    <para>
 
120
                        If IPARAM(7) = 3, 4, 5 represents the shift. Not referenced if
 
121
                        IPARAM(7) = 1 or 2.
 
122
                    </para>
 
123
                </listitem>
 
124
            </varlistentry>
 
125
        </variablelist>
 
126
        <para>
 
127
            NOTE: The remaining arguments BMAT, N, WHICH, NEV, TOL, RESID, NCV,
 
128
            V, IPARAM, IPNTR, WORKD, WORKL, LWORKL, INFO must be passed directly to
 
129
            DSEUPD following the last call to DSAUPD .
 
130
        </para>
 
131
        <para>
 
132
            These arguments MUST NOT BE MODIFIED between the last call to
 
133
            DSAUPD and the call to DSEUPD.
 
134
        </para>
 
135
        <para>
 
136
            Two of these parameters (WORKL, INFO) are also output
 
137
            parameters.
 
138
        </para>
 
139
        <variablelist>
 
140
            <varlistentry>
 
141
                <term>WORKL</term>
 
142
                <listitem>
 
143
                    <para>
 
144
                        Double precision work array of length LWORKL.
 
145
                        (OUTPUT/WORKSPACE)
 
146
                    </para>
 
147
                    <para>
 
148
                        WORKL(1:4*ncv) contains information obtained in dsaupd. They
 
149
                        are not changed by dseupd.
 
150
                    </para>
 
151
                    <para>
 
152
                        WORKL(4*ncv+1:ncv*ncv+8*ncv) holds the untransformed Ritz
 
153
                        values, the computed error estimates, and the associated eigenvector
 
154
                        matrix of H.
 
155
                    </para>
 
156
                    <para>
 
157
                        Note: IPNTR(8:10) contains the pointer into WORKL for
 
158
                        addresses of the above information computed by dseupd .
 
159
                    </para>
 
160
                    <itemizedlist>
 
161
                        <listitem>
 
162
                            <para>
 
163
                                IPNTR(8): pointer to the NCV RITZ values of the original
 
164
                                system.
 
165
                            </para>
 
166
                        </listitem>
 
167
                        <listitem>
 
168
                            <para>
 
169
                                IPNTR(9): pointer to the NCV corresponding error bounds.
 
170
                            </para>
 
171
                        </listitem>
 
172
                        <listitem>
 
173
                            <para>
 
174
                                IPNTR(10): pointer to the NCV by NCV matrix of
 
175
                                eigenvectors of the tridiagonal matrix T. Only referenced by
 
176
                                dseupd if RVEC = 1 See Remarks.
 
177
                            </para>
 
178
                        </listitem>
 
179
                    </itemizedlist>
 
180
                </listitem>
 
181
            </varlistentry>
 
182
            <varlistentry>
 
183
                <term>INFO</term>
 
184
                <listitem>
 
185
                    <para>Integer. (OUTPUT) </para>
 
186
                    <para>Error flag on output.</para>
 
187
                    <itemizedlist>
 
188
                        <listitem>
 
189
                            <para>0: Normal exit.</para>
 
190
                        </listitem>
 
191
                        <listitem>
 
192
                            <para>-1: N must be positive.</para>
 
193
                        </listitem>
 
194
                        <listitem>
 
195
                            <para>-2: NEV must be positive.</para>
 
196
                        </listitem>
 
197
                        <listitem>
 
198
                            <para>
 
199
                                -3: NCV must be greater than NEV and less than or equal to
 
200
                                N.
 
201
                            </para>
 
202
                        </listitem>
 
203
                        <listitem>
 
204
                            <para>
 
205
                                -5: WHICH must be one of 'LM', 'SM', 'LA', 'SA' or
 
206
                                'BE'.
 
207
                            </para>
 
208
                        </listitem>
 
209
                        <listitem>
 
210
                            <para>-6: BMAT must be one of 'I' or 'G'.</para>
 
211
                        </listitem>
 
212
                        <listitem>
 
213
                            <para>
 
214
                                -7: Length of private work WORKL array is not
 
215
                                sufficient.
 
216
                            </para>
 
217
                        </listitem>
 
218
                        <listitem>
 
219
                            <para>
 
220
                                -8: Error return from trid. eigenvalue calculation;
 
221
                                Information error from LAPACK routine dsteqr.
 
222
                            </para>
 
223
                        </listitem>
 
224
                        <listitem>
 
225
                            <para>-9: Starting vector is zero.</para>
 
226
                        </listitem>
 
227
                        <listitem>
 
228
                            <para>-10: IPARAM(7) must be 1, 2, 3, 4, 5.</para>
 
229
                        </listitem>
 
230
                        <listitem>
 
231
                            <para>-11: IPARAM(7) = 1 and BMAT = 'G' are incompatible.</para>
 
232
                        </listitem>
 
233
                        <listitem>
 
234
                            <para>-12: NEV and WHICH = 'BE' are incompatible.</para>
 
235
                        </listitem>
 
236
                        <listitem>
 
237
                            <para>
 
238
                                -14: DSAUPD did not find any eigenvalues to sufficient
 
239
                                accuracy.
 
240
                            </para>
 
241
                        </listitem>
 
242
                        <listitem>
 
243
                            <para>-15: HOWMNY must be one of 'A' or 'S' if RVEC = 1.</para>
 
244
                        </listitem>
 
245
                        <listitem>
 
246
                            <para>-16: HOWMNY = 'S' not yet implemented.</para>
 
247
                        </listitem>
 
248
                        <listitem>
 
249
                            <para>
 
250
                                -17: DSEUPD got a different count of the number of
 
251
                                converged Ritz values than DSAUPD got. This indicates the user
 
252
                                probably made an error in passing data from DSAUPD to DSEUPD or
 
253
                                that the data was modified before entering DSEUPD.
 
254
                            </para>
 
255
                        </listitem>
 
256
                    </itemizedlist>
 
257
                </listitem>
 
258
            </varlistentry>
 
259
        </variablelist>
 
260
    </refsection>
 
261
    <refsection>
 
262
        <title>Description</title>
 
263
        <para>
 
264
            This subroutine returns the converged approximations to eigenvalues
 
265
            of A * z = lambda * B * z and (optionally):
 
266
        </para>
 
267
        <orderedlist>
 
268
            <listitem>
 
269
                <para>the corresponding approximate eigenvectors,</para>
 
270
            </listitem>
 
271
            <listitem>
 
272
                <para>
 
273
                    an orthonormal (Lanczos) basis for the associated approximate
 
274
                    invariant subspace,
 
275
                </para>
 
276
            </listitem>
 
277
            <listitem>
 
278
                <para>Both. </para>
 
279
            </listitem>
 
280
        </orderedlist>
 
281
        <para>
 
282
            There is negligible additional cost to obtain eigenvectors. An
 
283
            orthonormal (Lanczos) basis is always computed. There is an additional
 
284
            storage cost of n*nev if both are requested (in this case a separate array
 
285
            Z must be supplied).
 
286
        </para>
 
287
        <para>
 
288
            These quantities are obtained from the Lanczos factorization
 
289
            computed by DSAUPD for the linear operator OP prescribed by the MODE
 
290
            selection (see IPARAM(7) in DSAUPD documentation.) DSAUPD must be called
 
291
            before this routine is called.
 
292
        </para>
 
293
        <para>
 
294
            These approximate eigenvalues and vectors are commonly called Ritz
 
295
            values and Ritz vectors respectively. They are referred to as such in the
 
296
            comments that follow.
 
297
        </para>
 
298
        <para>
 
299
            The computed orthonormal basis for the invariant subspace
 
300
            corresponding to these Ritz values is referred to as a Lanczos basis.
 
301
        </para>
 
302
        <para>
 
303
            See documentation in the header of the subroutine DSAUPD for a
 
304
            definition of OP as well as other terms and the relation of computed Ritz
 
305
            values and vectors of OP with respect to the given problem A * z = lambda * B * z.
 
306
        </para>
 
307
        <para>
 
308
            The approximate eigenvalues of the original problem are returned in
 
309
            ascending algebraic order.
 
310
        </para>
 
311
        <para>
 
312
            The user may elect to call this routine once for each desired Ritz
 
313
            vector and store it peripherally if desired. There is also the option of
 
314
            computing a selected set of these vectors with a single call.
 
315
        </para>
 
316
    </refsection>
 
317
    <refsection>
 
318
        <title>Remarks</title>
 
319
        <para>
 
320
            1. The converged Ritz values are always returned in increasing
 
321
            (algebraic) order. c 2. Currently only HOWMNY = 'A' is implemented. It is
 
322
            included at this stage for the user who wants to incorporate it.
 
323
        </para>
 
324
    </refsection>
 
325
    <refsection>
 
326
        <title>Example</title>
 
327
        <programlisting role="example">
 
328
            <![CDATA[ 
326
329
 
327
330
// The following sets dimensions for this problem.
328
331
 
411
414
printf('The convergence criterion is %d\n', tol);
412
415
 
413
416
]]>
414
 
    </programlisting>
415
 
  </refsection>
416
 
  <refsection role="see also">
417
 
    <title>See Also</title>
418
 
    <simplelist type="inline">
419
 
      <member>
420
 
        <link linkend="dsaupd">dsaupd</link>
421
 
      </member>
422
 
      <member>
423
 
        <link linkend="dneupd">dneupd</link>
424
 
      </member>
425
 
    </simplelist>
426
 
  </refsection>
427
 
  <refsection>
428
 
    <title>Bibliography</title>
429
 
    <para>
430
 
      1. D.C. Sorensen, "Implicit Application of Polynomial Filters in
431
 
      k-Step Arnoldi Method", SIAM J. Matr. Anal. Apps., 13 (1992), pp
432
 
      357-385.
433
 
    </para>
434
 
    <para>
435
 
      2. R.B. Lehoucq, "Analysis and Implementation of an Implicitly
436
 
      Restarted Arnoldi Iteration", Rice University Technical Report TR95-13,
437
 
      Department of Computational and Applied Mathematics.
438
 
    </para>
439
 
    <para>
440
 
      3. B.N. Parlett and Y. Saad, "Complex Shift and Invert Strategies
441
 
      for Real Matrices", Linear Algebra and its Applications, vol 88/89, pp
442
 
      575-595, (1987).
443
 
    </para>
444
 
  </refsection>
445
 
  <refsection>
446
 
    <title>Used Functions</title>
447
 
    <para>Based on ARPACK routine dseupd</para>
448
 
  </refsection>
 
417
        </programlisting>
 
418
    </refsection>
 
419
    <refsection role="see also">
 
420
        <title>See Also</title>
 
421
        <simplelist type="inline">
 
422
            <member>
 
423
                <link linkend="dsaupd">dsaupd</link>
 
424
            </member>
 
425
            <member>
 
426
                <link linkend="dneupd">dneupd</link>
 
427
            </member>
 
428
        </simplelist>
 
429
    </refsection>
 
430
    <refsection>
 
431
        <title>Bibliography</title>
 
432
        <para>
 
433
            1. D.C. Sorensen, "Implicit Application of Polynomial Filters in
 
434
            k-Step Arnoldi Method", SIAM J. Matr. Anal. Apps., 13 (1992), pp
 
435
            357-385.
 
436
        </para>
 
437
        <para>
 
438
            2. R.B. Lehoucq, "Analysis and Implementation of an Implicitly
 
439
            Restarted Arnoldi Iteration", Rice University Technical Report TR95-13,
 
440
            Department of Computational and Applied Mathematics.
 
441
        </para>
 
442
        <para>
 
443
            3. B.N. Parlett and Y. Saad, "Complex Shift and Invert Strategies
 
444
            for Real Matrices", Linear Algebra and its Applications, vol 88/89, pp
 
445
            575-595, (1987).
 
446
        </para>
 
447
    </refsection>
 
448
    <refsection>
 
449
        <title>Used Functions</title>
 
450
        <para>Based on ARPACK routine dseupd</para>
 
451
    </refsection>
 
452
    <refsection>
 
453
        <title>History</title>
 
454
        <revhistory>
 
455
            <revision>
 
456
                <revnumber>5.4.0</revnumber>
 
457
                <revremark>
 
458
                    Function obsolete for <link linkend="eigs">eigs</link>.
 
459
                </revremark>
 
460
            </revision>
 
461
        </revhistory>
 
462
    </refsection>
449
463
</refentry>