LCOV - code coverage report
Current view: top level - svd/interface - svdopts.c (source / functions) Hit Total Coverage
Test: SLEPc Lines: 301 322 93.5 %
Date: 2021-08-02 00:32:28 Functions: 24 24 100.0 %
Legend: Lines: hit not hit

          Line data    Source code
       1             : /*
       2             :    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
       3             :    SLEPc - Scalable Library for Eigenvalue Problem Computations
       4             :    Copyright (c) 2002-2021, 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 on svd
      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          13 : PetscErrorCode SVDSetImplicitTranspose(SVD svd,PetscBool impl)
      45             : {
      46          13 :   PetscFunctionBegin;
      47          13 :   PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
      48          26 :   PetscValidLogicalCollectiveBool(svd,impl,2);
      49          13 :   if (svd->impltrans!=impl) {
      50          13 :     svd->impltrans = impl;
      51          13 :     svd->state     = SVD_STATE_INITIAL;
      52             :   }
      53          13 :   PetscFunctionReturn(0);
      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 :   PetscValidBoolPointer(impl,2);
      77          12 :   *impl = svd->impltrans;
      78          12 :   PetscFunctionReturn(0);
      79             : }
      80             : 
      81             : /*@
      82             :    SVDSetTolerances - Sets the tolerance and maximum
      83             :    iteration count used by the default SVD convergence testers.
      84             : 
      85             :    Logically Collective on svd
      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_DEFAULT for either argument to assign a reasonably good value.
      98             : 
      99             :    Level: intermediate
     100             : 
     101             : .seealso: SVDGetTolerances()
     102             : @*/
     103          56 : PetscErrorCode SVDSetTolerances(SVD svd,PetscReal tol,PetscInt maxits)
     104             : {
     105          56 :   PetscFunctionBegin;
     106          56 :   PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
     107         112 :   PetscValidLogicalCollectiveReal(svd,tol,2);
     108         112 :   PetscValidLogicalCollectiveInt(svd,maxits,3);
     109          56 :   if (tol == PETSC_DEFAULT) {
     110          17 :     svd->tol   = PETSC_DEFAULT;
     111          17 :     svd->state = SVD_STATE_INITIAL;
     112             :   } else {
     113          39 :     if (tol <= 0.0) SETERRQ(PetscObjectComm((PetscObject)svd),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
     114          39 :     svd->tol = tol;
     115             :   }
     116          56 :   if (maxits == PETSC_DEFAULT || maxits == PETSC_DECIDE) {
     117          19 :     svd->max_it = PETSC_DEFAULT;
     118          19 :     svd->state  = SVD_STATE_INITIAL;
     119             :   } else {
     120          37 :     if (maxits <= 0) SETERRQ(PetscObjectComm((PetscObject)svd),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of maxits. Must be > 0");
     121          37 :     svd->max_it = maxits;
     122             :   }
     123          56 :   PetscFunctionReturn(0);
     124             : }
     125             : 
     126             : /*@C
     127             :    SVDGetTolerances - Gets the tolerance and maximum
     128             :    iteration count used by the default SVD convergence tests.
     129             : 
     130             :    Not Collective
     131             : 
     132             :    Input Parameter:
     133             : .  svd - the singular value solver context
     134             : 
     135             :    Output Parameters:
     136             : +  tol - the convergence tolerance
     137             : -  maxits - maximum number of iterations
     138             : 
     139             :    Notes:
     140             :    The user can specify NULL for any parameter that is not needed.
     141             : 
     142             :    Level: intermediate
     143             : 
     144             : .seealso: SVDSetTolerances()
     145             : @*/
     146          35 : PetscErrorCode SVDGetTolerances(SVD svd,PetscReal *tol,PetscInt *maxits)
     147             : {
     148          35 :   PetscFunctionBegin;
     149          35 :   PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
     150          35 :   if (tol)    *tol    = svd->tol;
     151          35 :   if (maxits) *maxits = svd->max_it;
     152          35 :   PetscFunctionReturn(0);
     153             : }
     154             : 
     155             : /*@
     156             :    SVDSetDimensions - Sets the number of singular values to compute
     157             :    and the dimension of the subspace.
     158             : 
     159             :    Logically Collective on svd
     160             : 
     161             :    Input Parameters:
     162             : +  svd - the singular value solver context
     163             : .  nsv - number of singular values to compute
     164             : .  ncv - the maximum dimension of the subspace to be used by the solver
     165             : -  mpd - the maximum dimension allowed for the projected problem
     166             : 
     167             :    Options Database Keys:
     168             : +  -svd_nsv <nsv> - Sets the number of singular values
     169             : .  -svd_ncv <ncv> - Sets the dimension of the subspace
     170             : -  -svd_mpd <mpd> - Sets the maximum projected dimension
     171             : 
     172             :    Notes:
     173             :    Use PETSC_DEFAULT for ncv and mpd to assign a reasonably good value, which is
     174             :    dependent on the solution method and the number of singular values required.
     175             : 
     176             :    The parameters ncv and mpd are intimately related, so that the user is advised
     177             :    to set one of them at most. Normal usage is that
     178             :    (a) in cases where nsv is small, the user sets ncv (a reasonable default is 2*nsv); and
     179             :    (b) in cases where nsv is large, the user sets mpd.
     180             : 
     181             :    The value of ncv should always be between nsv and (nsv+mpd), typically
     182             :    ncv=nsv+mpd. If nsv is not too large, mpd=nsv is a reasonable choice, otherwise
     183             :    a smaller value should be used.
     184             : 
     185             :    Level: intermediate
     186             : 
     187             : .seealso: SVDGetDimensions()
     188             : @*/
     189         127 : PetscErrorCode SVDSetDimensions(SVD svd,PetscInt nsv,PetscInt ncv,PetscInt mpd)
     190             : {
     191         127 :   PetscFunctionBegin;
     192         127 :   PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
     193         254 :   PetscValidLogicalCollectiveInt(svd,nsv,2);
     194         254 :   PetscValidLogicalCollectiveInt(svd,ncv,3);
     195         254 :   PetscValidLogicalCollectiveInt(svd,mpd,4);
     196         127 :   if (nsv<1) SETERRQ(PetscObjectComm((PetscObject)svd),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of nsv. Must be > 0");
     197         127 :   svd->nsv = nsv;
     198         127 :   if (ncv == PETSC_DEFAULT || ncv == PETSC_DECIDE) {
     199          85 :     svd->ncv = PETSC_DEFAULT;
     200             :   } else {
     201          42 :     if (ncv<1) SETERRQ(PetscObjectComm((PetscObject)svd),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of ncv. Must be > 0");
     202          42 :     svd->ncv = ncv;
     203             :   }
     204         127 :   if (mpd == PETSC_DECIDE || mpd == PETSC_DEFAULT) {
     205         127 :     svd->mpd = PETSC_DEFAULT;
     206             :   } else {
     207           0 :     if (mpd<1) SETERRQ(PetscObjectComm((PetscObject)svd),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of mpd. Must be > 0");
     208           0 :     svd->mpd = mpd;
     209             :   }
     210         127 :   svd->state = SVD_STATE_INITIAL;
     211         127 :   PetscFunctionReturn(0);
     212             : }
     213             : 
     214             : /*@C
     215             :    SVDGetDimensions - Gets the number of singular values to compute
     216             :    and the dimension of the subspace.
     217             : 
     218             :    Not Collective
     219             : 
     220             :    Input Parameter:
     221             : .  svd - the singular value context
     222             : 
     223             :    Output Parameters:
     224             : +  nsv - number of singular values to compute
     225             : .  ncv - the maximum dimension of the subspace to be used by the solver
     226             : -  mpd - the maximum dimension allowed for the projected problem
     227             : 
     228             :    Notes:
     229             :    The user can specify NULL for any parameter that is not needed.
     230             : 
     231             :    Level: intermediate
     232             : 
     233             : .seealso: SVDSetDimensions()
     234             : @*/
     235          41 : PetscErrorCode SVDGetDimensions(SVD svd,PetscInt *nsv,PetscInt *ncv,PetscInt *mpd)
     236             : {
     237          41 :   PetscFunctionBegin;
     238          41 :   PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
     239          41 :   if (nsv) *nsv = svd->nsv;
     240          41 :   if (ncv) *ncv = svd->ncv;
     241          41 :   if (mpd) *mpd = svd->mpd;
     242          41 :   PetscFunctionReturn(0);
     243             : }
     244             : 
     245             : /*@
     246             :     SVDSetWhichSingularTriplets - Specifies which singular triplets are
     247             :     to be sought.
     248             : 
     249             :     Logically Collective on svd
     250             : 
     251             :     Input Parameter:
     252             : .   svd - singular value solver context obtained from SVDCreate()
     253             : 
     254             :     Output Parameter:
     255             : .   which - which singular triplets are to be sought
     256             : 
     257             :     Possible values:
     258             :     The parameter 'which' can have one of these values
     259             : 
     260             : +     SVD_LARGEST  - largest singular values
     261             : -     SVD_SMALLEST - smallest singular values
     262             : 
     263             :     Options Database Keys:
     264             : +   -svd_largest  - Sets largest singular values
     265             : -   -svd_smallest - Sets smallest singular values
     266             : 
     267             :     Level: intermediate
     268             : 
     269             : .seealso: SVDGetWhichSingularTriplets(), SVDWhich
     270             : @*/
     271          37 : PetscErrorCode SVDSetWhichSingularTriplets(SVD svd,SVDWhich which)
     272             : {
     273          37 :   PetscFunctionBegin;
     274          37 :   PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
     275          74 :   PetscValidLogicalCollectiveEnum(svd,which,2);
     276          37 :   switch (which) {
     277          37 :     case SVD_LARGEST:
     278             :     case SVD_SMALLEST:
     279          37 :       if (svd->which != which) {
     280          21 :         svd->state = SVD_STATE_INITIAL;
     281          21 :         svd->which = which;
     282             :       }
     283          37 :       break;
     284           0 :   default:
     285           0 :     SETERRQ(PetscObjectComm((PetscObject)svd),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'which' parameter");
     286             :   }
     287          37 :   PetscFunctionReturn(0);
     288             : }
     289             : 
     290             : /*@
     291             :     SVDGetWhichSingularTriplets - Returns which singular triplets are
     292             :     to be sought.
     293             : 
     294             :     Not Collective
     295             : 
     296             :     Input Parameter:
     297             : .   svd - singular value solver context obtained from SVDCreate()
     298             : 
     299             :     Output Parameter:
     300             : .   which - which singular triplets are to be sought
     301             : 
     302             :     Notes:
     303             :     See SVDSetWhichSingularTriplets() for possible values of which
     304             : 
     305             :     Level: intermediate
     306             : 
     307             : .seealso: SVDSetWhichSingularTriplets(), SVDWhich
     308             : @*/
     309          12 : PetscErrorCode SVDGetWhichSingularTriplets(SVD svd,SVDWhich *which)
     310             : {
     311          12 :   PetscFunctionBegin;
     312          12 :   PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
     313          12 :   PetscValidPointer(which,2);
     314          12 :   *which = svd->which;
     315          12 :   PetscFunctionReturn(0);
     316             : }
     317             : 
     318             : /*@C
     319             :    SVDSetConvergenceTestFunction - Sets a function to compute the error estimate
     320             :    used in the convergence test.
     321             : 
     322             :    Logically Collective on svd
     323             : 
     324             :    Input Parameters:
     325             : +  svd     - singular value solver context obtained from SVDCreate()
     326             : .  func    - a pointer to the convergence test function
     327             : .  ctx     - context for private data for the convergence routine (may be null)
     328             : -  destroy - a routine for destroying the context (may be null)
     329             : 
     330             :    Calling Sequence of func:
     331             : $   func(SVD svd,PetscReal sigma,PetscReal res,PetscReal *errest,void *ctx)
     332             : 
     333             : +   svd    - singular value solver context obtained from SVDCreate()
     334             : .   sigma  - computed singular value
     335             : .   res    - residual norm associated to the singular triplet
     336             : .   errest - (output) computed error estimate
     337             : -   ctx    - optional context, as set by SVDSetConvergenceTestFunction()
     338             : 
     339             :    Note:
     340             :    If the error estimate returned by the convergence test function is less than
     341             :    the tolerance, then the singular value is accepted as converged.
     342             : 
     343             :    Level: advanced
     344             : 
     345             : .seealso: SVDSetConvergenceTest(), SVDSetTolerances()
     346             : @*/
     347           1 : PetscErrorCode SVDSetConvergenceTestFunction(SVD svd,PetscErrorCode (*func)(SVD,PetscReal,PetscReal,PetscReal*,void*),void* ctx,PetscErrorCode (*destroy)(void*))
     348             : {
     349           1 :   PetscErrorCode ierr;
     350             : 
     351           1 :   PetscFunctionBegin;
     352           1 :   PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
     353           1 :   if (svd->convergeddestroy) {
     354           0 :     ierr = (*svd->convergeddestroy)(svd->convergedctx);CHKERRQ(ierr);
     355             :   }
     356           1 :   svd->convergeduser    = func;
     357           1 :   svd->convergeddestroy = destroy;
     358           1 :   svd->convergedctx     = ctx;
     359           1 :   if (func == SVDConvergedAbsolute) svd->conv = SVD_CONV_ABS;
     360           1 :   else if (func == SVDConvergedRelative) svd->conv = SVD_CONV_REL;
     361           1 :   else if (func == SVDConvergedNorm) svd->conv = SVD_CONV_NORM;
     362           1 :   else if (func == SVDConvergedMaxIt) svd->conv = SVD_CONV_MAXIT;
     363             :   else {
     364           1 :     svd->conv      = SVD_CONV_USER;
     365           1 :     svd->converged = svd->convergeduser;
     366             :   }
     367           1 :   PetscFunctionReturn(0);
     368             : }
     369             : 
     370             : /*@
     371             :    SVDSetConvergenceTest - Specifies how to compute the error estimate
     372             :    used in the convergence test.
     373             : 
     374             :    Logically Collective on svd
     375             : 
     376             :    Input Parameters:
     377             : +  svd  - singular value solver context obtained from SVDCreate()
     378             : -  conv - the type of convergence test
     379             : 
     380             :    Options Database Keys:
     381             : +  -svd_conv_abs   - Sets the absolute convergence test
     382             : .  -svd_conv_rel   - Sets the convergence test relative to the singular value
     383             : .  -svd_conv_norm  - Sets the convergence test relative to the matrix norms
     384             : .  -svd_conv_maxit - Forces the maximum number of iterations as set by -svd_max_it
     385             : -  -svd_conv_user  - Selects the user-defined convergence test
     386             : 
     387             :    Note:
     388             :    The parameter 'conv' can have one of these values
     389             : +     SVD_CONV_ABS   - absolute error ||r||
     390             : .     SVD_CONV_REL   - error relative to the singular value l, ||r||/sigma
     391             : .     SVD_CONV_NORM  - error relative to the matrix norms, ||r||/||A||
     392             : .     SVD_CONV_MAXIT - no convergence until maximum number of iterations has been reached
     393             : -     SVD_CONV_USER  - function set by SVDSetConvergenceTestFunction()
     394             : 
     395             :    Level: intermediate
     396             : 
     397             : .seealso: SVDGetConvergenceTest(), SVDSetConvergenceTestFunction(), SVDSetStoppingTest(), SVDConv
     398             : @*/
     399          18 : PetscErrorCode SVDSetConvergenceTest(SVD svd,SVDConv conv)
     400             : {
     401          18 :   PetscFunctionBegin;
     402          18 :   PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
     403          36 :   PetscValidLogicalCollectiveEnum(svd,conv,2);
     404          18 :   switch (conv) {
     405          12 :     case SVD_CONV_ABS:   svd->converged = SVDConvergedAbsolute; break;
     406           0 :     case SVD_CONV_REL:   svd->converged = SVDConvergedRelative; break;
     407           5 :     case SVD_CONV_NORM:  svd->converged = SVDConvergedNorm; break;
     408           1 :     case SVD_CONV_MAXIT: svd->converged = SVDConvergedMaxIt; break;
     409           0 :     case SVD_CONV_USER:
     410           0 :       if (!svd->convergeduser) SETERRQ(PetscObjectComm((PetscObject)svd),PETSC_ERR_ORDER,"Must call SVDSetConvergenceTestFunction() first");
     411           0 :       svd->converged = svd->convergeduser;
     412           0 :       break;
     413           0 :     default:
     414           0 :       SETERRQ(PetscObjectComm((PetscObject)svd),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'conv' value");
     415             :   }
     416          18 :   svd->conv = conv;
     417          18 :   PetscFunctionReturn(0);
     418             : }
     419             : 
     420             : /*@
     421             :    SVDGetConvergenceTest - Gets the method used to compute the error estimate
     422             :    used in the convergence test.
     423             : 
     424             :    Not Collective
     425             : 
     426             :    Input Parameters:
     427             : .  svd   - singular value solver context obtained from SVDCreate()
     428             : 
     429             :    Output Parameters:
     430             : .  conv  - the type of convergence test
     431             : 
     432             :    Level: intermediate
     433             : 
     434             : .seealso: SVDSetConvergenceTest(), SVDConv
     435             : @*/
     436          12 : PetscErrorCode SVDGetConvergenceTest(SVD svd,SVDConv *conv)
     437             : {
     438          12 :   PetscFunctionBegin;
     439          12 :   PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
     440          12 :   PetscValidPointer(conv,2);
     441          12 :   *conv = svd->conv;
     442          12 :   PetscFunctionReturn(0);
     443             : }
     444             : 
     445             : /*@C
     446             :    SVDSetStoppingTestFunction - Sets a function to decide when to stop the outer
     447             :    iteration of the singular value solver.
     448             : 
     449             :    Logically Collective on svd
     450             : 
     451             :    Input Parameters:
     452             : +  svd     - singular value solver context obtained from SVDCreate()
     453             : .  func    - pointer to the stopping test function
     454             : .  ctx     - context for private data for the stopping routine (may be null)
     455             : -  destroy - a routine for destroying the context (may be null)
     456             : 
     457             :    Calling Sequence of func:
     458             : $   func(SVD svd,PetscInt its,PetscInt max_it,PetscInt nconv,PetscInt nsv,SVDConvergedReason *reason,void *ctx)
     459             : 
     460             : +   svd    - singular value solver context obtained from SVDCreate()
     461             : .   its    - current number of iterations
     462             : .   max_it - maximum number of iterations
     463             : .   nconv  - number of currently converged singular triplets
     464             : .   nsv    - number of requested singular triplets
     465             : .   reason - (output) result of the stopping test
     466             : -   ctx    - optional context, as set by SVDSetStoppingTestFunction()
     467             : 
     468             :    Note:
     469             :    Normal usage is to first call the default routine SVDStoppingBasic() and then
     470             :    set reason to SVD_CONVERGED_USER if some user-defined conditions have been
     471             :    met. To let the singular value solver continue iterating, the result must be
     472             :    left as SVD_CONVERGED_ITERATING.
     473             : 
     474             :    Level: advanced
     475             : 
     476             : .seealso: SVDSetStoppingTest(), SVDStoppingBasic()
     477             : @*/
     478           1 : PetscErrorCode SVDSetStoppingTestFunction(SVD svd,PetscErrorCode (*func)(SVD,PetscInt,PetscInt,PetscInt,PetscInt,SVDConvergedReason*,void*),void* ctx,PetscErrorCode (*destroy)(void*))
     479             : {
     480           1 :   PetscErrorCode ierr;
     481             : 
     482           1 :   PetscFunctionBegin;
     483           1 :   PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
     484           1 :   if (svd->stoppingdestroy) {
     485           0 :     ierr = (*svd->stoppingdestroy)(svd->stoppingctx);CHKERRQ(ierr);
     486             :   }
     487           1 :   svd->stoppinguser    = func;
     488           1 :   svd->stoppingdestroy = destroy;
     489           1 :   svd->stoppingctx     = ctx;
     490           1 :   if (func == SVDStoppingBasic) svd->stop = SVD_STOP_BASIC;
     491             :   else {
     492           1 :     svd->stop     = SVD_STOP_USER;
     493           1 :     svd->stopping = svd->stoppinguser;
     494             :   }
     495           1 :   PetscFunctionReturn(0);
     496             : }
     497             : 
     498             : /*@
     499             :    SVDSetStoppingTest - Specifies how to decide the termination of the outer
     500             :    loop of the singular value solver.
     501             : 
     502             :    Logically Collective on svd
     503             : 
     504             :    Input Parameters:
     505             : +  svd  - singular value solver context obtained from SVDCreate()
     506             : -  stop - the type of stopping test
     507             : 
     508             :    Options Database Keys:
     509             : +  -svd_stop_basic - Sets the default stopping test
     510             : -  -svd_stop_user  - Selects the user-defined stopping test
     511             : 
     512             :    Note:
     513             :    The parameter 'stop' can have one of these values
     514             : +     SVD_STOP_BASIC - default stopping test
     515             : -     SVD_STOP_USER  - function set by SVDSetStoppingTestFunction()
     516             : 
     517             :    Level: advanced
     518             : 
     519             : .seealso: SVDGetStoppingTest(), SVDSetStoppingTestFunction(), SVDSetConvergenceTest(), SVDStop
     520             : @*/
     521          12 : PetscErrorCode SVDSetStoppingTest(SVD svd,SVDStop stop)
     522             : {
     523          12 :   PetscFunctionBegin;
     524          12 :   PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
     525          24 :   PetscValidLogicalCollectiveEnum(svd,stop,2);
     526          12 :   switch (stop) {
     527          12 :     case SVD_STOP_BASIC: svd->stopping = SVDStoppingBasic; break;
     528           0 :     case SVD_STOP_USER:
     529           0 :       if (!svd->stoppinguser) SETERRQ(PetscObjectComm((PetscObject)svd),PETSC_ERR_ORDER,"Must call SVDSetStoppingTestFunction() first");
     530           0 :       svd->stopping = svd->stoppinguser;
     531           0 :       break;
     532           0 :     default:
     533           0 :       SETERRQ(PetscObjectComm((PetscObject)svd),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'stop' value");
     534             :   }
     535          12 :   svd->stop = stop;
     536          12 :   PetscFunctionReturn(0);
     537             : }
     538             : 
     539             : /*@
     540             :    SVDGetStoppingTest - Gets the method used to decide the termination of the outer
     541             :    loop of the singular value solver.
     542             : 
     543             :    Not Collective
     544             : 
     545             :    Input Parameters:
     546             : .  svd   - singular value solver context obtained from SVDCreate()
     547             : 
     548             :    Output Parameters:
     549             : .  stop  - the type of stopping test
     550             : 
     551             :    Level: advanced
     552             : 
     553             : .seealso: SVDSetStoppingTest(), SVDStop
     554             : @*/
     555          12 : PetscErrorCode SVDGetStoppingTest(SVD svd,SVDStop *stop)
     556             : {
     557          12 :   PetscFunctionBegin;
     558          12 :   PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
     559          12 :   PetscValidPointer(stop,2);
     560          12 :   *stop = svd->stop;
     561          12 :   PetscFunctionReturn(0);
     562             : }
     563             : 
     564             : /*@C
     565             :    SVDMonitorSetFromOptions - Sets a monitor function and viewer appropriate for the type
     566             :    indicated by the user.
     567             : 
     568             :    Collective on svd
     569             : 
     570             :    Input Parameters:
     571             : +  svd      - the singular value solver context
     572             : .  opt      - the command line option for this monitor
     573             : .  name     - the monitor type one is seeking
     574             : .  ctx      - an optional user context for the monitor, or NULL
     575             : -  trackall - whether this monitor tracks all singular values or not
     576             : 
     577             :    Level: developer
     578             : 
     579             : .seealso: SVDMonitorSet(), SVDSetTrackAll()
     580             : @*/
     581         405 : PetscErrorCode SVDMonitorSetFromOptions(SVD svd,const char opt[],const char name[],void *ctx,PetscBool trackall)
     582             : {
     583         405 :   PetscErrorCode       (*mfunc)(SVD,PetscInt,PetscInt,PetscReal*,PetscReal*,PetscInt,void*);
     584         405 :   PetscErrorCode       (*cfunc)(PetscViewer,PetscViewerFormat,void*,PetscViewerAndFormat**);
     585         405 :   PetscErrorCode       (*dfunc)(PetscViewerAndFormat**);
     586         405 :   PetscViewerAndFormat *vf;
     587         405 :   PetscViewer          viewer;
     588         405 :   PetscViewerFormat    format;
     589         405 :   PetscViewerType      vtype;
     590         405 :   char                 key[PETSC_MAX_PATH_LEN];
     591         405 :   PetscBool            flg;
     592         405 :   PetscErrorCode       ierr;
     593             : 
     594         405 :   PetscFunctionBegin;
     595         405 :   ierr = PetscOptionsGetViewer(PetscObjectComm((PetscObject)svd),((PetscObject)svd)->options,((PetscObject)svd)->prefix,opt,&viewer,&format,&flg);CHKERRQ(ierr);
     596         405 :   if (!flg) PetscFunctionReturn(0);
     597             : 
     598           8 :   ierr = PetscViewerGetType(viewer,&vtype);CHKERRQ(ierr);
     599           8 :   ierr = SlepcMonitorMakeKey_Internal(name,vtype,format,key);CHKERRQ(ierr);
     600           8 :   ierr = PetscFunctionListFind(SVDMonitorList,key,&mfunc);CHKERRQ(ierr);
     601           8 :   ierr = PetscFunctionListFind(SVDMonitorCreateList,key,&cfunc);CHKERRQ(ierr);
     602           8 :   ierr = PetscFunctionListFind(SVDMonitorDestroyList,key,&dfunc);CHKERRQ(ierr);
     603           8 :   if (!cfunc) cfunc = PetscViewerAndFormatCreate_Internal;
     604           8 :   if (!dfunc) dfunc = PetscViewerAndFormatDestroy;
     605             : 
     606           8 :   ierr = (*cfunc)(viewer,format,ctx,&vf);CHKERRQ(ierr);
     607           8 :   ierr = PetscObjectDereference((PetscObject)viewer);CHKERRQ(ierr);
     608           8 :   ierr = SVDMonitorSet(svd,mfunc,vf,(PetscErrorCode(*)(void **))dfunc);CHKERRQ(ierr);
     609           8 :   if (trackall) {
     610           3 :     ierr = SVDSetTrackAll(svd,PETSC_TRUE);CHKERRQ(ierr);
     611             :   }
     612           8 :   PetscFunctionReturn(0);
     613             : }
     614             : 
     615             : /*@
     616             :    SVDSetFromOptions - Sets SVD options from the options database.
     617             :    This routine must be called before SVDSetUp() if the user is to be
     618             :    allowed to set the solver type.
     619             : 
     620             :    Collective on svd
     621             : 
     622             :    Input Parameters:
     623             : .  svd - the singular value solver context
     624             : 
     625             :    Notes:
     626             :    To see all options, run your program with the -help option.
     627             : 
     628             :    Level: beginner
     629             : 
     630             : .seealso:
     631             : @*/
     632         135 : PetscErrorCode SVDSetFromOptions(SVD svd)
     633             : {
     634         135 :   PetscErrorCode ierr;
     635         135 :   char           type[256];
     636         135 :   PetscBool      set,flg,val,flg1,flg2,flg3;
     637         135 :   PetscInt       i,j,k;
     638         135 :   PetscReal      r;
     639             : 
     640         135 :   PetscFunctionBegin;
     641         135 :   PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
     642         135 :   ierr = SVDRegisterAll();CHKERRQ(ierr);
     643         405 :   ierr = PetscObjectOptionsBegin((PetscObject)svd);CHKERRQ(ierr);
     644         149 :     ierr = PetscOptionsFList("-svd_type","SVD solver method","SVDSetType",SVDList,(char*)(((PetscObject)svd)->type_name?((PetscObject)svd)->type_name:SVDCROSS),type,sizeof(type),&flg);CHKERRQ(ierr);
     645         135 :     if (flg) {
     646         117 :       ierr = SVDSetType(svd,type);CHKERRQ(ierr);
     647          18 :     } else if (!((PetscObject)svd)->type_name) {
     648           5 :       ierr = SVDSetType(svd,SVDCROSS);CHKERRQ(ierr);
     649             :     }
     650             : 
     651         135 :     ierr = PetscOptionsBoolGroupBegin("-svd_standard","Singular value decomposition (SVD)","SVDSetProblemType",&flg);CHKERRQ(ierr);
     652         135 :     if (flg) { ierr = SVDSetProblemType(svd,SVD_STANDARD);CHKERRQ(ierr); }
     653         135 :     ierr = PetscOptionsBoolGroupEnd("-svd_generalized","Generalized singular value decomposition (GSVD)","SVDSetProblemType",&flg);CHKERRQ(ierr);
     654         135 :     if (flg) { ierr = SVDSetProblemType(svd,SVD_GENERALIZED);CHKERRQ(ierr); }
     655             : 
     656         135 :     ierr = PetscOptionsBool("-svd_implicittranspose","Handle matrix transpose implicitly","SVDSetImplicitTranspose",svd->impltrans,&val,&flg);CHKERRQ(ierr);
     657         135 :     if (flg) { ierr = SVDSetImplicitTranspose(svd,val);CHKERRQ(ierr); }
     658             : 
     659         135 :     i = svd->max_it;
     660         135 :     ierr = PetscOptionsInt("-svd_max_it","Maximum number of iterations","SVDSetTolerances",svd->max_it,&i,&flg1);CHKERRQ(ierr);
     661         135 :     r = svd->tol;
     662         155 :     ierr = PetscOptionsReal("-svd_tol","Tolerance","SVDSetTolerances",SlepcDefaultTol(svd->tol),&r,&flg2);CHKERRQ(ierr);
     663         135 :     if (flg1 || flg2) { ierr = SVDSetTolerances(svd,r,i);CHKERRQ(ierr); }
     664             : 
     665         135 :     ierr = PetscOptionsBoolGroupBegin("-svd_conv_abs","Absolute error convergence test","SVDSetConvergenceTest",&flg);CHKERRQ(ierr);
     666         135 :     if (flg) { ierr = SVDSetConvergenceTest(svd,SVD_CONV_ABS);CHKERRQ(ierr); }
     667         135 :     ierr = PetscOptionsBoolGroup("-svd_conv_rel","Relative error convergence test","SVDSetConvergenceTest",&flg);CHKERRQ(ierr);
     668         135 :     if (flg) { ierr = SVDSetConvergenceTest(svd,SVD_CONV_REL);CHKERRQ(ierr); }
     669         135 :     ierr = PetscOptionsBoolGroup("-svd_conv_norm","Convergence test relative to the matrix norms","SVDSetConvergenceTest",&flg);CHKERRQ(ierr);
     670         135 :     if (flg) { ierr = SVDSetConvergenceTest(svd,SVD_CONV_NORM);CHKERRQ(ierr); }
     671         135 :     ierr = PetscOptionsBoolGroup("-svd_conv_maxit","Maximum iterations convergence test","SVDSetConvergenceTest",&flg);CHKERRQ(ierr);
     672         135 :     if (flg) { ierr = SVDSetConvergenceTest(svd,SVD_CONV_MAXIT);CHKERRQ(ierr); }
     673         135 :     ierr = PetscOptionsBoolGroupEnd("-svd_conv_user","User-defined convergence test","SVDSetConvergenceTest",&flg);CHKERRQ(ierr);
     674         135 :     if (flg) { ierr = SVDSetConvergenceTest(svd,SVD_CONV_USER);CHKERRQ(ierr); }
     675             : 
     676         135 :     ierr = PetscOptionsBoolGroupBegin("-svd_stop_basic","Stop iteration if all singular values converged or max_it reached","SVDSetStoppingTest",&flg);CHKERRQ(ierr);
     677         135 :     if (flg) { ierr = SVDSetStoppingTest(svd,SVD_STOP_BASIC);CHKERRQ(ierr); }
     678         135 :     ierr = PetscOptionsBoolGroupEnd("-svd_stop_user","User-defined stopping test","SVDSetStoppingTest",&flg);CHKERRQ(ierr);
     679         135 :     if (flg) { ierr = SVDSetStoppingTest(svd,SVD_STOP_USER);CHKERRQ(ierr); }
     680             : 
     681         135 :     i = svd->nsv;
     682         135 :     ierr = PetscOptionsInt("-svd_nsv","Number of singular values to compute","SVDSetDimensions",svd->nsv,&i,&flg1);CHKERRQ(ierr);
     683         135 :     j = svd->ncv;
     684         135 :     ierr = PetscOptionsInt("-svd_ncv","Number of basis vectors","SVDSetDimensions",svd->ncv,&j,&flg2);CHKERRQ(ierr);
     685         135 :     k = svd->mpd;
     686         135 :     ierr = PetscOptionsInt("-svd_mpd","Maximum dimension of projected problem","SVDSetDimensions",svd->mpd,&k,&flg3);CHKERRQ(ierr);
     687         135 :     if (flg1 || flg2 || flg3) { ierr = SVDSetDimensions(svd,i,j,k);CHKERRQ(ierr); }
     688             : 
     689         135 :     ierr = PetscOptionsBoolGroupBegin("-svd_largest","Compute largest singular values","SVDSetWhichSingularTriplets",&flg);CHKERRQ(ierr);
     690         135 :     if (flg) { ierr = SVDSetWhichSingularTriplets(svd,SVD_LARGEST);CHKERRQ(ierr); }
     691         135 :     ierr = PetscOptionsBoolGroupEnd("-svd_smallest","Compute smallest singular values","SVDSetWhichSingularTriplets",&flg);CHKERRQ(ierr);
     692         135 :     if (flg) { ierr = SVDSetWhichSingularTriplets(svd,SVD_SMALLEST);CHKERRQ(ierr); }
     693             : 
     694             :     /* -----------------------------------------------------------------------*/
     695             :     /*
     696             :       Cancels all monitors hardwired into code before call to SVDSetFromOptions()
     697             :     */
     698         135 :     ierr = PetscOptionsBool("-svd_monitor_cancel","Remove any hardwired monitor routines","SVDMonitorCancel",PETSC_FALSE,&flg,&set);CHKERRQ(ierr);
     699         135 :     if (set && flg) { ierr = SVDMonitorCancel(svd);CHKERRQ(ierr); }
     700         135 :     ierr = SVDMonitorSetFromOptions(svd,"-svd_monitor","first_approximation",NULL,PETSC_FALSE);CHKERRQ(ierr);
     701         135 :     ierr = SVDMonitorSetFromOptions(svd,"-svd_monitor_all","all_approximations",NULL,PETSC_TRUE);CHKERRQ(ierr);
     702         135 :     ierr = SVDMonitorSetFromOptions(svd,"-svd_monitor_conv","convergence_history",NULL,PETSC_FALSE);CHKERRQ(ierr);
     703             : 
     704             :     /* -----------------------------------------------------------------------*/
     705         135 :     ierr = PetscOptionsName("-svd_view","Print detailed information on solver used","SVDView",NULL);CHKERRQ(ierr);
     706         135 :     ierr = PetscOptionsName("-svd_view_vectors","View computed singular vectors","SVDVectorsView",NULL);CHKERRQ(ierr);
     707         135 :     ierr = PetscOptionsName("-svd_view_values","View computed singular values","SVDValuesView",NULL);CHKERRQ(ierr);
     708         135 :     ierr = PetscOptionsName("-svd_converged_reason","Print reason for convergence, and number of iterations","SVDConvergedReasonView",NULL);CHKERRQ(ierr);
     709         135 :     ierr = PetscOptionsName("-svd_error_absolute","Print absolute errors of each singular triplet","SVDErrorView",NULL);CHKERRQ(ierr);
     710         135 :     ierr = PetscOptionsName("-svd_error_relative","Print relative errors of each singular triplet","SVDErrorView",NULL);CHKERRQ(ierr);
     711             : 
     712         135 :     if (svd->ops->setfromoptions) {
     713         112 :       ierr = (*svd->ops->setfromoptions)(PetscOptionsObject,svd);CHKERRQ(ierr);
     714             :     }
     715         135 :     ierr = PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)svd);CHKERRQ(ierr);
     716         270 :   ierr = PetscOptionsEnd();CHKERRQ(ierr);
     717             : 
     718         135 :   if (!svd->V) { ierr = SVDGetBV(svd,&svd->V,NULL);CHKERRQ(ierr); }
     719         135 :   ierr = BVSetFromOptions(svd->V);CHKERRQ(ierr);
     720         135 :   if (!svd->U) { ierr = SVDGetBV(svd,NULL,&svd->U);CHKERRQ(ierr); }
     721         135 :   ierr = BVSetFromOptions(svd->U);CHKERRQ(ierr);
     722         135 :   if (!svd->ds) { ierr = SVDGetDS(svd,&svd->ds);CHKERRQ(ierr); }
     723         135 :   ierr = DSSetFromOptions(svd->ds);CHKERRQ(ierr);
     724         135 :   PetscFunctionReturn(0);
     725             : }
     726             : 
     727             : /*@
     728             :    SVDSetProblemType - Specifies the type of the singular value problem.
     729             : 
     730             :    Logically Collective on svd
     731             : 
     732             :    Input Parameters:
     733             : +  svd  - the singular value solver context
     734             : -  type - a known type of singular value problem
     735             : 
     736             :    Options Database Keys:
     737             : +  -svd_standard    - standard singular value decomposition (SVD)
     738             : -  -svd_generalized - generalized singular value problem (GSVD)
     739             : 
     740             :    Notes:
     741             :    The GSVD requires that two matrices have been passed via SVDSetOperators().
     742             : 
     743             :    Level: intermediate
     744             : 
     745             : .seealso: SVDSetOperators(), SVDSetType(), SVDGetProblemType(), SVDProblemType
     746             : @*/
     747         143 : PetscErrorCode SVDSetProblemType(SVD svd,SVDProblemType type)
     748             : {
     749         143 :   PetscFunctionBegin;
     750         143 :   PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
     751         286 :   PetscValidLogicalCollectiveEnum(svd,type,2);
     752         143 :   if (type == svd->problem_type) PetscFunctionReturn(0);
     753         143 :   switch (type) {
     754         104 :     case SVD_STANDARD:
     755         104 :       svd->isgeneralized = PETSC_FALSE;
     756         104 :       break;
     757          39 :     case SVD_GENERALIZED:
     758          39 :       svd->isgeneralized = PETSC_TRUE;
     759          39 :       break;
     760           0 :     default:
     761           0 :       SETERRQ(PetscObjectComm((PetscObject)svd),PETSC_ERR_ARG_WRONG,"Unknown singular value problem type");
     762             :   }
     763         143 :   svd->problem_type = type;
     764         143 :   svd->state = SVD_STATE_INITIAL;
     765         143 :   PetscFunctionReturn(0);
     766             : }
     767             : 
     768             : /*@
     769             :    SVDGetProblemType - Gets the problem type from the SVD object.
     770             : 
     771             :    Not Collective
     772             : 
     773             :    Input Parameter:
     774             : .  svd - the singular value solver context
     775             : 
     776             :    Output Parameter:
     777             : .  type - the problem type
     778             : 
     779             :    Level: intermediate
     780             : 
     781             : .seealso: SVDSetProblemType(), SVDProblemType
     782             : @*/
     783          12 : PetscErrorCode SVDGetProblemType(SVD svd,SVDProblemType *type)
     784             : {
     785          12 :   PetscFunctionBegin;
     786          12 :   PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
     787          12 :   PetscValidPointer(type,2);
     788          12 :   *type = svd->problem_type;
     789          12 :   PetscFunctionReturn(0);
     790             : }
     791             : 
     792             : /*@
     793             :    SVDIsGeneralized - Ask if the SVD object corresponds to a generalized
     794             :    singular value problem.
     795             : 
     796             :    Not collective
     797             : 
     798             :    Input Parameter:
     799             : .  svd - the singular value solver context
     800             : 
     801             :    Output Parameter:
     802             : .  is - the answer
     803             : 
     804             :    Level: intermediate
     805             : 
     806             : .seealso: SVDIsHermitian(), SVDIsPositive()
     807             : @*/
     808          12 : PetscErrorCode SVDIsGeneralized(SVD svd,PetscBool* is)
     809             : {
     810          12 :   PetscFunctionBegin;
     811          12 :   PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
     812          12 :   PetscValidBoolPointer(is,2);
     813          12 :   *is = svd->isgeneralized;
     814          12 :   PetscFunctionReturn(0);
     815             : }
     816             : 
     817             : /*@
     818             :    SVDSetTrackAll - Specifies if the solver must compute the residual norm of all
     819             :    approximate singular value or not.
     820             : 
     821             :    Logically Collective on svd
     822             : 
     823             :    Input Parameters:
     824             : +  svd      - the singular value solver context
     825             : -  trackall - whether to compute all residuals or not
     826             : 
     827             :    Notes:
     828             :    If the user sets trackall=PETSC_TRUE then the solver computes (or estimates)
     829             :    the residual norm for each singular value approximation. Computing the residual is
     830             :    usually an expensive operation and solvers commonly compute only the residual
     831             :    associated to the first unconverged singular value.
     832             : 
     833             :    The option '-svd_monitor_all' automatically activates this option.
     834             : 
     835             :    Level: developer
     836             : 
     837             : .seealso: SVDGetTrackAll()
     838             : @*/
     839           3 : PetscErrorCode SVDSetTrackAll(SVD svd,PetscBool trackall)
     840             : {
     841           3 :   PetscFunctionBegin;
     842           3 :   PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
     843           6 :   PetscValidLogicalCollectiveBool(svd,trackall,2);
     844           3 :   svd->trackall = trackall;
     845           3 :   PetscFunctionReturn(0);
     846             : }
     847             : 
     848             : /*@
     849             :    SVDGetTrackAll - Returns the flag indicating whether all residual norms must
     850             :    be computed or not.
     851             : 
     852             :    Not Collective
     853             : 
     854             :    Input Parameter:
     855             : .  svd - the singular value solver context
     856             : 
     857             :    Output Parameter:
     858             : .  trackall - the returned flag
     859             : 
     860             :    Level: developer
     861             : 
     862             : .seealso: SVDSetTrackAll()
     863             : @*/
     864          79 : PetscErrorCode SVDGetTrackAll(SVD svd,PetscBool *trackall)
     865             : {
     866          79 :   PetscFunctionBegin;
     867          79 :   PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
     868          79 :   PetscValidBoolPointer(trackall,2);
     869          79 :   *trackall = svd->trackall;
     870          79 :   PetscFunctionReturn(0);
     871             : }
     872             : 
     873             : /*@C
     874             :    SVDSetOptionsPrefix - Sets the prefix used for searching for all
     875             :    SVD options in the database.
     876             : 
     877             :    Logically Collective on svd
     878             : 
     879             :    Input Parameters:
     880             : +  svd - the singular value solver context
     881             : -  prefix - the prefix string to prepend to all SVD option requests
     882             : 
     883             :    Notes:
     884             :    A hyphen (-) must NOT be given at the beginning of the prefix name.
     885             :    The first character of all runtime options is AUTOMATICALLY the
     886             :    hyphen.
     887             : 
     888             :    For example, to distinguish between the runtime options for two
     889             :    different SVD contexts, one could call
     890             : .vb
     891             :       SVDSetOptionsPrefix(svd1,"svd1_")
     892             :       SVDSetOptionsPrefix(svd2,"svd2_")
     893             : .ve
     894             : 
     895             :    Level: advanced
     896             : 
     897             : .seealso: SVDAppendOptionsPrefix(), SVDGetOptionsPrefix()
     898             : @*/
     899           3 : PetscErrorCode SVDSetOptionsPrefix(SVD svd,const char *prefix)
     900             : {
     901           3 :   PetscErrorCode ierr;
     902             : 
     903           3 :   PetscFunctionBegin;
     904           3 :   PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
     905           3 :   if (!svd->V) { ierr = SVDGetBV(svd,&svd->V,&svd->U);CHKERRQ(ierr); }
     906           3 :   ierr = BVSetOptionsPrefix(svd->V,prefix);CHKERRQ(ierr);
     907           3 :   ierr = BVSetOptionsPrefix(svd->U,prefix);CHKERRQ(ierr);
     908           3 :   if (!svd->ds) { ierr = SVDGetDS(svd,&svd->ds);CHKERRQ(ierr); }
     909           3 :   ierr = DSSetOptionsPrefix(svd->ds,prefix);CHKERRQ(ierr);
     910           3 :   ierr = PetscObjectSetOptionsPrefix((PetscObject)svd,prefix);CHKERRQ(ierr);
     911           3 :   PetscFunctionReturn(0);
     912             : }
     913             : 
     914             : /*@C
     915             :    SVDAppendOptionsPrefix - Appends to the prefix used for searching for all
     916             :    SVD options in the database.
     917             : 
     918             :    Logically Collective on svd
     919             : 
     920             :    Input Parameters:
     921             : +  svd - the singular value solver context
     922             : -  prefix - the prefix string to prepend to all SVD option requests
     923             : 
     924             :    Notes:
     925             :    A hyphen (-) must NOT be given at the beginning of the prefix name.
     926             :    The first character of all runtime options is AUTOMATICALLY the hyphen.
     927             : 
     928             :    Level: advanced
     929             : 
     930             : .seealso: SVDSetOptionsPrefix(), SVDGetOptionsPrefix()
     931             : @*/
     932           3 : PetscErrorCode SVDAppendOptionsPrefix(SVD svd,const char *prefix)
     933             : {
     934           3 :   PetscErrorCode ierr;
     935             : 
     936           3 :   PetscFunctionBegin;
     937           3 :   PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
     938           3 :   if (!svd->V) { ierr = SVDGetBV(svd,&svd->V,&svd->U);CHKERRQ(ierr); }
     939           3 :   ierr = BVAppendOptionsPrefix(svd->V,prefix);CHKERRQ(ierr);
     940           3 :   ierr = BVAppendOptionsPrefix(svd->U,prefix);CHKERRQ(ierr);
     941           3 :   if (!svd->ds) { ierr = SVDGetDS(svd,&svd->ds);CHKERRQ(ierr); }
     942           3 :   ierr = DSAppendOptionsPrefix(svd->ds,prefix);CHKERRQ(ierr);
     943           3 :   ierr = PetscObjectAppendOptionsPrefix((PetscObject)svd,prefix);CHKERRQ(ierr);
     944           3 :   PetscFunctionReturn(0);
     945             : }
     946             : 
     947             : /*@C
     948             :    SVDGetOptionsPrefix - Gets the prefix used for searching for all
     949             :    SVD options in the database.
     950             : 
     951             :    Not Collective
     952             : 
     953             :    Input Parameters:
     954             : .  svd - the singular value solver context
     955             : 
     956             :    Output Parameters:
     957             : .  prefix - pointer to the prefix string used is returned
     958             : 
     959             :    Note:
     960             :    On the Fortran side, the user should pass in a string 'prefix' of
     961             :    sufficient length to hold the prefix.
     962             : 
     963             :    Level: advanced
     964             : 
     965             : .seealso: SVDSetOptionsPrefix(), SVDAppendOptionsPrefix()
     966             : @*/
     967           3 : PetscErrorCode SVDGetOptionsPrefix(SVD svd,const char *prefix[])
     968             : {
     969           3 :   PetscErrorCode ierr;
     970             : 
     971           3 :   PetscFunctionBegin;
     972           3 :   PetscValidHeaderSpecific(svd,SVD_CLASSID,1);
     973           3 :   PetscValidPointer(prefix,2);
     974           3 :   ierr = PetscObjectGetOptionsPrefix((PetscObject)svd,prefix);CHKERRQ(ierr);
     975           3 :   PetscFunctionReturn(0);
     976             : }
     977             : 

Generated by: LCOV version 1.14