Actual source code: itcreate.c

petsc-3.3-p7 2013-05-11
  2: /*
  3:      The basic KSP routines, Create, View etc. are here.
  4: */
  5: #include <petsc-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:   PetscObjectTypeCompare((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, CHEBYSHEV, 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,KSPNormType *normtype,PCSide *pcside)
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:   *normtype = (KSPNormType)ibest;
287:   *pcside = (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,&ksp->normtype,&ksp->pc_side);
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: {
434:   MatNullSpace   nullsp;

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

460: /*@
461:    KSPGetOperators - Gets the matrix associated with the linear system
462:    and a (possibly) different one associated with the preconditioner. 

464:    Collective on KSP and Mat

466:    Input Parameter:
467: .  ksp - the KSP context

469:    Output Parameters:
470: +  Amat - the matrix associated with the linear system
471: .  Pmat - the matrix to be used in constructing the preconditioner, usually the same as Amat. 
472: -  flag - flag indicating information about the preconditioner matrix structure
473:    during successive linear solves.  This flag is ignored the first time a
474:    linear system is solved, and thus is irrelevant when solving just one linear
475:    system.

477:     Level: intermediate

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

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

483: .seealso: KSPSolve(), KSPGetPC(), PCGetOperators(), PCSetOperators(), KSPSetOperators(), KSPGetOperatorsSet()
484: @*/
485: PetscErrorCode  KSPGetOperators(KSP ksp,Mat *Amat,Mat *Pmat,MatStructure *flag)
486: {

491:   if (!ksp->pc) {KSPGetPC(ksp,&ksp->pc);}
492:   PCGetOperators(ksp->pc,Amat,Pmat,flag);
493:   return(0);
494: }

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

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

504:    Input Parameter:
505: .  pc - the KSP context

507:    Output Parameters:
508: +  mat - the matrix associated with the linear system was set
509: -  pmat - matrix associated with the preconditioner was set, usually the same

511:    Level: intermediate

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

515: .seealso: PCSetOperators(), KSPGetOperators(), KSPSetOperators(), PCGetOperators(), PCGetOperatorsSet()
516: @*/
517: PetscErrorCode  KSPGetOperatorsSet(KSP ksp,PetscBool  *mat,PetscBool  *pmat)
518: {

523:   if (!ksp->pc) {KSPGetPC(ksp,&ksp->pc);}
524:   PCGetOperatorsSet(ksp->pc,mat,pmat);
525:   return(0);
526: }

530: /*@
531:    KSPCreate - Creates the default KSP context.

533:    Collective on MPI_Comm

535:    Input Parameter:
536: .  comm - MPI communicator

538:    Output Parameter:
539: .  ksp - location to put the KSP context

541:    Notes:
542:    The default KSP type is GMRES with a restart of 30, using modified Gram-Schmidt
543:    orthogonalization.

545:    Level: beginner

547: .keywords: KSP, create, context

549: .seealso: KSPSetUp(), KSPSolve(), KSPDestroy(), KSP
550: @*/
551: PetscErrorCode  KSPCreate(MPI_Comm comm,KSP *inksp)
552: {
553:   KSP            ksp;
555:   void           *ctx;

559:   *inksp = 0;
560: #ifndef PETSC_USE_DYNAMIC_LIBRARIES
561:   KSPInitializePackage(PETSC_NULL);
562: #endif

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

566:   ksp->max_it        = 10000;
567:   ksp->pc_side       = PC_SIDE_DEFAULT;
568:   ksp->rtol          = 1.e-5;
569:   ksp->abstol        = 1.e-50;
570:   ksp->divtol        = 1.e4;

572:   ksp->chknorm             = -1;
573:   ksp->normtype            = KSP_NORM_DEFAULT;
574:   ksp->rnorm               = 0.0;
575:   ksp->its                 = 0;
576:   ksp->guess_zero          = PETSC_TRUE;
577:   ksp->calc_sings          = PETSC_FALSE;
578:   ksp->res_hist            = PETSC_NULL;
579:   ksp->res_hist_alloc      = PETSC_NULL;
580:   ksp->res_hist_len        = 0;
581:   ksp->res_hist_max        = 0;
582:   ksp->res_hist_reset      = PETSC_TRUE;
583:   ksp->numbermonitors      = 0;

585:   KSPDefaultConvergedCreate(&ctx);
586:   KSPSetConvergenceTest(ksp,KSPDefaultConverged,ctx,KSPDefaultConvergedDestroy);
587:   ksp->ops->buildsolution  = KSPDefaultBuildSolution;
588:   ksp->ops->buildresidual  = KSPDefaultBuildResidual;
589: #if defined(PETSC_HAVE_AMS)
590:   ((PetscObject)ksp)->bops->publish       = KSPPublish_Petsc;
591: #endif

593:   ksp->vec_sol         = 0;
594:   ksp->vec_rhs         = 0;
595:   ksp->pc              = 0;
596:   ksp->data            = 0;
597:   ksp->nwork           = 0;
598:   ksp->work            = 0;
599:   ksp->reason          = KSP_CONVERGED_ITERATING;
600:   ksp->setupstage      = KSP_SETUP_NEW;

602:   KSPNormSupportTableReset_Private(ksp);

604:   *inksp = ksp;
605:   return(0);
606: }
607: 
610: /*@C
611:    KSPSetType - Builds KSP for a particular solver. 

613:    Logically Collective on KSP

615:    Input Parameters:
616: +  ksp      - the Krylov space context
617: -  type - a known method

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

623:    Notes:  
624:    See "petsc/include/petscksp.h" for available methods (for instance,
625:    KSPCG or KSPGMRES).

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

639:   Level: intermediate

641: .keywords: KSP, set, method

643: .seealso: PCSetType(), KSPType

645: @*/
646: PetscErrorCode  KSPSetType(KSP ksp, const KSPType type)
647: {
648:   PetscErrorCode ierr,(*r)(KSP);
649:   PetscBool      match;


655:   PetscObjectTypeCompare((PetscObject)ksp,type,&match);
656:   if (match) return(0);

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

684: /*@
685:    KSPRegisterDestroy - Frees the list of KSP methods that were
686:    registered by KSPRegisterDynamic().

688:    Not Collective

690:    Level: advanced

692: .keywords: KSP, register, destroy

694: .seealso: KSPRegisterDynamic(), KSPRegisterAll()
695: @*/
696: PetscErrorCode  KSPRegisterDestroy(void)
697: {

701:   PetscFListDestroy(&KSPList);
702:   KSPRegisterAllCalled = PETSC_FALSE;
703:   return(0);
704: }

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

711:    Not Collective

713:    Input Parameter:
714: .  ksp - Krylov context 

716:    Output Parameter:
717: .  name - name of KSP method 

719:    Level: intermediate

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

723: .seealso: KSPSetType()
724: @*/
725: PetscErrorCode  KSPGetType(KSP ksp,const KSPType *type)
726: {
730:   *type = ((PetscObject)ksp)->type_name;
731:   return(0);
732: }

736: /*@C
737:   KSPRegister - See KSPRegisterDynamic()

739:   Level: advanced
740: @*/
741: PetscErrorCode  KSPRegister(const char sname[],const char path[],const char name[],PetscErrorCode (*function)(KSP))
742: {
744:   char           fullname[PETSC_MAX_PATH_LEN];

747:   PetscFListConcat(path,name,fullname);
748:   PetscFListAdd(&KSPList,sname,fullname,(void (*)(void))function);
749:   return(0);
750: }

754: /*@
755:   KSPSetNullSpace - Sets the null space of the operator

757:   Logically Collective on KSP

759:   Input Parameters:
760: +  ksp - the Krylov space object
761: -  nullsp - the null space of the operator

763:   Level: advanced

765: .seealso: KSPSetOperators(), MatNullSpaceCreate(), KSPGetNullSpace(), MatSetNullSpace()
766: @*/
767: PetscErrorCode  KSPSetNullSpace(KSP ksp,MatNullSpace nullsp)
768: {

774:   PetscObjectReference((PetscObject)nullsp);
775:   if (ksp->nullsp) { MatNullSpaceDestroy(&ksp->nullsp); }
776:   ksp->nullsp = nullsp;
777:   return(0);
778: }

782: /*@
783:   KSPGetNullSpace - Gets the null space of the operator

785:   Not Collective

787:   Input Parameters:
788: +  ksp - the Krylov space object
789: -  nullsp - the null space of the operator

791:   Level: advanced

793: .seealso: KSPSetOperators(), MatNullSpaceCreate(), KSPSetNullSpace()
794: @*/
795: PetscErrorCode  KSPGetNullSpace(KSP ksp,MatNullSpace *nullsp)
796: {
800:   *nullsp = ksp->nullsp;
801:   return(0);
802: }