Actual source code: itcreate.c

  1: #define PETSCKSP_DLL

  3: /*
  4:      The basic KSP routines, Create, View etc. are here.
  5: */
 6:  #include include/private/kspimpl.h
 7:  #include petscsys.h

  9: /* Logging support */
 10: PetscCookie  KSP_COOKIE = 0;
 11: PetscEvent  KSP_GMRESOrthogonalization = 0, KSP_SetUp = 0, KSP_Solve = 0;


 14: PetscTruth KSPRegisterAllCalled = PETSC_FALSE;

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

 21:    Collective on KSP

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

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

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

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

 41:    Level: beginner

 43: .keywords: KSP, view

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

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

 59:   PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_ASCII,&iascii);
 60:   if (iascii) {
 61:     KSPGetType(ksp,&type);
 62:     if (((PetscObject)ksp)->prefix) {
 63:       PetscViewerASCIIPrintf(viewer,"KSP Object:(%s)\n",((PetscObject)ksp)->prefix);
 64:     } else {
 65:       PetscViewerASCIIPrintf(viewer,"KSP Object:\n");
 66:     }
 67:     if (type) {
 68:       PetscViewerASCIIPrintf(viewer,"  type: %s\n",type);
 69:     } else {
 70:       PetscViewerASCIIPrintf(viewer,"  type: not yet set\n");
 71:     }
 72:     if (ksp->ops->view) {
 73:       PetscViewerASCIIPushTab(viewer);
 74:       (*ksp->ops->view)(ksp,viewer);
 75:       PetscViewerASCIIPopTab(viewer);
 76:     }
 77:     if (ksp->guess_zero) {PetscViewerASCIIPrintf(viewer,"  maximum iterations=%D, initial guess is zero\n",ksp->max_it);}
 78:     else                 {PetscViewerASCIIPrintf(viewer,"  maximum iterations=%D\n", ksp->max_it);}
 79:     if (ksp->guess_knoll) {PetscViewerASCIIPrintf(viewer,"  using preconditioner applied to right hand side for initial guess\n");}
 80:     PetscViewerASCIIPrintf(viewer,"  tolerances:  relative=%G, absolute=%G, divergence=%G\n",ksp->rtol,ksp->abstol,ksp->divtol);
 81:     if (ksp->pc_side == PC_RIGHT)          {PetscViewerASCIIPrintf(viewer,"  right preconditioning\n");}
 82:     else if (ksp->pc_side == PC_SYMMETRIC) {PetscViewerASCIIPrintf(viewer,"  symmetric preconditioning\n");}
 83:     else                                   {PetscViewerASCIIPrintf(viewer,"  left preconditioning\n");}
 84:   } else {
 85:     if (ksp->ops->view) {
 86:       (*ksp->ops->view)(ksp,viewer);
 87:     }
 88:   }
 89:   PCView(ksp->pc,viewer);
 90:   return(0);
 91: }

 93: /*
 94:    Contains the list of registered KSP routines
 95: */
 96: PetscFList KSPList = 0;

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

103:    Collective on KSP

105:    Input Parameter:
106: +  ksp - Krylov solver context
107: -  normtype - one of 
108: $   KSP_NORM_NO - skips computing the norm, this should only be used if you are using
109: $                 the Krylov method as a smoother with a fixed small number of iterations.
110: $                 Implicitly sets KSPSkipConverged as KSP convergence test.
111: $                 Supported only by CG, Richardson, Bi-CG-stab, CR, and CGS methods.
112: $   KSP_NORM_PRECONDITIONED - the default for left preconditioned solves, uses the l2 norm
113: $                 of the preconditioned residual
114: $   KSP_NORM_UNPRECONDITIONED - uses the l2 norm of the true b - Ax residual, supported only by
115: $                 CG, CHEBYCHEV, and RICHARDSON, automatically true for right (see KSPSetPreconditioningSide()) 
116: $                 preconditioning..
117: $   KSP_NORM_NATURAL - supported  by cg, cr, and cgs 


120:    Options Database Key:
121: .   -ksp_norm_type <none,preconditioned,unpreconditioned,natural>

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

126:    Level: advanced

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

130: .seealso: KSPSetUp(), KSPSolve(), KSPDestroy(), KSPSkipConverged()                               
131: @*/
132: PetscErrorCode  KSPSetNormType(KSP ksp,KSPNormType normtype)
133: {

138:   ksp->normtype = normtype;
139:   if (normtype == KSP_NORM_NO) {
140:     KSPSetConvergenceTest(ksp,KSPSkipConverged,0,0);
141:     PetscInfo(ksp,"Warning: setting KSPNormType to skip computing the norm\n\
142:  KSP convergence test is implicitly set to KSPSkipConverged\n");
143:   }
144:   return(0);
145: }

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

