Actual source code: itcreate.c

  2: /*
  3:      The basic KSP routines, Create, View etc. are here.
  4: */
  5: #include <private/kspimpl.h>      /*I "petscksp.h" I*/

  7: /* Logging support */
  8: PetscClassId  KSP_CLASSID;
  9: PetscLogEvent  KSP_GMRESOrthogonalization, KSP_SetUp, KSP_Solve;

 11: /*
 12:    Contains the list of registered KSP routines
 13: */
 14: PetscFList KSPList = 0;
 15: PetscBool  KSPRegisterAllCalled = PETSC_FALSE;

 19: /*@C 
 20:    KSPView - Prints the KSP data structure.

 22:    Collective on KSP

 24:    Input Parameters:
 25: +  ksp - the Krylov space context
 26: -  viewer - visualization context

 28:    Options Database Keys:
 29: .  -ksp_view - print the ksp data structure at the end of a KSPSolve call

 31:    Note:
 32:    The available visualization contexts include
 33: +     PETSC_VIEWER_STDOUT_SELF - standard output (default)
 34: -     PETSC_VIEWER_STDOUT_WORLD - synchronized standard
 35:          output where only the first processor opens
 36:          the file.  All other processors send their 
 37:          data to the first processor to print. 

 39:    The user can open an alternative visualization context with
 40:    PetscViewerASCIIOpen() - output to a specified file.

 42:    Level: beginner

 44: .keywords: KSP, view

 46: .seealso: PCView(), PetscViewerASCIIOpen()
 47: @*/
 48: PetscErrorCode  KSPView(KSP ksp,PetscViewer viewer)
 49: {
 51:   PetscBool      iascii;

 55:   if (!viewer) viewer = PETSC_VIEWER_STDOUT_(((PetscObject)ksp)->comm);

 59:   PetscTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&iascii);
 60:   if (iascii) {
 61:     PetscObjectPrintClassNamePrefixType((PetscObject)ksp,viewer,"KSP Object");
 62:     if (ksp->ops->view) {
 63:       PetscViewerASCIIPushTab(viewer);
 64:       (*ksp->ops->view)(ksp,viewer);
 65:       PetscViewerASCIIPopTab(viewer);
 66:     }
 67:     if (ksp->guess_zero) {PetscViewerASCIIPrintf(viewer,"  maximum iterations=%D, initial guess is zero\n",ksp->max_it);}
 68:     else                 {PetscViewerASCIIPrintf(viewer,"  maximum iterations=%D\n", ksp->max_it);}
 69:     if (ksp->guess_knoll) {PetscViewerASCIIPrintf(viewer,"  using preconditioner applied to right hand side for initial guess\n");}
 70:     PetscViewerASCIIPrintf(viewer,"  tolerances:  relative=%G, absolute=%G, divergence=%G\n",ksp->rtol,ksp->abstol,ksp->divtol);
 71:     if (ksp->pc_side == PC_RIGHT)          {PetscViewerASCIIPrintf(viewer,"  right preconditioning\n");}
 72:     else if (ksp->pc_side == PC_SYMMETRIC) {PetscViewerASCIIPrintf(viewer,"  symmetric preconditioning\n");}
 73:     else                                   {PetscViewerASCIIPrintf(viewer,"  left preconditioning\n");}
 74:     if (ksp->guess) {PetscViewerASCIIPrintf(viewer,"  using Fischers initial guess method %D with size %D\n",ksp->guess->method,ksp->guess->maxl);}
 75:     if (ksp->dscale) {PetscViewerASCIIPrintf(viewer,"  diagonally scaled system\n");}
 76:     if (ksp->nullsp) {PetscViewerASCIIPrintf(viewer,"  has attached null space\n");}
 77:     if (!ksp->guess_zero) {PetscViewerASCIIPrintf(viewer,"  using nonzero initial guess\n");}
 78:     PetscViewerASCIIPrintf(viewer,"  using %s norm type for convergence test\n",KSPNormTypes[ksp->normtype]);
 79:   } else {
 80:     if (ksp->ops->view) {
 81:       (*ksp->ops->view)(ksp,viewer);
 82:     }
 83:   }
 84:   if (!ksp->pc) {KSPGetPC(ksp,&ksp->pc);}
 85:   PCView(ksp->pc,viewer);
 86:   return(0);
 87: }


 92: /*@
 93:    KSPSetNormType - Sets the norm that is used for convergence testing.

 95:    Logically Collective on KSP

 97:    Input Parameter:
 98: +  ksp - Krylov solver context
 99: -  normtype - one of 
100: $   KSP_NORM_NONE - skips computing the norm, this should only be used if you are using
101: $                 the Krylov method as a smoother with a fixed small number of iterations.
102: $                 Implicitly sets KSPSkipConverged as KSP convergence test.
103: $                 Supported only by CG, Richardson, Bi-CG-stab, CR, and CGS methods.
104: $   KSP_NORM_PRECONDITIONED - the default for left preconditioned solves, uses the l2 norm
105: $                 of the preconditioned residual
106: $   KSP_NORM_UNPRECONDITIONED - uses the l2 norm of the true b - Ax residual, supported only by
107: $                 CG, CHEBYCHEV, and RICHARDSON, automatically true for right (see KSPSetPCSide()) 
108: $                 preconditioning..
109: $   KSP_NORM_NATURAL - supported  by KSPCG, KSPCR, KSPCGNE, KSPCGS


112:    Options Database Key:
113: .   -ksp_norm_type <none,preconditioned,unpreconditioned,natural>

115:    Notes: 
116:    Currently only works with the CG, Richardson, Bi-CG-stab, CR, and CGS methods.

118:    Level: advanced

120: .keywords: KSP, create, context, norms

122: .seealso: KSPSetUp(), KSPSolve(), KSPDestroy(), KSPSkipConverged()                               
123: @*/
124: PetscErrorCode  KSPSetNormType(KSP ksp,KSPNormType normtype)
125: {

131:   ksp->normtype = normtype;
132:   if (normtype == KSP_NORM_NONE) {
133:     KSPSetConvergenceTest(ksp,KSPSkipConverged,0,0);
134:     PetscInfo(ksp,"Warning: setting KSPNormType to skip computing the norm\n\
135:  KSP convergence test is implicitly set to KSPSkipConverged\n");
136:   }
137:   return(0);
138: }

