Line data Source code
1 : /*
2 : - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
3 : SLEPc - Scalable Library for Eigenvalue Problem Computations
4 : Copyright (c) 2002-, Universitat Politecnica de Valencia, Spain
5 :
6 : This file is part of SLEPc.
7 : SLEPc is distributed under a 2-clause BSD license (see LICENSE).
8 : - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
9 : */
10 : /*
11 : SVD routines for setting solver options
12 : */
13 :
14 : #include <slepc/private/svdimpl.h> /*I "slepcsvd.h" I*/
15 : #include <petscdraw.h>
16 :
17 : /*@
18 : SVDSetImplicitTranspose - Indicates how to handle the transpose of the matrix
19 : associated with the singular value problem.
20 :
21 : Logically Collective
22 :
23 : Input Parameters:
24 : + svd - the singular value solver context
25 : - impl - how to handle the transpose (implicitly or not)
26 :
27 : Options Database Key:
28 : . -svd_implicittranspose - Activate the implicit transpose mode.
29 :
30 : Notes:
31 : By default, the transpose of the matrix is explicitly built (if the matrix
32 : has defined the MatTranspose operation).
33 :
34 : If this flag is set to true, the solver does not build the transpose, but
35 : handles it implicitly via MatMultTranspose() (or MatMultHermitianTranspose()
36 : in the complex case) operations. This is likely to be more inefficient
37 : than the default behaviour, both in sequential and in parallel, but
38 : requires less storage.
39 :
40 : Level: advanced
41 :
42 : .seealso: SVDGetImplicitTranspose(), SVDSolve(), SVDSetOperators()
43 : @*/
44 25 : PetscErrorCode SVDSetImplicitTranspose(SVD svd,PetscBool impl)
45 : {
46 25 : PetscFunctionBegin;
47 25 : PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
48 75 : PetscValidLogicalCollectiveBool(svd,impl,2);
49 25 : if (svd->impltrans!=impl) {
50 19 : svd->impltrans = impl;
51 19 : svd->state = SVD_STATE_INITIAL;
52 : }
53 25 : PetscFunctionReturn(PETSC_SUCCESS);
54 : }
55 :
56 : /*@
57 : SVDGetImplicitTranspose - Gets the mode used to handle the transpose
58 : of the matrix associated with the singular value problem.
59 :
60 : Not Collective
61 :
62 : Input Parameter:
63 : . svd - the singular value solver context
64 :
65 : Output Parameter:
66 : . impl - how to handle the transpose (implicitly or not)
67 :
68 : Level: advanced
69 :
70 : .seealso: SVDSetImplicitTranspose(), SVDSolve(), SVDSetOperators()
71 : @*/
72 12 : PetscErrorCode SVDGetImplicitTranspose(SVD svd,PetscBool *impl)
73 : {
74 12 : PetscFunctionBegin;
75 12 : PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
76 12 : PetscAssertPointer(impl,2);
77 12 : *impl = svd->impltrans;
78 12 : PetscFunctionReturn(PETSC_SUCCESS);
79 : }
80 :
81 : /*@
82 : SVDSetTolerances - Sets the tolerance and maximum
83 : iteration count used by the default SVD convergence testers.
84 :
85 : Logically Collective
86 :
87 : Input Parameters:
88 : + svd - the singular value solver context
89 : . tol - the convergence tolerance
90 : - maxits - maximum number of iterations to use
91 :
92 : Options Database Keys:
93 : + -svd_tol <tol> - Sets the convergence tolerance
94 : - -svd_max_it <maxits> - Sets the maximum number of iterations allowed
95 :
96 : Note:
97 : Use PETSC_CURRENT to retain the current value of any of the parameters.
98 : Use PETSC_DETERMINE for either argument to assign a default value computed
99 : internally (may be different in each solver).
100 : For maxits use PETSC_UMLIMITED to indicate there is no upper bound on this value.
101 :
102 : Level: intermediate
103 :
104 : .seealso: SVDGetTolerances()
105 : @*/
106 61 : PetscErrorCode SVDSetTolerances(SVD svd,PetscReal tol,PetscInt maxits)
107 : {
108 61 : PetscFunctionBegin;
109 61 : PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
110 183 : PetscValidLogicalCollectiveReal(svd,tol,2);
111 183 : PetscValidLogicalCollectiveInt(svd,maxits,3);
112 61 : if (tol == (PetscReal)PETSC_DETERMINE) {
113 6 : svd->tol = PETSC_DETERMINE;
114 6 : svd->state = SVD_STATE_INITIAL;
115 55 : } else if (tol != (PetscReal)PETSC_CURRENT) {
116 40 : PetscCheck(tol>0.0,PetscObjectComm((PetscObject)svd),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
117 40 : svd->tol = tol;
118 : }
119 61 : if (maxits == PETSC_DETERMINE) {
120 11 : svd->max_it = PETSC_DETERMINE;
121 11 : svd->state = SVD_STATE_INITIAL;
122 50 : } else if (maxits == PETSC_UNLIMITED) {
123 0 : svd->max_it = PETSC_INT_MAX;
124 50 : } else if (maxits != PETSC_CURRENT) {
125 42 : PetscCheck(maxits>0,PetscObjectComm((PetscObject)svd),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of maxits. Must be > 0");
126 42 : svd->max_it = maxits;
127 : }
128 61 : PetscFunctionReturn(PETSC_SUCCESS);
129 : }
130 :
131 : /*@
132 : SVDGetTolerances - Gets the tolerance and maximum
133 : iteration count used by the default SVD convergence tests.
134 :
135 : Not Collective
136 :
137 : Input Parameter:
138 : . svd - the singular value solver context
139 :
140 : Output Parameters:
141 : + tol - the convergence tolerance
142 : - maxits - maximum number of iterations
143 :
144 : Notes:
145 : The user can specify NULL for any parameter that is not needed.
146 :
147 : Level: intermediate
148 :
149 : .seealso: SVDSetTolerances()
150 : @*/
151 93 : PetscErrorCode SVDGetTolerances(SVD svd,PetscReal *tol,PetscInt *maxits)
152 : {
153 93 : PetscFunctionBegin;
154 93 : PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
155 93 : if (tol) *tol = svd->tol;
156 93 : if (maxits) *maxits = svd->max_it;
157 93 : PetscFunctionReturn(PETSC_SUCCESS);
158 : }
159 :
160 : /*@
161 : SVDSetThreshold - Sets the threshold used in the threshold stopping test.
162 :
163 : Logically Collective
164 :
165 : Input Parameters:
166 : + svd - the singular value solver context
167 : . thres - the threshold value
168 : - rel - whether the threshold is relative or not
169 :
170 : Options Database Keys:
171 : + -svd_threshold_absolute <thres> - Sets an absolute threshold
172 : - -svd_threshold_relative <thres> - Sets a relative threshold
173 :
174 : Notes:
175 : This function internally calls SVDSetStoppingTest() to set a special stopping
176 : test based on the threshold, where singular values are computed in sequence
177 : until one of the computed singular values is below the threshold.
178 :
179 : If the solver is configured to compute smallest singular values, then the
180 : threshold must be interpreted in the opposite direction, i.e., the computation
181 : will stop when one of the computed singular values is above the threshold.
182 :
183 : In the case of largest singular values, the threshold can be made relative
184 : with respect to the largest singular value (i.e., the matrix norm).
185 :
186 : The test against the threshold is done for converged singular values, which
187 : implies that the final number of converged singular values will be at least
188 : one more than the actual number of values below/above the threshold.
189 :
190 : Since the number of computed singular values is not known a priori, the solver
191 : will need to reallocate the basis of vectors internally, to have enough room
192 : to accommodate all the singular vectors. Hence, this option must be used with
193 : caution to avoid out-of-memory problems. The recommendation is to set the value
194 : of ncv to be larger than the estimated number of singular values, to minimize
195 : the number of reallocations.
196 :
197 : This functionality is most useful when computing largest singular values. A
198 : typical use case is to compute a low rank approximation of a matrix. Suppose
199 : we know that singular values decay abruptly around a certain index k, which
200 : is unknown. Then using a small relative threshold such as 0.2 will guarantee that
201 : the computed singular vectors capture the numerical rank k. However, if the matrix
202 : does not have low rank, i.e., singular values decay progressively, then a
203 : value of 0.2 will imply a very high cost, both computationally and in memory.
204 :
205 : If a number of wanted singular values has been set with SVDSetDimensions()
206 : it is also taken into account and the solver will stop when one of the two
207 : conditions (threshold or number of converged values) is met.
208 :
209 : Use SVDSetStoppingTest() to return to the usual computation of a fixed number
210 : of singular values.
211 :
212 : Level: advanced
213 :
214 : .seealso: SVDGetThreshold(), SVDSetStoppingTest(), SVDSetDimensions(), SVDSetWhichSingularTriplets()
215 : @*/
216 12 : PetscErrorCode SVDSetThreshold(SVD svd,PetscReal thres,PetscBool rel)
217 : {
218 12 : PetscFunctionBegin;
219 12 : PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
220 36 : PetscValidLogicalCollectiveReal(svd,thres,2);
221 36 : PetscValidLogicalCollectiveBool(svd,rel,3);
222 12 : PetscCheck(thres>0.0,PetscObjectComm((PetscObject)svd),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of the threshold. Must be > 0");
223 12 : if (svd->thres != thres || svd->threlative != rel) {
224 12 : svd->thres = thres;
225 12 : svd->threlative = rel;
226 12 : svd->state = SVD_STATE_INITIAL;
227 12 : PetscCall(SVDSetStoppingTest(svd,SVD_STOP_THRESHOLD));
228 : }
229 12 : PetscFunctionReturn(PETSC_SUCCESS);
230 : }
231 :
232 : /*@
233 : SVDGetThreshold - Gets the threshold used by the threshold stopping test.
234 :
235 : Not Collective
236 :
237 : Input Parameter:
238 : . svd - the singular value solver context
239 :
240 : Output Parameters:
241 : + thres - the threshold
242 : - rel - whether the threshold is relative or not
243 :
244 : Level: advanced
245 :
246 : .seealso: SVDSetThreshold()
247 : @*/
248 6 : PetscErrorCode SVDGetThreshold(SVD svd,PetscReal *thres,PetscBool *rel)
249 : {
250 6 : PetscFunctionBegin;
251 6 : PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
252 6 : if (thres) *thres = svd->thres;
253 6 : if (rel) *rel = svd->threlative;
254 6 : PetscFunctionReturn(PETSC_SUCCESS);
255 : }
256 :
257 : /*@
258 : SVDSetDimensions - Sets the number of singular values to compute
259 : and the dimension of the subspace.
260 :
261 : Logically Collective
262 :
263 : Input Parameters:
264 : + svd - the singular value solver context
265 : . nsv - number of singular values to compute
266 : . ncv - the maximum dimension of the subspace to be used by the solver
267 : - mpd - the maximum dimension allowed for the projected problem
268 :
269 : Options Database Keys:
270 : + -svd_nsv <nsv> - Sets the number of singular values
271 : . -svd_ncv <ncv> - Sets the dimension of the subspace
272 : - -svd_mpd <mpd> - Sets the maximum projected dimension
273 :
274 : Notes:
275 : Use PETSC_DETERMINE for ncv and mpd to assign a reasonably good value, which is
276 : dependent on the solution method and the number of singular values required. For
277 : any of the arguments, use PETSC_CURRENT to preserve the current value.
278 :
279 : The parameters ncv and mpd are intimately related, so that the user is advised
280 : to set one of them at most. Normal usage is that
281 : (a) in cases where nsv is small, the user sets ncv (a reasonable default is 2*nsv); and
282 : (b) in cases where nsv is large, the user sets mpd.
283 :
284 : The value of ncv should always be between nsv and (nsv+mpd), typically
285 : ncv=nsv+mpd. If nsv is not too large, mpd=nsv is a reasonable choice, otherwise
286 : a smaller value should be used.
287 :
288 : Level: intermediate
289 :
290 : .seealso: SVDGetDimensions()
291 : @*/
292 217 : PetscErrorCode SVDSetDimensions(SVD svd,PetscInt nsv,PetscInt ncv,PetscInt mpd)
293 : {
294 217 : PetscFunctionBegin;
295 217 : PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
296 651 : PetscValidLogicalCollectiveInt(svd,nsv,2);
297 651 : PetscValidLogicalCollectiveInt(svd,ncv,3);
298 651 : PetscValidLogicalCollectiveInt(svd,mpd,4);
299 217 : if (nsv != PETSC_CURRENT) {
300 208 : PetscCheck(nsv>0,PetscObjectComm((PetscObject)svd),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of nsv. Must be > 0");
301 208 : svd->nsv = nsv;
302 : }
303 217 : if (ncv == PETSC_DETERMINE) {
304 136 : svd->ncv = PETSC_DETERMINE;
305 81 : } else if (ncv != PETSC_CURRENT) {
306 81 : PetscCheck(ncv>0,PetscObjectComm((PetscObject)svd),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of ncv. Must be > 0");
307 81 : svd->ncv = ncv;
308 : }
309 217 : if (mpd == PETSC_DETERMINE) {
310 215 : svd->mpd = PETSC_DETERMINE;
311 2 : } else if (mpd != PETSC_CURRENT) {
312 2 : PetscCheck(mpd>0,PetscObjectComm((PetscObject)svd),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of mpd. Must be > 0");
313 2 : svd->mpd = mpd;
314 : }
315 217 : svd->state = SVD_STATE_INITIAL;
316 217 : PetscFunctionReturn(PETSC_SUCCESS);
317 : }
318 :
319 : /*@
320 : SVDGetDimensions - Gets the number of singular values to compute
321 : and the dimension of the subspace.
322 :
323 : Not Collective
324 :
325 : Input Parameter:
326 : . svd - the singular value context
327 :
328 : Output Parameters:
329 : + nsv - number of singular values to compute
330 : . ncv - the maximum dimension of the subspace to be used by the solver
331 : - mpd - the maximum dimension allowed for the projected problem
332 :
333 : Notes:
334 : The user can specify NULL for any parameter that is not needed.
335 :
336 : Level: intermediate
337 :
338 : .seealso: SVDSetDimensions()
339 : @*/
340 93 : PetscErrorCode SVDGetDimensions(SVD svd,PetscInt *nsv,PetscInt *ncv,PetscInt *mpd)
341 : {
342 93 : PetscFunctionBegin;
343 93 : PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
344 184 : if (nsv) *nsv = svd->nsv? svd->nsv: 1;
345 93 : if (ncv) *ncv = svd->ncv;
346 93 : if (mpd) *mpd = svd->mpd;
347 93 : PetscFunctionReturn(PETSC_SUCCESS);
348 : }
349 :
350 : /*@
351 : SVDSetWhichSingularTriplets - Specifies which singular triplets are
352 : to be sought.
353 :
354 : Logically Collective
355 :
356 : Input Parameter:
357 : . svd - singular value solver context obtained from SVDCreate()
358 :
359 : Output Parameter:
360 : . which - which singular triplets are to be sought
361 :
362 : Options Database Keys:
363 : + -svd_largest - Sets largest singular values
364 : - -svd_smallest - Sets smallest singular values
365 :
366 : Notes:
367 : The parameter 'which' can have one of these values
368 :
369 : + SVD_LARGEST - largest singular values
370 : - SVD_SMALLEST - smallest singular values
371 :
372 : Level: intermediate
373 :
374 : .seealso: SVDGetWhichSingularTriplets(), SVDWhich
375 : @*/
376 55 : PetscErrorCode SVDSetWhichSingularTriplets(SVD svd,SVDWhich which)
377 : {
378 55 : PetscFunctionBegin;
379 55 : PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
380 165 : PetscValidLogicalCollectiveEnum(svd,which,2);
381 55 : switch (which) {
382 55 : case SVD_LARGEST:
383 : case SVD_SMALLEST:
384 55 : if (svd->which != which) {
385 39 : svd->state = SVD_STATE_INITIAL;
386 39 : svd->which = which;
387 : }
388 55 : break;
389 0 : default:
390 0 : SETERRQ(PetscObjectComm((PetscObject)svd),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'which' parameter");
391 : }
392 55 : PetscFunctionReturn(PETSC_SUCCESS);
393 : }
394 :
395 : /*@
396 : SVDGetWhichSingularTriplets - Returns which singular triplets are
397 : to be sought.
398 :
399 : Not Collective
400 :
401 : Input Parameter:
402 : . svd - singular value solver context obtained from SVDCreate()
403 :
404 : Output Parameter:
405 : . which - which singular triplets are to be sought
406 :
407 : Notes:
408 : See SVDSetWhichSingularTriplets() for possible values of which
409 :
410 : Level: intermediate
411 :
412 : .seealso: SVDSetWhichSingularTriplets(), SVDWhich
413 : @*/
414 12 : PetscErrorCode SVDGetWhichSingularTriplets(SVD svd,SVDWhich *which)
415 : {
416 12 : PetscFunctionBegin;
417 12 : PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
418 12 : PetscAssertPointer(which,2);
419 12 : *which = svd->which;
420 12 : PetscFunctionReturn(PETSC_SUCCESS);
421 : }
422 :
423 : /*@C
424 : SVDSetConvergenceTestFunction - Sets a function to compute the error estimate
425 : used in the convergence test.
426 :
427 : Logically Collective
428 :
429 : Input Parameters:
430 : + svd - singular value solver context obtained from SVDCreate()
431 : . conv - the convergence test function, see SVDConvergenceTestFn for the calling sequence
432 : . ctx - context for private data for the convergence routine (may be NULL)
433 : - destroy - a routine for destroying the context (may be NULL), see PetscCtxDestroyFn for the calling sequence
434 :
435 : Note:
436 : If the error estimate returned by the convergence test function is less than
437 : the tolerance, then the singular value is accepted as converged.
438 :
439 : Level: advanced
440 :
441 : .seealso: SVDSetConvergenceTest(), SVDSetTolerances()
442 : @*/
443 1 : PetscErrorCode SVDSetConvergenceTestFunction(SVD svd,SVDConvergenceTestFn *conv,void* ctx,PetscCtxDestroyFn *destroy)
444 : {
445 1 : PetscFunctionBegin;
446 1 : PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
447 1 : if (svd->convergeddestroy) PetscCall((*svd->convergeddestroy)(&svd->convergedctx));
448 1 : svd->convergeduser = conv;
449 1 : svd->convergeddestroy = destroy;
450 1 : svd->convergedctx = ctx;
451 1 : if (conv == SVDConvergedAbsolute) svd->conv = SVD_CONV_ABS;
452 1 : else if (conv == SVDConvergedRelative) svd->conv = SVD_CONV_REL;
453 1 : else if (conv == SVDConvergedNorm) svd->conv = SVD_CONV_NORM;
454 1 : else if (conv == SVDConvergedMaxIt) svd->conv = SVD_CONV_MAXIT;
455 : else {
456 1 : svd->conv = SVD_CONV_USER;
457 1 : svd->converged = svd->convergeduser;
458 : }
459 1 : PetscFunctionReturn(PETSC_SUCCESS);
460 : }
461 :
462 : /*@
463 : SVDSetConvergenceTest - Specifies how to compute the error estimate
464 : used in the convergence test.
465 :
466 : Logically Collective
467 :
468 : Input Parameters:
469 : + svd - singular value solver context obtained from SVDCreate()
470 : - conv - the type of convergence test
471 :
472 : Options Database Keys:
473 : + -svd_conv_abs - Sets the absolute convergence test
474 : . -svd_conv_rel - Sets the convergence test relative to the singular value
475 : . -svd_conv_norm - Sets the convergence test relative to the matrix norm
476 : . -svd_conv_maxit - Forces the maximum number of iterations as set by -svd_max_it
477 : - -svd_conv_user - Selects the user-defined convergence test
478 :
479 : Notes:
480 : The parameter 'conv' can have one of these values
481 : + SVD_CONV_ABS - absolute error ||r||
482 : . SVD_CONV_REL - error relative to the singular value sigma, ||r||/sigma
483 : . SVD_CONV_NORM - error relative to the matrix norms, ||r||/||Z||, with Z=A or Z=[A;B]
484 : . SVD_CONV_MAXIT - no convergence until maximum number of iterations has been reached
485 : - SVD_CONV_USER - function set by SVDSetConvergenceTestFunction()
486 :
487 : The default in standard SVD is SVD_CONV_REL, while in GSVD the default is SVD_CONV_NORM.
488 :
489 : Level: intermediate
490 :
491 : .seealso: SVDGetConvergenceTest(), SVDSetConvergenceTestFunction(), SVDSetStoppingTest(), SVDConv
492 : @*/
493 239 : PetscErrorCode SVDSetConvergenceTest(SVD svd,SVDConv conv)
494 : {
495 239 : PetscFunctionBegin;
496 239 : PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
497 717 : PetscValidLogicalCollectiveEnum(svd,conv,2);
498 239 : switch (conv) {
499 12 : case SVD_CONV_ABS: svd->converged = SVDConvergedAbsolute; break;
500 133 : case SVD_CONV_REL: svd->converged = SVDConvergedRelative; break;
501 92 : case SVD_CONV_NORM: svd->converged = SVDConvergedNorm; break;
502 2 : case SVD_CONV_MAXIT: svd->converged = SVDConvergedMaxIt; break;
503 0 : case SVD_CONV_USER:
504 0 : PetscCheck(svd->convergeduser,PetscObjectComm((PetscObject)svd),PETSC_ERR_ORDER,"Must call SVDSetConvergenceTestFunction() first");
505 0 : svd->converged = svd->convergeduser;
506 0 : break;
507 0 : default:
508 0 : SETERRQ(PetscObjectComm((PetscObject)svd),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'conv' value");
509 : }
510 239 : svd->conv = conv;
511 239 : PetscFunctionReturn(PETSC_SUCCESS);
512 : }
513 :
514 : /*@
515 : SVDGetConvergenceTest - Gets the method used to compute the error estimate
516 : used in the convergence test.
517 :
518 : Not Collective
519 :
520 : Input Parameters:
521 : . svd - singular value solver context obtained from SVDCreate()
522 :
523 : Output Parameters:
524 : . conv - the type of convergence test
525 :
526 : Level: intermediate
527 :
528 : .seealso: SVDSetConvergenceTest(), SVDConv
529 : @*/
530 12 : PetscErrorCode SVDGetConvergenceTest(SVD svd,SVDConv *conv)
531 : {
532 12 : PetscFunctionBegin;
533 12 : PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
534 12 : PetscAssertPointer(conv,2);
535 12 : *conv = svd->conv;
536 12 : PetscFunctionReturn(PETSC_SUCCESS);
537 : }
538 :
539 : /*@C
540 : SVDSetStoppingTestFunction - Sets a function to decide when to stop the outer
541 : iteration of the singular value solver.
542 :
543 : Logically Collective
544 :
545 : Input Parameters:
546 : + svd - singular value solver context obtained from SVDCreate()
547 : . stop - the stopping test function, see SVDStoppingTestFn for the calling sequence
548 : . ctx - context for private data for the stopping routine (may be NULL)
549 : - destroy - a routine for destroying the context (may be NULL), see PetscCtxDestroyFn for the calling sequence
550 :
551 : Note:
552 : Normal usage is to first call the default routine SVDStoppingBasic() and then
553 : set reason to SVD_CONVERGED_USER if some user-defined conditions have been
554 : met. To let the singular value solver continue iterating, the result must be
555 : left as SVD_CONVERGED_ITERATING.
556 :
557 : Level: advanced
558 :
559 : .seealso: SVDSetStoppingTest(), SVDStoppingBasic()
560 : @*/
561 13 : PetscErrorCode SVDSetStoppingTestFunction(SVD svd,SVDStoppingTestFn *stop,void* ctx,PetscCtxDestroyFn *destroy)
562 : {
563 13 : PetscFunctionBegin;
564 13 : PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
565 13 : if (svd->stoppingdestroy) PetscCall((*svd->stoppingdestroy)(&svd->stoppingctx));
566 13 : svd->stoppinguser = stop;
567 13 : svd->stoppingdestroy = destroy;
568 13 : svd->stoppingctx = ctx;
569 13 : if (stop == SVDStoppingBasic) PetscCall(SVDSetStoppingTest(svd,SVD_STOP_BASIC));
570 13 : else if (stop == SVDStoppingThreshold) PetscCall(SVDSetStoppingTest(svd,SVD_STOP_THRESHOLD));
571 : else {
572 1 : svd->stop = SVD_STOP_USER;
573 1 : svd->stopping = svd->stoppinguser;
574 : }
575 13 : PetscFunctionReturn(PETSC_SUCCESS);
576 : }
577 :
578 : /*@
579 : SVDSetStoppingTest - Specifies how to decide the termination of the outer
580 : loop of the singular value solver.
581 :
582 : Logically Collective
583 :
584 : Input Parameters:
585 : + svd - singular value solver context obtained from SVDCreate()
586 : - stop - the type of stopping test
587 :
588 : Options Database Keys:
589 : + -svd_stop_basic - Sets the default stopping test
590 : . -svd_stop_threshold - Sets the threshold stopping test
591 : - -svd_stop_user - Selects the user-defined stopping test
592 :
593 : Note:
594 : The parameter 'stop' can have one of these values
595 : + SVD_STOP_BASIC - default stopping test
596 : . SVD_STOP_THRESHOLD - threshold stopping test
597 : - SVD_STOP_USER - function set by SVDSetStoppingTestFunction()
598 :
599 : Level: advanced
600 :
601 : .seealso: SVDGetStoppingTest(), SVDSetStoppingTestFunction(), SVDSetConvergenceTest(), SVDStop
602 : @*/
603 36 : PetscErrorCode SVDSetStoppingTest(SVD svd,SVDStop stop)
604 : {
605 36 : PetscFunctionBegin;
606 36 : PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
607 108 : PetscValidLogicalCollectiveEnum(svd,stop,2);
608 36 : switch (stop) {
609 12 : case SVD_STOP_BASIC: svd->stopping = SVDStoppingBasic; break;
610 24 : case SVD_STOP_THRESHOLD: svd->stopping = SVDStoppingThreshold; break;
611 0 : case SVD_STOP_USER:
612 0 : PetscCheck(svd->stoppinguser,PetscObjectComm((PetscObject)svd),PETSC_ERR_ORDER,"Must call SVDSetStoppingTestFunction() first");
613 0 : svd->stopping = svd->stoppinguser;
614 0 : break;
615 0 : default:
616 0 : SETERRQ(PetscObjectComm((PetscObject)svd),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'stop' value");
617 : }
618 36 : svd->stop = stop;
619 36 : PetscFunctionReturn(PETSC_SUCCESS);
620 : }
621 :
622 : /*@
623 : SVDGetStoppingTest - Gets the method used to decide the termination of the outer
624 : loop of the singular value solver.
625 :
626 : Not Collective
627 :
628 : Input Parameters:
629 : . svd - singular value solver context obtained from SVDCreate()
630 :
631 : Output Parameters:
632 : . stop - the type of stopping test
633 :
634 : Level: advanced
635 :
636 : .seealso: SVDSetStoppingTest(), SVDStop
637 : @*/
638 25 : PetscErrorCode SVDGetStoppingTest(SVD svd,SVDStop *stop)
639 : {
640 25 : PetscFunctionBegin;
641 25 : PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
642 25 : PetscAssertPointer(stop,2);
643 25 : *stop = svd->stop;
644 25 : PetscFunctionReturn(PETSC_SUCCESS);
645 : }
646 :
647 : /*@C
648 : SVDMonitorSetFromOptions - Sets a monitor function and viewer appropriate for the type
649 : indicated by the user.
650 :
651 : Collective
652 :
653 : Input Parameters:
654 : + svd - the singular value solver context
655 : . opt - the command line option for this monitor
656 : . name - the monitor type one is seeking
657 : . ctx - an optional user context for the monitor, or NULL
658 : - trackall - whether this monitor tracks all singular values or not
659 :
660 : Level: developer
661 :
662 : .seealso: SVDMonitorSet(), SVDSetTrackAll()
663 : @*/
664 924 : PetscErrorCode SVDMonitorSetFromOptions(SVD svd,const char opt[],const char name[],void *ctx,PetscBool trackall)
665 : {
666 924 : PetscErrorCode (*mfunc)(SVD,PetscInt,PetscInt,PetscReal*,PetscReal*,PetscInt,void*);
667 924 : PetscErrorCode (*cfunc)(PetscViewer,PetscViewerFormat,void*,PetscViewerAndFormat**);
668 924 : PetscErrorCode (*dfunc)(PetscViewerAndFormat**);
669 924 : PetscViewerAndFormat *vf;
670 924 : PetscViewer viewer;
671 924 : PetscViewerFormat format;
672 924 : PetscViewerType vtype;
673 924 : char key[PETSC_MAX_PATH_LEN];
674 924 : PetscBool flg;
675 :
676 924 : PetscFunctionBegin;
677 924 : PetscCall(PetscOptionsCreateViewer(PetscObjectComm((PetscObject)svd),((PetscObject)svd)->options,((PetscObject)svd)->prefix,opt,&viewer,&format,&flg));
678 924 : if (!flg) PetscFunctionReturn(PETSC_SUCCESS);
679 :
680 6 : PetscCall(PetscViewerGetType(viewer,&vtype));
681 6 : PetscCall(SlepcMonitorMakeKey_Internal(name,vtype,format,key));
682 6 : PetscCall(PetscFunctionListFind(SVDMonitorList,key,&mfunc));
683 6 : PetscCheck(mfunc,PetscObjectComm((PetscObject)svd),PETSC_ERR_SUP,"Specified viewer and format not supported");
684 6 : PetscCall(PetscFunctionListFind(SVDMonitorCreateList,key,&cfunc));
685 6 : PetscCall(PetscFunctionListFind(SVDMonitorDestroyList,key,&dfunc));
686 6 : if (!cfunc) cfunc = PetscViewerAndFormatCreate_Internal;
687 6 : if (!dfunc) dfunc = PetscViewerAndFormatDestroy;
688 :
689 6 : PetscCall((*cfunc)(viewer,format,ctx,&vf));
690 6 : PetscCall(PetscViewerDestroy(&viewer));
691 6 : PetscCall(SVDMonitorSet(svd,mfunc,vf,(PetscCtxDestroyFn*)dfunc));
692 6 : if (trackall) PetscCall(SVDSetTrackAll(svd,PETSC_TRUE));
693 6 : PetscFunctionReturn(PETSC_SUCCESS);
694 : }
695 :
696 : /*@
697 : SVDSetFromOptions - Sets SVD options from the options database.
698 : This routine must be called before SVDSetUp() if the user is to be
699 : allowed to set the solver type.
700 :
701 : Collective
702 :
703 : Input Parameters:
704 : . svd - the singular value solver context
705 :
706 : Notes:
707 : To see all options, run your program with the -help option.
708 :
709 : Level: beginner
710 :
711 : .seealso: SVDSetOptionsPrefix()
712 : @*/
713 231 : PetscErrorCode SVDSetFromOptions(SVD svd)
714 : {
715 231 : char type[256];
716 231 : PetscBool set,flg,val,flg1,flg2,flg3;
717 231 : PetscInt i,j,k;
718 231 : PetscReal r;
719 :
720 231 : PetscFunctionBegin;
721 231 : PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
722 231 : PetscCall(SVDRegisterAll());
723 693 : PetscObjectOptionsBegin((PetscObject)svd);
724 255 : PetscCall(PetscOptionsFList("-svd_type","SVD solver method","SVDSetType",SVDList,(char*)(((PetscObject)svd)->type_name?((PetscObject)svd)->type_name:SVDCROSS),type,sizeof(type),&flg));
725 231 : if (flg) PetscCall(SVDSetType(svd,type));
726 26 : else if (!((PetscObject)svd)->type_name) PetscCall(SVDSetType(svd,SVDCROSS));
727 :
728 231 : PetscCall(PetscOptionsBoolGroupBegin("-svd_standard","Singular value decomposition (SVD)","SVDSetProblemType",&flg));
729 231 : if (flg) PetscCall(SVDSetProblemType(svd,SVD_STANDARD));
730 231 : PetscCall(PetscOptionsBoolGroup("-svd_generalized","Generalized singular value decomposition (GSVD)","SVDSetProblemType",&flg));
731 231 : if (flg) PetscCall(SVDSetProblemType(svd,SVD_GENERALIZED));
732 231 : PetscCall(PetscOptionsBoolGroupEnd("-svd_hyperbolic","Hyperbolic singular value decomposition (HSVD)","SVDSetProblemType",&flg));
733 231 : if (flg) PetscCall(SVDSetProblemType(svd,SVD_HYPERBOLIC));
734 :
735 231 : PetscCall(PetscOptionsBool("-svd_implicittranspose","Handle matrix transpose implicitly","SVDSetImplicitTranspose",svd->impltrans,&val,&flg));
736 231 : if (flg) PetscCall(SVDSetImplicitTranspose(svd,val));
737 :
738 231 : i = svd->max_it;
739 231 : PetscCall(PetscOptionsInt("-svd_max_it","Maximum number of iterations","SVDSetTolerances",svd->max_it,&i,&flg1));
740 231 : r = svd->tol;
741 441 : PetscCall(PetscOptionsReal("-svd_tol","Tolerance","SVDSetTolerances",SlepcDefaultTol(svd->tol),&r,&flg2));
742 231 : if (flg1 || flg2) PetscCall(SVDSetTolerances(svd,r,i));
743 :
744 231 : r = svd->thres;
745 231 : PetscCall(PetscOptionsReal("-svd_threshold_absolute","Absolute threshold","SVDSetThreshold",r,&r,&flg));
746 231 : if (flg) PetscCall(SVDSetThreshold(svd,r,PETSC_FALSE));
747 231 : PetscCall(PetscOptionsReal("-svd_threshold_relative","Relative threshold","SVDSetThreshold",r,&r,&flg));
748 231 : if (flg) PetscCall(SVDSetThreshold(svd,r,PETSC_TRUE));
749 :
750 231 : PetscCall(PetscOptionsBoolGroupBegin("-svd_conv_abs","Absolute error convergence test","SVDSetConvergenceTest",&flg));
751 231 : if (flg) PetscCall(SVDSetConvergenceTest(svd,SVD_CONV_ABS));
752 231 : PetscCall(PetscOptionsBoolGroup("-svd_conv_rel","Relative error convergence test","SVDSetConvergenceTest",&flg));
753 231 : if (flg) PetscCall(SVDSetConvergenceTest(svd,SVD_CONV_REL));
754 231 : PetscCall(PetscOptionsBoolGroup("-svd_conv_norm","Convergence test relative to the matrix norms","SVDSetConvergenceTest",&flg));
755 231 : if (flg) PetscCall(SVDSetConvergenceTest(svd,SVD_CONV_NORM));
756 231 : PetscCall(PetscOptionsBoolGroup("-svd_conv_maxit","Maximum iterations convergence test","SVDSetConvergenceTest",&flg));
757 231 : if (flg) PetscCall(SVDSetConvergenceTest(svd,SVD_CONV_MAXIT));
758 231 : PetscCall(PetscOptionsBoolGroupEnd("-svd_conv_user","User-defined convergence test","SVDSetConvergenceTest",&flg));
759 231 : if (flg) PetscCall(SVDSetConvergenceTest(svd,SVD_CONV_USER));
760 :
761 231 : PetscCall(PetscOptionsBoolGroupBegin("-svd_stop_basic","Stop iteration if all singular values converged or max_it reached","SVDSetStoppingTest",&flg));
762 231 : if (flg) PetscCall(SVDSetStoppingTest(svd,SVD_STOP_BASIC));
763 231 : PetscCall(PetscOptionsBoolGroup("-svd_stop_threshold","Stop iteration if a converged singular value is below/above the threshold","SVDSetStoppingTest",&flg));
764 231 : if (flg) PetscCall(SVDSetStoppingTest(svd,SVD_STOP_THRESHOLD));
765 231 : PetscCall(PetscOptionsBoolGroupEnd("-svd_stop_user","User-defined stopping test","SVDSetStoppingTest",&flg));
766 231 : if (flg) PetscCall(SVDSetStoppingTest(svd,SVD_STOP_USER));
767 :
768 231 : i = svd->nsv;
769 231 : PetscCall(PetscOptionsInt("-svd_nsv","Number of singular values to compute","SVDSetDimensions",svd->nsv,&i,&flg1));
770 231 : if (!flg1) i = PETSC_CURRENT;
771 231 : j = svd->ncv;
772 231 : PetscCall(PetscOptionsInt("-svd_ncv","Number of basis vectors","SVDSetDimensions",svd->ncv,&j,&flg2));
773 231 : k = svd->mpd;
774 231 : PetscCall(PetscOptionsInt("-svd_mpd","Maximum dimension of projected problem","SVDSetDimensions",svd->mpd,&k,&flg3));
775 231 : if (flg1 || flg2 || flg3) PetscCall(SVDSetDimensions(svd,i,j,k));
776 :
777 231 : PetscCall(PetscOptionsBoolGroupBegin("-svd_largest","Compute largest singular values","SVDSetWhichSingularTriplets",&flg));
778 231 : if (flg) PetscCall(SVDSetWhichSingularTriplets(svd,SVD_LARGEST));
779 231 : PetscCall(PetscOptionsBoolGroupEnd("-svd_smallest","Compute smallest singular values","SVDSetWhichSingularTriplets",&flg));
780 231 : if (flg) PetscCall(SVDSetWhichSingularTriplets(svd,SVD_SMALLEST));
781 :
782 : /* -----------------------------------------------------------------------*/
783 : /*
784 : Cancels all monitors hardwired into code before call to SVDSetFromOptions()
785 : */
786 231 : PetscCall(PetscOptionsBool("-svd_monitor_cancel","Remove any hardwired monitor routines","SVDMonitorCancel",PETSC_FALSE,&flg,&set));
787 231 : if (set && flg) PetscCall(SVDMonitorCancel(svd));
788 231 : PetscCall(SVDMonitorSetFromOptions(svd,"-svd_monitor","first_approximation",NULL,PETSC_FALSE));
789 231 : PetscCall(SVDMonitorSetFromOptions(svd,"-svd_monitor_all","all_approximations",NULL,PETSC_TRUE));
790 231 : PetscCall(SVDMonitorSetFromOptions(svd,"-svd_monitor_conv","convergence_history",NULL,PETSC_FALSE));
791 231 : PetscCall(SVDMonitorSetFromOptions(svd,"-svd_monitor_conditioning","conditioning",NULL,PETSC_FALSE));
792 :
793 : /* -----------------------------------------------------------------------*/
794 231 : PetscCall(PetscOptionsName("-svd_view","Print detailed information on solver used","SVDView",&set));
795 231 : PetscCall(PetscOptionsName("-svd_view_vectors","View computed singular vectors","SVDVectorsView",&set));
796 231 : PetscCall(PetscOptionsName("-svd_view_values","View computed singular values","SVDValuesView",&set));
797 231 : PetscCall(PetscOptionsName("-svd_converged_reason","Print reason for convergence, and number of iterations","SVDConvergedReasonView",&set));
798 231 : PetscCall(PetscOptionsName("-svd_error_absolute","Print absolute errors of each singular triplet","SVDErrorView",&set));
799 231 : PetscCall(PetscOptionsName("-svd_error_relative","Print relative errors of each singular triplet","SVDErrorView",&set));
800 231 : PetscCall(PetscOptionsName("-svd_error_norm","Print errors relative to the matrix norms of each singular triplet","SVDErrorView",&set));
801 :
802 231 : PetscTryTypeMethod(svd,setfromoptions,PetscOptionsObject);
803 231 : PetscCall(PetscObjectProcessOptionsHandlers((PetscObject)svd,PetscOptionsObject));
804 231 : PetscOptionsEnd();
805 :
806 231 : if (!svd->V) PetscCall(SVDGetBV(svd,&svd->V,NULL));
807 231 : PetscCall(BVSetFromOptions(svd->V));
808 231 : if (!svd->U) PetscCall(SVDGetBV(svd,NULL,&svd->U));
809 231 : PetscCall(BVSetFromOptions(svd->U));
810 231 : if (!svd->ds) PetscCall(SVDGetDS(svd,&svd->ds));
811 231 : PetscCall(SVDSetDSType(svd));
812 231 : PetscCall(DSSetFromOptions(svd->ds));
813 231 : PetscFunctionReturn(PETSC_SUCCESS);
814 : }
815 :
816 : /*@
817 : SVDSetProblemType - Specifies the type of the singular value problem.
818 :
819 : Logically Collective
820 :
821 : Input Parameters:
822 : + svd - the singular value solver context
823 : - type - a known type of singular value problem
824 :
825 : Options Database Keys:
826 : + -svd_standard - standard singular value decomposition (SVD)
827 : . -svd_generalized - generalized singular value problem (GSVD)
828 : - -svd_hyperbolic - hyperbolic singular value problem (HSVD)
829 :
830 : Notes:
831 : The GSVD requires that two matrices have been passed via SVDSetOperators().
832 : The HSVD requires that a signature matrix has been passed via SVDSetSignature().
833 :
834 : Level: intermediate
835 :
836 : .seealso: SVDSetOperators(), SVDSetSignature(), SVDSetType(), SVDGetProblemType(), SVDProblemType
837 : @*/
838 239 : PetscErrorCode SVDSetProblemType(SVD svd,SVDProblemType type)
839 : {
840 239 : PetscFunctionBegin;
841 239 : PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
842 717 : PetscValidLogicalCollectiveEnum(svd,type,2);
843 239 : if (type == svd->problem_type) PetscFunctionReturn(PETSC_SUCCESS);
844 239 : switch (type) {
845 110 : case SVD_STANDARD:
846 110 : svd->isgeneralized = PETSC_FALSE;
847 110 : svd->ishyperbolic = PETSC_FALSE;
848 110 : break;
849 91 : case SVD_GENERALIZED:
850 91 : svd->isgeneralized = PETSC_TRUE;
851 91 : svd->ishyperbolic = PETSC_FALSE;
852 91 : break;
853 38 : case SVD_HYPERBOLIC:
854 38 : svd->isgeneralized = PETSC_FALSE;
855 38 : svd->ishyperbolic = PETSC_TRUE;
856 38 : break;
857 0 : default:
858 0 : SETERRQ(PetscObjectComm((PetscObject)svd),PETSC_ERR_ARG_WRONG,"Unknown singular value problem type");
859 : }
860 239 : svd->problem_type = type;
861 239 : svd->state = SVD_STATE_INITIAL;
862 239 : PetscFunctionReturn(PETSC_SUCCESS);
863 : }
864 :
865 : /*@
866 : SVDGetProblemType - Gets the problem type from the SVD object.
867 :
868 : Not Collective
869 :
870 : Input Parameter:
871 : . svd - the singular value solver context
872 :
873 : Output Parameter:
874 : . type - the problem type
875 :
876 : Level: intermediate
877 :
878 : .seealso: SVDSetProblemType(), SVDProblemType
879 : @*/
880 12 : PetscErrorCode SVDGetProblemType(SVD svd,SVDProblemType *type)
881 : {
882 12 : PetscFunctionBegin;
883 12 : PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
884 12 : PetscAssertPointer(type,2);
885 12 : *type = svd->problem_type;
886 12 : PetscFunctionReturn(PETSC_SUCCESS);
887 : }
888 :
889 : /*@
890 : SVDIsGeneralized - Ask if the SVD object corresponds to a generalized
891 : singular value problem.
892 :
893 : Not Collective
894 :
895 : Input Parameter:
896 : . svd - the singular value solver context
897 :
898 : Output Parameter:
899 : . is - the answer
900 :
901 : Level: intermediate
902 :
903 : .seealso: SVDIsHyperbolic()
904 : @*/
905 12 : PetscErrorCode SVDIsGeneralized(SVD svd,PetscBool* is)
906 : {
907 12 : PetscFunctionBegin;
908 12 : PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
909 12 : PetscAssertPointer(is,2);
910 12 : *is = svd->isgeneralized;
911 12 : PetscFunctionReturn(PETSC_SUCCESS);
912 : }
913 :
914 : /*@
915 : SVDIsHyperbolic - Ask if the SVD object corresponds to a hyperbolic
916 : singular value problem.
917 :
918 : Not Collective
919 :
920 : Input Parameter:
921 : . svd - the singular value solver context
922 :
923 : Output Parameter:
924 : . is - the answer
925 :
926 : Level: intermediate
927 :
928 : .seealso: SVDIsGeneralized()
929 : @*/
930 25 : PetscErrorCode SVDIsHyperbolic(SVD svd,PetscBool* is)
931 : {
932 25 : PetscFunctionBegin;
933 25 : PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
934 25 : PetscAssertPointer(is,2);
935 25 : *is = svd->ishyperbolic;
936 25 : PetscFunctionReturn(PETSC_SUCCESS);
937 : }
938 :
939 : /*@
940 : SVDSetTrackAll - Specifies if the solver must compute the residual norm of all
941 : approximate singular value or not.
942 :
943 : Logically Collective
944 :
945 : Input Parameters:
946 : + svd - the singular value solver context
947 : - trackall - whether to compute all residuals or not
948 :
949 : Notes:
950 : If the user sets trackall=PETSC_TRUE then the solver computes (or estimates)
951 : the residual norm for each singular value approximation. Computing the residual is
952 : usually an expensive operation and solvers commonly compute only the residual
953 : associated to the first unconverged singular value.
954 :
955 : The option '-svd_monitor_all' automatically activates this option.
956 :
957 : Level: developer
958 :
959 : .seealso: SVDGetTrackAll()
960 : @*/
961 2 : PetscErrorCode SVDSetTrackAll(SVD svd,PetscBool trackall)
962 : {
963 2 : PetscFunctionBegin;
964 2 : PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
965 6 : PetscValidLogicalCollectiveBool(svd,trackall,2);
966 2 : svd->trackall = trackall;
967 2 : PetscFunctionReturn(PETSC_SUCCESS);
968 : }
969 :
970 : /*@
971 : SVDGetTrackAll - Returns the flag indicating whether all residual norms must
972 : be computed or not.
973 :
974 : Not Collective
975 :
976 : Input Parameter:
977 : . svd - the singular value solver context
978 :
979 : Output Parameter:
980 : . trackall - the returned flag
981 :
982 : Level: developer
983 :
984 : .seealso: SVDSetTrackAll()
985 : @*/
986 108 : PetscErrorCode SVDGetTrackAll(SVD svd,PetscBool *trackall)
987 : {
988 108 : PetscFunctionBegin;
989 108 : PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
990 108 : PetscAssertPointer(trackall,2);
991 108 : *trackall = svd->trackall;
992 108 : PetscFunctionReturn(PETSC_SUCCESS);
993 : }
994 :
995 : /*@
996 : SVDSetOptionsPrefix - Sets the prefix used for searching for all
997 : SVD options in the database.
998 :
999 : Logically Collective
1000 :
1001 : Input Parameters:
1002 : + svd - the singular value solver context
1003 : - prefix - the prefix string to prepend to all SVD option requests
1004 :
1005 : Notes:
1006 : A hyphen (-) must NOT be given at the beginning of the prefix name.
1007 : The first character of all runtime options is AUTOMATICALLY the
1008 : hyphen.
1009 :
1010 : For example, to distinguish between the runtime options for two
1011 : different SVD contexts, one could call
1012 : .vb
1013 : SVDSetOptionsPrefix(svd1,"svd1_")
1014 : SVDSetOptionsPrefix(svd2,"svd2_")
1015 : .ve
1016 :
1017 : Level: advanced
1018 :
1019 : .seealso: SVDAppendOptionsPrefix(), SVDGetOptionsPrefix()
1020 : @*/
1021 3 : PetscErrorCode SVDSetOptionsPrefix(SVD svd,const char *prefix)
1022 : {
1023 3 : PetscFunctionBegin;
1024 3 : PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
1025 3 : if (!svd->V) PetscCall(SVDGetBV(svd,&svd->V,&svd->U));
1026 3 : PetscCall(BVSetOptionsPrefix(svd->V,prefix));
1027 3 : PetscCall(BVSetOptionsPrefix(svd->U,prefix));
1028 3 : if (!svd->ds) PetscCall(SVDGetDS(svd,&svd->ds));
1029 3 : PetscCall(DSSetOptionsPrefix(svd->ds,prefix));
1030 3 : PetscCall(PetscObjectSetOptionsPrefix((PetscObject)svd,prefix));
1031 3 : PetscFunctionReturn(PETSC_SUCCESS);
1032 : }
1033 :
1034 : /*@
1035 : SVDAppendOptionsPrefix - Appends to the prefix used for searching for all
1036 : SVD options in the database.
1037 :
1038 : Logically Collective
1039 :
1040 : Input Parameters:
1041 : + svd - the singular value solver context
1042 : - prefix - the prefix string to prepend to all SVD option requests
1043 :
1044 : Notes:
1045 : A hyphen (-) must NOT be given at the beginning of the prefix name.
1046 : The first character of all runtime options is AUTOMATICALLY the hyphen.
1047 :
1048 : Level: advanced
1049 :
1050 : .seealso: SVDSetOptionsPrefix(), SVDGetOptionsPrefix()
1051 : @*/
1052 3 : PetscErrorCode SVDAppendOptionsPrefix(SVD svd,const char *prefix)
1053 : {
1054 3 : PetscFunctionBegin;
1055 3 : PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
1056 3 : if (!svd->V) PetscCall(SVDGetBV(svd,&svd->V,&svd->U));
1057 3 : PetscCall(BVAppendOptionsPrefix(svd->V,prefix));
1058 3 : PetscCall(BVAppendOptionsPrefix(svd->U,prefix));
1059 3 : if (!svd->ds) PetscCall(SVDGetDS(svd,&svd->ds));
1060 3 : PetscCall(DSAppendOptionsPrefix(svd->ds,prefix));
1061 3 : PetscCall(PetscObjectAppendOptionsPrefix((PetscObject)svd,prefix));
1062 3 : PetscFunctionReturn(PETSC_SUCCESS);
1063 : }
1064 :
1065 : /*@
1066 : SVDGetOptionsPrefix - Gets the prefix used for searching for all
1067 : SVD options in the database.
1068 :
1069 : Not Collective
1070 :
1071 : Input Parameters:
1072 : . svd - the singular value solver context
1073 :
1074 : Output Parameters:
1075 : . prefix - pointer to the prefix string used is returned
1076 :
1077 : Note:
1078 : On the Fortran side, the user should pass in a string 'prefix' of
1079 : sufficient length to hold the prefix.
1080 :
1081 : Level: advanced
1082 :
1083 : .seealso: SVDSetOptionsPrefix(), SVDAppendOptionsPrefix()
1084 : @*/
1085 3 : PetscErrorCode SVDGetOptionsPrefix(SVD svd,const char *prefix[])
1086 : {
1087 3 : PetscFunctionBegin;
1088 3 : PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
1089 3 : PetscAssertPointer(prefix,2);
1090 3 : PetscCall(PetscObjectGetOptionsPrefix((PetscObject)svd,prefix));
1091 3 : PetscFunctionReturn(PETSC_SUCCESS);
1092 : }
|