153:    Collective on KSP

155:    Input Parameter:
156: +  ksp - Krylov solver context
157: -  it  - use -1 to check at all iterations

159:    Notes: 
160:    Currently only works with Bi-CG-stab

162:    Use KSPSetNormType(ksp,KSP_NORM_NO) to never check the norm

164:    Level: advanced

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

168: .seealso: KSPSetUp(), KSPSolve(), KSPDestroy(), KSPSkipConverged(), KSPSetNormType()                               
169: @*/
170: PetscErrorCode  KSPSetCheckNormIteration(KSP ksp,PetscInt it)
171: {
174:   ksp->chknorm = it;
175:   return(0);
176: }

180: /*@
181:    KSPGetNormType - Sets the norm that is used for convergence testing.

183:    Not Collective

185:    Input Parameter:
186: .  ksp - Krylov solver context

188:    Output Parameter:
189: .  normtype - norm that is used for convergence testing

191:    Level: advanced

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

195: .seealso: KSPNormType, KSPSetNormType(), KSPSkipConverged()
196: @*/
197: PetscErrorCode  KSPGetNormType(KSP ksp, KSPNormType *normtype) {
201:   *normtype = ksp->normtype;
202:   return(0);
203: }

205: #if 0
208: static PetscErrorCode KSPPublish_Petsc(PetscObject obj)
209: {
211:   return(0);
212: }
213: #endif

217: /*@
218:    KSPSetOperators - Sets the matrix associated with the linear system
219:    and a (possibly) different one associated with the preconditioner. 

221:    Collective on KSP and Mat

223:    Input Parameters:
224: +  ksp - the KSP context
225: .  Amat - the matrix associated with the linear system
226: .  Pmat - the matrix to be used in constructing the preconditioner, usually the
227:           same as Amat. 
228: -  flag - flag indicating information about the preconditioner matrix structure
229:    during successive linear solves.  This flag is ignored the first time a
230:    linear system is solved, and thus is irrelevant when solving just one linear
231:    system.

233:    Notes: 
234:    The flag can be used to eliminate unnecessary work in the preconditioner 
235:    during the repeated solution of linear systems of the same size.  The
236:    available options are
237: $    SAME_PRECONDITIONER -
238: $      Pmat is identical during successive linear solves.
239: $      This option is intended for folks who are using
240: $      different Amat and Pmat matrices and want to reuse the
241: $      same preconditioner matrix.  For example, this option
242: $      saves work by not recomputing incomplete factorization
243: $      for ILU/ICC preconditioners.
244: $    SAME_NONZERO_PATTERN -
245: $      Pmat has the same nonzero structure during
246: $      successive linear solves. 
247: $    DIFFERENT_NONZERO_PATTERN -
248: $      Pmat does not have the same nonzero structure.

250:     Caution:
251:     If you specify SAME_NONZERO_PATTERN, PETSc believes your assertion
252:     and does not check the structure of the matrix.  If you erroneously
253:     claim that the structure is the same when it actually is not, the new
254:     preconditioner will not function correctly.  Thus, use this optimization
255:     feature carefully!

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

260:     Level: beginner

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

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

273: $         MatCreate(comm,&mat);
274: $         KSP/PCSetOperators(ksp/pc,mat,mat,SAME_NONZERO_PATTERN);
275: $         PetscObjectDereference((PetscObject)mat);
276: $           set size, type, etc of mat

278:      and

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

283: $         MatCreate(comm,&mat);
284: $         MatCreate(comm,&pmat);
285: $         KSP/PCSetOperators(ksp/pc,mat,pmat,SAME_NONZERO_PATTERN);
286: $         PetscObjectDereference((PetscObject)mat);
287: $         PetscObjectDereference((PetscObject)pmat);
288: $           set size, type, etc of mat and pmat

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

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

301: .seealso: KSPSolve(), KSPGetPC(), PCGetOperators(), PCSetOperators(), KSPGetOperators()
302: @*/
303: PetscErrorCode  KSPSetOperators(KSP ksp,Mat Amat,Mat Pmat,MatStructure flag)
304: {

313:   PCSetOperators(ksp->pc,Amat,Pmat,flag);
314:   if (ksp->setupcalled > 1) ksp->setupcalled = 1;  /* so that next solve call will call setup */
315:   return(0);
316: }