142: /*@
143:    KSPSetCheckNormIteration - Sets the first iteration at which the norm of the residual will be 
144:      computed and used in the convergence test. 

146:    Logically Collective on KSP

148:    Input Parameter:
149: +  ksp - Krylov solver context
150: -  it  - use -1 to check at all iterations

152:    Notes: 
153:    Currently only works with KSPCG, KSPBCGS and KSPIBCGS

155:    Use KSPSetNormType(ksp,KSP_NORM_NONE) to never check the norm

157:    On steps where the norm is not computed, the previous norm is still in the variable, so if you run with, for example,
158:     -ksp_monitor the residual norm will appear to be unchanged for several iterations (though it is not really unchanged).
159:    Level: advanced

161: .keywords: KSP, create, context, norms

163: .seealso: KSPSetUp(), KSPSolve(), KSPDestroy(), KSPSkipConverged(), KSPSetNormType()                               
164: @*/
165: PetscErrorCode  KSPSetCheckNormIteration(KSP ksp,PetscInt it)
166: {
170:   ksp->chknorm = it;
171:   return(0);
172: }

176: /*@
177:    KSPSetLagNorm - Lags the residual norm calculation so that it is computed as part of the MPI_Allreduce() for 
178:    computing the inner products for the next iteration.  This can reduce communication costs at the expense of doing 
179:    one additional iteration.


182:    Logically Collective on KSP

184:    Input Parameter:
185: +  ksp - Krylov solver context
186: -  flg - PETSC_TRUE or PETSC_FALSE

188:    Options Database Keys:
189: .  -ksp_lag_norm - lag the calculated residual norm

191:    Notes: 
192:    Currently only works with KSPIBCGS.

194:    Use KSPSetNormType(ksp,KSP_NORM_NONE) to never check the norm

196:    If you lag the norm and run with, for example, -ksp_monitor, the residual norm reported will be the lagged one.
197:    Level: advanced

199: .keywords: KSP, create, context, norms

201: .seealso: KSPSetUp(), KSPSolve(), KSPDestroy(), KSPSkipConverged(), KSPSetNormType()                               
202: @*/
203: PetscErrorCode  KSPSetLagNorm(KSP ksp,PetscBool  flg)
204: {
208:   ksp->lagnorm = flg;
209:   return(0);
210: }

214: /*@
215:    KSPSetSupportedNorm - Sets a norm and preconditioner side supported by a KSP

217:    Logically Collective

219:    Input Arguments:
220: +  ksp - Krylov method
221: .  normtype - supported norm type
222: .  pcside - preconditioner side that can be used with this norm
223: -  preference - integer preference for this combination, larger values have higher priority

225:    Level: developer

227:    Notes:
228:    This function should be called from the implementation files KSPCreate_XXX() to declare
229:    which norms and preconditioner sides are supported. Users should not need to call this
230:    function.

232:    KSP_NORM_NONE is supported by default with all KSP methods and any PC side. If a KSP explicitly does not support
233:    KSP_NORM_NONE, it should set this by setting priority=0.

235: .seealso: KSPSetNormType(), KSPSetPCSide()
236: @*/
237: PetscErrorCode KSPSetSupportedNorm(KSP ksp,KSPNormType normtype,PCSide pcside,PetscInt priority)
238: {

242:   ksp->normsupporttable[normtype][pcside] = priority;
243:   return(0);
244: }

248: PetscErrorCode KSPNormSupportTableReset_Private(KSP ksp)
249: {

253:   PetscMemzero(ksp->normsupporttable,sizeof ksp->normsupporttable);
254:   KSPSetSupportedNorm(ksp,KSP_NORM_NONE,PC_LEFT,1);
255:   KSPSetSupportedNorm(ksp,KSP_NORM_NONE,PC_RIGHT,1);
256:   return(0);
257: }

261: PetscErrorCode KSPSetUpNorms_Private(KSP ksp)
262: {
263:   PetscInt i,j,best,ibest = 0,jbest = 0;

266:   best = 0;
267:   for (i=0; i<KSP_NORM_MAX; i++) {
268:     for (j=0; j<PC_SIDE_MAX; j++) {
269:       if ((ksp->normtype == KSP_NORM_DEFAULT || ksp->normtype == i)
270:           && (ksp->pc_side == PC_SIDE_DEFAULT || ksp->pc_side == j)
271:           && (ksp->normsupporttable[i][j] > best)) {
272:         if (ksp->normtype == KSP_NORM_DEFAULT && i == KSP_NORM_NONE && ksp->normsupporttable[i][j] <= 1)
273:           continue; /* Skip because we don't want to default to no norms unless set by the KSP (preonly). */
274:         best = ksp->normsupporttable[i][j];
275:         ibest = i;
276:         jbest = j;
277:       }
278:     }
279:   }
280:   if (best < 1) {
281:     if (ksp->normtype == KSP_NORM_DEFAULT && ksp->pc_side == PC_SIDE_DEFAULT) SETERRQ1(((PetscObject)ksp)->comm,PETSC_ERR_PLIB,"The %s KSP implementation did not call KSPSetSupportedNorm()",((PetscObject)ksp)->type_name);
282:     if (ksp->normtype == KSP_NORM_DEFAULT) SETERRQ2(((PetscObject)ksp)->comm,PETSC_ERR_SUP,"KSP %s does not support %s",((PetscObject)ksp)->type_name,PCSides[ksp->pc_side]);
283:     if (ksp->pc_side == PC_SIDE_DEFAULT) SETERRQ2(((PetscObject)ksp)->comm,PETSC_ERR_SUP,"KSP %s does not support %s",((PetscObject)ksp)->type_name,KSPNormTypes[ksp->normtype]);
284:     SETERRQ3(((PetscObject)ksp)->comm,PETSC_ERR_SUP,"KSP %s does not support %s with %s",((PetscObject)ksp)->type_name,KSPNormTypes[ksp->normtype],PCSides[ksp->pc_side]);
285:   }
286:   ksp->normtype = (KSPNormType)ibest;
287:   ksp->pc_side = (PCSide)jbest;
288:   return(0);
289: }