320: /*@
321:    KSPGetOperators - Gets the matrix associated with the linear system
322:    and a (possibly) different one associated with the preconditioner. 

324:    Collective on KSP and Mat

326:    Input Parameter:
327: .  ksp - the KSP context

329:    Output Parameters:
330: +  Amat - the matrix associated with the linear system
331: .  Pmat - the matrix to be used in constructing the preconditioner, usually the
332:           same as Amat. 
333: -  flag - flag indicating information about the preconditioner matrix structure
334:    during successive linear solves.  This flag is ignored the first time a
335:    linear system is solved, and thus is irrelevant when solving just one linear
336:    system.

338:     Level: intermediate

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

342: .seealso: KSPSolve(), KSPGetPC(), PCGetOperators(), PCSetOperators(), KSPSetOperators(), KSPGetOperatorsSet()
343: @*/
344: PetscErrorCode  KSPGetOperators(KSP ksp,Mat *Amat,Mat *Pmat,MatStructure *flag)
345: {

350:   PCGetOperators(ksp->pc,Amat,Pmat,flag);
351:   return(0);
352: }

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

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

362:    Input Parameter:
363: .  pc - the preconditioner context

365:    Output Parameters:
366: +  mat - the matrix associated with the linear system was set
367: -  pmat - matrix associated with the preconditioner was set, usually the same

369:    Level: intermediate

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

373: .seealso: PCSetOperators(), KSPGetOperators(), KSPSetOperators(), PCGetOperators(), PCGetOperatorsSet()
374: @*/
375: PetscErrorCode  KSPGetOperatorsSet(KSP ksp,PetscTruth *mat,PetscTruth *pmat)
376: {

381:   PCGetOperatorsSet(ksp->pc,mat,pmat);
382:   return(0);
383: }

387: /*@
388:    KSPCreate - Creates the default KSP context.

390:    Collective on MPI_Comm

392:    Input Parameter:
393: .  comm - MPI communicator

395:    Output Parameter:
396: .  ksp - location to put the KSP context

398:    Notes:
399:    The default KSP type is GMRES with a restart of 30, using modified Gram-Schmidt
400:    orthogonalization.

402:    Level: beginner

404: .keywords: KSP, create, context

406: .seealso: KSPSetUp(), KSPSolve(), KSPDestroy(), KSP
407: @*/
408: PetscErrorCode  KSPCreate(MPI_Comm comm,KSP *inksp)
409: {
410:   KSP            ksp;
412:   void           *ctx;

416:   *inksp = 0;
417: #ifndef PETSC_USE_DYNAMIC_LIBRARIES
418:   KSPInitializePackage(PETSC_NULL);
419: #endif

421:   PetscHeaderCreate(ksp,_p_KSP,struct _KSPOps,KSP_COOKIE,-1,"KSP",comm,KSPDestroy,KSPView);

423:   ksp->max_it        = 10000;
424:   ksp->pc_side       = PC_LEFT;
425:   ksp->rtol          = 1.e-5;
426:   ksp->abstol        = 1.e-50;
427:   ksp->divtol        = 1.e4;
428: 
429:   ksp->chknorm             = -1;
430:   ksp->normtype            = KSP_NORM_PRECONDITIONED;
431:   ksp->rnorm               = 0.0;
432:   ksp->its                 = 0;
433:   ksp->guess_zero          = PETSC_TRUE;
434:   ksp->calc_sings          = PETSC_FALSE;
435:   ksp->res_hist            = PETSC_NULL;
436:   ksp->res_hist_alloc      = PETSC_NULL;
437:   ksp->res_hist_len        = 0;
438:   ksp->res_hist_max        = 0;
439:   ksp->res_hist_reset      = PETSC_TRUE;
440:   ksp->numbermonitors      = 0;

442:   KSPDefaultConvergedCreate(&ctx);
443:   KSPSetConvergenceTest(ksp,KSPDefaultConverged,ctx,KSPDefaultConvergedDestroy);
444:   ksp->ops->buildsolution  = KSPDefaultBuildSolution;
445:   ksp->ops->buildresidual  = KSPDefaultBuildResidual;

447:   ksp->vec_sol         = 0;
448:   ksp->vec_rhs         = 0;
449:   ksp->pc              = 0;
450:   ksp->data            = 0;
451:   ksp->nwork           = 0;
452:   ksp->work            = 0;
453:   ksp->reason          = KSP_CONVERGED_ITERATING;
454:   ksp->setupcalled     = 0;

456:   PetscPublishAll(ksp);
457:   PCCreate(comm,&ksp->pc);
458:   *inksp = ksp;
459:   return(0);
460: }
461: 
464: /*@C
465:    KSPSetType - Builds KSP for a particular solver. 

467:    Collective on KSP

469:    Input Parameters:
470: +  ksp      - the Krylov space context
471: -  type - a known method

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

477:    Notes:  
478:    See "petsc/include/petscksp.h" for available methods (for instance,
479:    KSPCG or KSPGMRES).

481:   Normally, it is best to use the KSPSetFromOptions() command and
482:   then set the KSP type from the options database rather than by using
483:   this routine.  Using the options database provides the user with
484:   maximum flexibility in evaluating the many different Krylov methods.
485:   The KSPSetType() routine is provided for those situations where it
486:   is necessary to set the iterative solver independently of the command
487:   line or options database.  This might be the case, for example, when
488:   the choice of iterative solver changes during the execution of the
489:   program, and the user's application is taking responsibility for
490:   choosing the appropriate method.  In other words, this routine is
491:   not for beginners.

493:   Level: intermediate

495: .keywords: KSP, set, method

497: .seealso: PCSetType(), KSPType

499: @*/
500: PetscErrorCode  KSPSetType(KSP ksp, KSPType type)
501: {
502:   PetscErrorCode ierr,(*r)(KSP);
503:   PetscTruth     match;


509:   PetscTypeCompare((PetscObject)ksp,type,&match);
510:   if (match) return(0);

512:    PetscFListFind(KSPList,((PetscObject)ksp)->comm,type,(void (**)(void)) &r);
513:   if (!r) SETERRQ1(PETSC_ERR_ARG_UNKNOWN_TYPE,"Unable to find requested KSP type %s",type);
514:   /* Destroy the previous private KSP context */
515:   if (ksp->ops->destroy) { (*ksp->ops->destroy)(ksp); }
516:   /* Reinitialize function pointers in KSPOps structure */
517:   PetscMemzero(ksp->ops,sizeof(struct _KSPOps));
518:   ksp->ops->buildsolution = KSPDefaultBuildSolution;
519:   ksp->ops->buildresidual = KSPDefaultBuildResidual;
520:   /* Call the KSPCreate_XXX routine for this particular Krylov solver */
521:   ksp->setupcalled = 0;
522:   (*r)(ksp);
523:   PetscObjectChangeTypeName((PetscObject)ksp,type);
524:   return(0);
525: }