293: /*@
294:    KSPGetNormType - Gets the norm that is used for convergence testing.

296:    Not Collective

298:    Input Parameter:
299: .  ksp - Krylov solver context

301:    Output Parameter:
302: .  normtype - norm that is used for convergence testing

304:    Level: advanced

306: .keywords: KSP, create, context, norms

308: .seealso: KSPNormType, KSPSetNormType(), KSPSkipConverged()
309: @*/
310: PetscErrorCode  KSPGetNormType(KSP ksp, KSPNormType *normtype)
311: {

317:   KSPSetUpNorms_Private(ksp);
318:   *normtype = ksp->normtype;
319:   return(0);
320: }

322: #if defined(PETSC_HAVE_AMS)
325: static PetscErrorCode KSPPublish_Petsc(PetscObject obj)
326: {
327:   KSP            ksp = (KSP) obj;

331:   AMS_Memory_add_field(obj->amem,"its",&ksp->its,1,AMS_INT,AMS_READ,AMS_COMMON,AMS_REDUCT_UNDEF);
332:   return(0);
333: }
334: #endif

338: /*@
339:    KSPSetOperators - Sets the matrix associated with the linear system
340:    and a (possibly) different one associated with the preconditioner. 

342:    Collective on KSP and Mat

344:    Input Parameters:
345: +  ksp - the KSP context
346: .  Amat - the matrix associated with the linear system
347: .  Pmat - the matrix to be used in constructing the preconditioner, usually the
348:           same as Amat. 
349: -  flag - flag indicating information about the preconditioner matrix structure
350:    during successive linear solves.  This flag is ignored the first time a
351:    linear system is solved, and thus is irrelevant when solving just one linear
352:    system.

354:    Notes: 
355:    The flag can be used to eliminate unnecessary work in the preconditioner 
356:    during the repeated solution of linear systems of the same size.  The
357:    available options are
358: $    SAME_PRECONDITIONER -
359: $      Pmat is identical during successive linear solves.
360: $      This option is intended for folks who are using
361: $      different Amat and Pmat matrices and want to reuse the
362: $      same preconditioner matrix.  For example, this option
363: $      saves work by not recomputing incomplete factorization
364: $      for ILU/ICC preconditioners.
365: $    SAME_NONZERO_PATTERN -
366: $      Pmat has the same nonzero structure during
367: $      successive linear solves. 
368: $    DIFFERENT_NONZERO_PATTERN -
369: $      Pmat does not have the same nonzero structure.

371:     All future calls to KSPSetOperators() must use the same size matrices!

373:     Passing a PETSC_NULL for Amat or Pmat removes the matrix that is currently used.

375:     If you wish to replace either Amat or Pmat but leave the other one untouched then
376:     first call KSPGetOperators() to get the one you wish to keep, call PetscObjectReference()
377:     on it and then pass it back in in your call to KSPSetOperators().

379:     Caution:
380:     If you specify SAME_NONZERO_PATTERN, PETSc believes your assertion
381:     and does not check the structure of the matrix.  If you erroneously
382:     claim that the structure is the same when it actually is not, the new
383:     preconditioner will not function correctly.  Thus, use this optimization
384:     feature carefully!

386:     If in doubt about whether your preconditioner matrix has changed
387:     structure or not, use the flag DIFFERENT_NONZERO_PATTERN.

389:     Level: beginner

391:    Alternative usage: If the operators have NOT been set with KSP/PCSetOperators() then the operators
392:       are created in PC and returned to the user. In this case, if both operators
393:       mat and pmat are requested, two DIFFERENT operators will be returned. If
394:       only one is requested both operators in the PC will be the same (i.e. as
395:       if one had called KSP/PCSetOperators() with the same argument for both Mats).
396:       The user must set the sizes of the returned matrices and their type etc just
397:       as if the user created them with MatCreate(). For example,

399: $         KSP/PCGetOperators(ksp/pc,&mat,PETSC_NULL,PETSC_NULL); is equivalent to
400: $           set size, type, etc of mat

402: $         MatCreate(comm,&mat);
403: $         KSP/PCSetOperators(ksp/pc,mat,mat,SAME_NONZERO_PATTERN);
404: $         PetscObjectDereference((PetscObject)mat);
405: $           set size, type, etc of mat

407:      and

409: $         KSP/PCGetOperators(ksp/pc,&mat,&pmat,PETSC_NULL); is equivalent to
410: $           set size, type, etc of mat and pmat

412: $         MatCreate(comm,&mat);
413: $         MatCreate(comm,&pmat);
414: $         KSP/PCSetOperators(ksp/pc,mat,pmat,SAME_NONZERO_PATTERN);
415: $         PetscObjectDereference((PetscObject)mat);
416: $         PetscObjectDereference((PetscObject)pmat);
417: $           set size, type, etc of mat and pmat

419:     The rational for this support is so that when creating a TS, SNES, or KSP the hierarchy
420:     of underlying objects (i.e. SNES, KSP, PC, Mat) and their livespans can be completely 
421:     managed by the top most level object (i.e. the TS, SNES, or KSP). Another way to look
422:     at this is when you create a SNES you do not NEED to create a KSP and attach it to 
423:     the SNES object (the SNES object manages it for you). Similarly when you create a KSP
424:     you do not need to attach a PC to it (the KSP object manages the PC object for you).
425:     Thus, why should YOU have to create the Mat and attach it to the SNES/KSP/PC, when
426:     it can be created for you?

428: .keywords: KSP, set, operators, matrix, preconditioner, linear system

430: .seealso: KSPSolve(), KSPGetPC(), PCGetOperators(), PCSetOperators(), KSPGetOperators()
431: @*/
432: PetscErrorCode  KSPSetOperators(KSP ksp,Mat Amat,Mat Pmat,MatStructure flag)
433: {

442:   if (!ksp->pc) {KSPGetPC(ksp,&ksp->pc);}
443:   PCSetOperators(ksp->pc,Amat,Pmat,flag);
444:   if (ksp->setupstage == KSP_SETUP_NEWRHS) ksp->setupstage = KSP_SETUP_NEWMATRIX;  /* so that next solve call will call PCSetUp() on new matrix */
445:   if (ksp->guess) {
446:     KSPFischerGuessReset(ksp->guess);
447:   }
448:   return(0);
449: }

453: /*@
454:    KSPGetOperators - Gets the matrix associated with the linear system
455:    and a (possibly) different one associated with the preconditioner. 

457:    Collective on KSP and Mat

459:    Input Parameter:
460: .  ksp - the KSP context

462:    Output Parameters:
463: +  Amat - the matrix associated with the linear system
464: .  Pmat - the matrix to be used in constructing the preconditioner, usually the same as Amat. 
465: -  flag - flag indicating information about the preconditioner matrix structure
466:    during successive linear solves.  This flag is ignored the first time a
467:    linear system is solved, and thus is irrelevant when solving just one linear
468:    system.

470:     Level: intermediate

472:    Notes: DOES NOT increase the reference counts of the matrix, so you should NOT destroy them.

474: .keywords: KSP, set, get, operators, matrix, preconditioner, linear system

476: .seealso: KSPSolve(), KSPGetPC(), PCGetOperators(), PCSetOperators(), KSPSetOperators(), KSPGetOperatorsSet()
477: @*/
478: PetscErrorCode  KSPGetOperators(KSP ksp,Mat *Amat,Mat *Pmat,MatStructure *flag)
479: {

484:   if (!ksp->pc) {KSPGetPC(ksp,&ksp->pc);}
485:   PCGetOperators(ksp->pc,Amat,Pmat,flag);
486:   return(0);
487: }

491: /*@C
492:    KSPGetOperatorsSet - Determines if the matrix associated with the linear system and
493:    possibly a different one associated with the preconditioner have been set in the KSP.

495:    Not collective, though the results on all processes should be the same

497:    Input Parameter:
498: .  pc - the preconditioner context

500:    Output Parameters:
501: +  mat - the matrix associated with the linear system was set
502: -  pmat - matrix associated with the preconditioner was set, usually the same

504:    Level: intermediate

506: .keywords: KSP, get, operators, matrix, linear system

508: .seealso: PCSetOperators(), KSPGetOperators(), KSPSetOperators(), PCGetOperators(), PCGetOperatorsSet()
509: @*/
510: PetscErrorCode  KSPGetOperatorsSet(KSP ksp,PetscBool  *mat,PetscBool  *pmat)
511: {

516:   if (!ksp->pc) {KSPGetPC(ksp,&ksp->pc);}
517:   PCGetOperatorsSet(ksp->pc,mat,pmat);
518:   return(0);
519: }