529: /*@
530:    KSPRegisterDestroy - Frees the list of KSP methods that were
531:    registered by KSPRegisterDynamic().

533:    Not Collective

535:    Level: advanced

537: .keywords: KSP, register, destroy

539: .seealso: KSPRegisterDynamic(), KSPRegisterAll()
540: @*/
541: PetscErrorCode  KSPRegisterDestroy(void)
542: {

546:   PetscFListDestroy(&KSPList);
547:   KSPRegisterAllCalled = PETSC_FALSE;
548:   return(0);
549: }

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

556:    Not Collective

558:    Input Parameter:
559: .  ksp - Krylov context 

561:    Output Parameter:
562: .  name - name of KSP method 

564:    Level: intermediate

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

568: .seealso: KSPSetType()
569: @*/
570: PetscErrorCode  KSPGetType(KSP ksp,KSPType *type)
571: {
575:   *type = ((PetscObject)ksp)->type_name;
576:   return(0);
577: }

581: /*@C
582:   KSPRegister - See KSPRegisterDynamic()

584:   Level: advanced
585: @*/
586: PetscErrorCode  KSPRegister(const char sname[],const char path[],const char name[],PetscErrorCode (*function)(KSP))
587: {
589:   char           fullname[PETSC_MAX_PATH_LEN];

592:   PetscFListConcat(path,name,fullname);
593:   PetscFListAdd(&KSPList,sname,fullname,(void (*)(void))function);
594:   return(0);
595: }

599: /*@
600:   KSPSetNullSpace - Sets the null space of the operator

602:   Collective on KSP

604:   Input Parameters:
605: +  ksp - the Krylov space object
606: -  nullsp - the null space of the operator

608:   Level: advanced

610: .seealso: KSPSetOperators(), MatNullSpaceCreate(), KSPGetNullSpace()
611: @*/
612: PetscErrorCode  KSPSetNullSpace(KSP ksp,MatNullSpace nullsp)
613: {

619:   PetscObjectReference((PetscObject)nullsp);
620:   if (ksp->nullsp) { MatNullSpaceDestroy(ksp->nullsp); }
621:   ksp->nullsp = nullsp;
622:   return(0);
623: }

627: /*@
628:   KSPGetNullSpace - Gets the null space of the operator

630:   Collective on KSP

632:   Input Parameters:
633: +  ksp - the Krylov space object
634: -  nullsp - the null space of the operator

636:   Level: advanced

638: .seealso: KSPSetOperators(), MatNullSpaceCreate(), KSPSetNullSpace()
639: @*/
640: PetscErrorCode  KSPGetNullSpace(KSP ksp,MatNullSpace *nullsp)
641: {
645:   *nullsp = ksp->nullsp;
646:   return(0);
647: }