523: /*@
524:    KSPCreate - Creates the default KSP context.

526:    Collective on MPI_Comm

528:    Input Parameter:
529: .  comm - MPI communicator

531:    Output Parameter:
532: .  ksp - location to put the KSP context

534:    Notes:
535:    The default KSP type is GMRES with a restart of 30, using modified Gram-Schmidt
536:    orthogonalization.

538:    Level: beginner

540: .keywords: KSP, create, context

542: .seealso: KSPSetUp(), KSPSolve(), KSPDestroy(), KSP
543: @*/
544: PetscErrorCode  KSPCreate(MPI_Comm comm,KSP *inksp)
545: {
546:   KSP            ksp;
548:   void           *ctx;

552:   *inksp = 0;
553: #ifndef PETSC_USE_DYNAMIC_LIBRARIES
554:   KSPInitializePackage(PETSC_NULL);
555: #endif

557:   PetscHeaderCreate(ksp,_p_KSP,struct _KSPOps,KSP_CLASSID,-1,"KSP","Krylov Method","KSP",comm,KSPDestroy,KSPView);

559:   ksp->max_it        = 10000;
560:   ksp->pc_side       = PC_SIDE_DEFAULT;
561:   ksp->rtol          = 1.e-5;
562:   ksp->abstol        = 1.e-50;
563:   ksp->divtol        = 1.e4;

565:   ksp->chknorm             = -1;
566:   ksp->normtype            = KSP_NORM_DEFAULT;
567:   ksp->rnorm               = 0.0;
568:   ksp->its                 = 0;
569:   ksp->guess_zero          = PETSC_TRUE;
570:   ksp->calc_sings          = PETSC_FALSE;
571:   ksp->res_hist            = PETSC_NULL;
572:   ksp->res_hist_alloc      = PETSC_NULL;
573:   ksp->res_hist_len        = 0;
574:   ksp->res_hist_max        = 0;
575:   ksp->res_hist_reset      = PETSC_TRUE;
576:   ksp->numbermonitors      = 0;

578:   KSPDefaultConvergedCreate(&ctx);
579:   KSPSetConvergenceTest(ksp,KSPDefaultConverged,ctx,KSPDefaultConvergedDestroy);
580:   ksp->ops->buildsolution  = KSPDefaultBuildSolution;
581:   ksp->ops->buildresidual  = KSPDefaultBuildResidual;
582: #if defined(PETSC_HAVE_AMS)
583:   ((PetscObject)ksp)->bops->publish       = KSPPublish_Petsc;
584: #endif

586:   ksp->vec_sol         = 0;
587:   ksp->vec_rhs         = 0;
588:   ksp->pc              = 0;
589:   ksp->data            = 0;
590:   ksp->nwork           = 0;
591:   ksp->work            = 0;
592:   ksp->reason          = KSP_CONVERGED_ITERATING;
593:   ksp->setupstage      = KSP_SETUP_NEW;

595:   KSPNormSupportTableReset_Private(ksp);

597:   *inksp = ksp;
598:   return(0);
599: }
600: 
603: /*@C
604:    KSPSetType - Builds KSP for a particular solver. 

606:    Logically Collective on KSP

608:    Input Parameters:
609: +  ksp      - the Krylov space context
610: -  type - a known method

612:    Options Database Key:
613: .  -ksp_type  <method> - Sets the method; use -help for a list 
614:     of available methods (for instance, cg or gmres)

616:    Notes:  
617:    See "petsc/include/petscksp.h" for available methods (for instance,
618:    KSPCG or KSPGMRES).

620:   Normally, it is best to use the KSPSetFromOptions() command and
621:   then set the KSP type from the options database rather than by using
622:   this routine.  Using the options database provides the user with
623:   maximum flexibility in evaluating the many different Krylov methods.
624:   The KSPSetType() routine is provided for those situations where it
625:   is necessary to set the iterative solver independently of the command
626:   line or options database.  This might be the case, for example, when
627:   the choice of iterative solver changes during the execution of the
628:   program, and the user's application is taking responsibility for
629:   choosing the appropriate method.  In other words, this routine is
630:   not for beginners.

632:   Level: intermediate

634: .keywords: KSP, set, method

636: .seealso: PCSetType(), KSPType

638: @*/
639: PetscErrorCode  KSPSetType(KSP ksp, const KSPType type)
640: {
641:   PetscErrorCode ierr,(*r)(KSP);
642:   PetscBool      match;


648:   PetscTypeCompare((PetscObject)ksp,type,&match);
649:   if (match) return(0);

651:    PetscFListFind(KSPList,((PetscObject)ksp)->comm,type,PETSC_TRUE,(void (**)(void)) &r);
652:   if (!r) SETERRQ1(((PetscObject)ksp)->comm,PETSC_ERR_ARG_UNKNOWN_TYPE,"Unable to find requested KSP type %s",type);
653:   /* Destroy the previous private KSP context */
654:   if (ksp->ops->destroy) { (*ksp->ops->destroy)(ksp); }
655:   /* Reinitialize function pointers in KSPOps structure */
656:   PetscMemzero(ksp->ops,sizeof(struct _KSPOps));
657:   ksp->ops->buildsolution = KSPDefaultBuildSolution;
658:   ksp->ops->buildresidual = KSPDefaultBuildResidual;
659:   KSPNormSupportTableReset_Private(ksp);
660:   /* Call the KSPCreate_XXX routine for this particular Krylov solver */
661:   ksp->setupstage = KSP_SETUP_NEW;
662:   PetscObjectChangeTypeName((PetscObject)ksp,type);
663:   (*r)(ksp);
664: #if defined(PETSC_HAVE_AMS)
665:   if (PetscAMSPublishAll) {
666:     PetscObjectAMSPublish((PetscObject)ksp);
667:   }
668: #endif
669:   return(0);
670: }

674: /*@
675:    KSPRegisterDestroy - Frees the list of KSP methods that were
676:    registered by KSPRegisterDynamic().

678:    Not Collective

680:    Level: advanced

682: .keywords: KSP, register, destroy

684: .seealso: KSPRegisterDynamic(), KSPRegisterAll()
685: @*/
686: PetscErrorCode  KSPRegisterDestroy(void)
687: {

691:   PetscFListDestroy(&KSPList);
692:   KSPRegisterAllCalled = PETSC_FALSE;
693:   return(0);
694: }

698: /*@C
699:    KSPGetType - Gets the KSP type as a string from the KSP object.

701:    Not Collective

703:    Input Parameter:
704: .  ksp - Krylov context 

706:    Output Parameter:
707: .  name - name of KSP method 

709:    Level: intermediate

711: .keywords: KSP, get, method, name

713: .seealso: KSPSetType()
714: @*/
715: PetscErrorCode  KSPGetType(KSP ksp,const KSPType *type)
716: {
720:   *type = ((PetscObject)ksp)->type_name;
721:   return(0);
722: }

726: /*@C
727:   KSPRegister - See KSPRegisterDynamic()

729:   Level: advanced
730: @*/
731: PetscErrorCode  KSPRegister(const char sname[],const char path[],const char name[],PetscErrorCode (*function)(KSP))
732: {
734:   char           fullname[PETSC_MAX_PATH_LEN];

737:   PetscFListConcat(path,name,fullname);
738:   PetscFListAdd(&KSPList,sname,fullname,(void (*)(void))function);
739:   return(0);
740: }

744: /*@
745:   KSPSetNullSpace - Sets the null space of the operator

747:   Logically Collective on KSP

749:   Input Parameters:
750: +  ksp - the Krylov space object
751: -  nullsp - the null space of the operator

753:   Level: advanced

755: .seealso: KSPSetOperators(), MatNullSpaceCreate(), KSPGetNullSpace()
756: @*/
757: PetscErrorCode  KSPSetNullSpace(KSP ksp,MatNullSpace nullsp)
758: {

764:   PetscObjectReference((PetscObject)nullsp);
765:   if (ksp->nullsp) { MatNullSpaceDestroy(&ksp->nullsp); }
766:   ksp->nullsp = nullsp;
767:   return(0);
768: }

772: /*@
773:   KSPGetNullSpace - Gets the null space of the operator

775:   Not Collective

777:   Input Parameters:
778: +  ksp - the Krylov space object
779: -  nullsp - the null space of the operator

781:   Level: advanced

783: .seealso: KSPSetOperators(), MatNullSpaceCreate(), KSPSetNullSpace()
784: @*/
785: PetscErrorCode  KSPGetNullSpace(KSP ksp,MatNullSpace *nullsp)
786: {
790:   *nullsp = ksp->nullsp;
791:   return(0);
792: }