Actual source code: itcreate.c

  1: #define PETSCKSP_DLL

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

  9: /* Logging support */
 10: PetscCookie PETSCKSP_DLLEXPORT 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 PETSCKSP_DLLEXPORT KSPView(KSP ksp,PetscViewer viewer)
 48: {
 49:   const char     *type;
 51:   PetscTruth     iascii;

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

 59:   PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_ASCII,&iascii);
 60:   if (iascii) {
 61:     KSPGetType(ksp,&type);
 62:     if (ksp->prefix) {
 63:       PetscViewerASCIIPrintf(viewer,"KSP Object:(%s)\n",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_NO_NORM - 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: $                 You must also call KSPSetConvergenceTest(ksp,KSPSkipConverged,PETSC_NULL);
111: $                 supported only by CG, Richardson, Bi-CG-stab, CR, and CGS methods.
112: $   KSP_PRECONDITIONED_NORM - the default for left preconditioned solves, uses the l2 norm
113: $                 of the preconditioned residual
114: $   KSP_UNPRECONDITIONED_NORM - uses the l2 norm of the true b - Ax residual, supported only by
115: $                 CG, CHEBYCHEV, and RICHARDSON  
116: $   KSP_NATURAL_NORM - supported  by cg, cr, and cgs 


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

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

125:    Level: advanced

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

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

137:   ksp->normtype = normtype;
138:   if (normtype == KSP_NO_NORM) {
139:     PetscInfo(ksp,"Warning seting KSPNormType to skip computing the norm\n\
140:   make sure you set the KSP convergence test to KSPSkipConvergence\n");
141:   }
142:   return(0);
143: }

147: static PetscErrorCode KSPPublish_Petsc(PetscObject obj)
148: {
150:   return(0);
151: }

155: /*@
156:    KSPSetOperators - Sets the matrix associated with the linear system
157:    and a (possibly) different one associated with the preconditioner. 

159:    Collective on KSP and Mat

161:    Input Parameters:
162: +  ksp - the KSP context
163: .  Amat - the matrix associated with the linear system
164: .  Pmat - the matrix to be used in constructing the preconditioner, usually the
165:           same as Amat. 
166: -  flag - flag indicating information about the preconditioner matrix structure
167:    during successive linear solves.  This flag is ignored the first time a
168:    linear system is solved, and thus is irrelevant when solving just one linear
169:    system.

171:    Notes: 
172:    The flag can be used to eliminate unnecessary work in the preconditioner 
173:    during the repeated solution of linear systems of the same size.  The
174:    available options are
175: $    SAME_PRECONDITIONER -
176: $      Pmat is identical during successive linear solves.
177: $      This option is intended for folks who are using
178: $      different Amat and Pmat matrices and want to reuse the
179: $      same preconditioner matrix.  For example, this option
180: $      saves work by not recomputing incomplete factorization
181: $      for ILU/ICC preconditioners.
182: $    SAME_NONZERO_PATTERN -
183: $      Pmat has the same nonzero structure during
184: $      successive linear solves. 
185: $    DIFFERENT_NONZERO_PATTERN -
186: $      Pmat does not have the same nonzero structure.

188:     Caution:
189:     If you specify SAME_NONZERO_PATTERN, PETSc believes your assertion
190:     and does not check the structure of the matrix.  If you erroneously
191:     claim that the structure is the same when it actually is not, the new
192:     preconditioner will not function correctly.  Thus, use this optimization
193:     feature carefully!

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

198:     Level: beginner

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

202: .seealso: KSPSolve(), KSPGetPC(), PCGetOperators(), PCSetOperators(), KSPGetOperators()
203: @*/
204: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetOperators(KSP ksp,Mat Amat,Mat Pmat,MatStructure flag)
205: {

214:   PCSetOperators(ksp->pc,Amat,Pmat,flag);
215:   if (ksp->setupcalled > 1) ksp->setupcalled = 1;  /* so that next solve call will call setup */
216:   return(0);
217: }

221: /*@
222:    KSPGetOperators - Gets the matrix associated with the linear system
223:    and a (possibly) different one associated with the preconditioner. 

225:    Collective on KSP and Mat

227:    Input Parameter:
228: .  ksp - the KSP context

230:    Output Parameters:
231: +  Amat - the matrix associated with the linear system
232: .  Pmat - the matrix to be used in constructing the preconditioner, usually the
233:           same as Amat. 
234: -  flag - flag indicating information about the preconditioner matrix structure
235:    during successive linear solves.  This flag is ignored the first time a
236:    linear system is solved, and thus is irrelevant when solving just one linear
237:    system.

239:     Level: intermediate

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

243: .seealso: KSPSolve(), KSPGetPC(), PCGetOperators(), PCSetOperators(), KSPSetOperators()
244: @*/
245: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetOperators(KSP ksp,Mat *Amat,Mat *Pmat,MatStructure *flag)
246: {

251:   PCGetOperators(ksp->pc,Amat,Pmat,flag);
252:   return(0);
253: }

257: /*@
258:    KSPCreate - Creates the default KSP context.

260:    Collective on MPI_Comm

262:    Input Parameter:
263: .  comm - MPI communicator

265:    Output Parameter:
266: .  ksp - location to put the KSP context

268:    Notes:
269:    The default KSP type is GMRES with a restart of 30, using modified Gram-Schmidt
270:    orthogonalization.

272:    Level: beginner

274: .keywords: KSP, create, context

276: .seealso: KSPSetUp(), KSPSolve(), KSPDestroy(), KSP
277: @*/
278: PetscErrorCode PETSCKSP_DLLEXPORT KSPCreate(MPI_Comm comm,KSP *inksp)
279: {
280:   KSP            ksp;

285:   *inksp = 0;
286: #ifndef PETSC_USE_DYNAMIC_LIBRARIES
287:   KSPInitializePackage(PETSC_NULL);
288: #endif

290:   PetscHeaderCreate(ksp,_p_KSP,struct _KSPOps,KSP_COOKIE,-1,"KSP",comm,KSPDestroy,KSPView);
291:   *inksp             = ksp;
292:   ksp->bops->publish = KSPPublish_Petsc;

294:   ksp->type          = -1;
295:   ksp->max_it        = 10000;
296:   ksp->pc_side       = PC_LEFT;
297:   ksp->rtol          = 1.e-5;
298:   ksp->abstol          = 1.e-50;
299:   ksp->divtol        = 1.e4;

301:   ksp->normtype            = KSP_PRECONDITIONED_NORM;
302:   ksp->rnorm               = 0.0;
303:   ksp->its                 = 0;
304:   ksp->guess_zero          = PETSC_TRUE;
305:   ksp->calc_sings          = PETSC_FALSE;
306:   ksp->res_hist            = PETSC_NULL;
307:   ksp->res_hist_len        = 0;
308:   ksp->res_hist_max        = 0;
309:   ksp->res_hist_reset      = PETSC_TRUE;
310:   ksp->numbermonitors      = 0;
311:   ksp->converged           = KSPDefaultConverged;
312:   ksp->ops->buildsolution  = KSPDefaultBuildSolution;
313:   ksp->ops->buildresidual  = KSPDefaultBuildResidual;

315:   ksp->ops->setfromoptions = 0;

317:   ksp->vec_sol         = 0;
318:   ksp->vec_rhs         = 0;
319:   ksp->pc              = 0;

321:   ksp->ops->solve      = 0;
322:   ksp->ops->setup      = 0;
323:   ksp->ops->destroy    = 0;

325:   ksp->data            = 0;
326:   ksp->nwork           = 0;
327:   ksp->work            = 0;

329:   ksp->cnvP            = 0;

331:   ksp->reason          = KSP_CONVERGED_ITERATING;

333:   ksp->setupcalled     = 0;
334:   PetscPublishAll(ksp);
335:   PCCreate(comm,&ksp->pc);
336:   return(0);
337: }
338: 
341: /*@C
342:    KSPSetType - Builds KSP for a particular solver. 

344:    Collective on KSP

346:    Input Parameters:
347: +  ksp      - the Krylov space context
348: -  type - a known method

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

354:    Notes:  
355:    See "petsc/include/petscksp.h" for available methods (for instance,
356:    KSPCG or KSPGMRES).

358:   Normally, it is best to use the KSPSetFromOptions() command and
359:   then set the KSP type from the options database rather than by using
360:   this routine.  Using the options database provides the user with
361:   maximum flexibility in evaluating the many different Krylov methods.
362:   The KSPSetType() routine is provided for those situations where it
363:   is necessary to set the iterative solver independently of the command
364:   line or options database.  This might be the case, for example, when
365:   the choice of iterative solver changes during the execution of the
366:   program, and the user's application is taking responsibility for
367:   choosing the appropriate method.  In other words, this routine is
368:   not for beginners.

370:   Level: intermediate

372: .keywords: KSP, set, method

374: .seealso: PCSetType(), KSPType

376: @*/
377: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetType(KSP ksp, KSPType type)
378: {
379:   PetscErrorCode ierr,(*r)(KSP);
380:   PetscTruth     match;


386:   PetscTypeCompare((PetscObject)ksp,type,&match);
387:   if (match) return(0);

389:   if (ksp->data) {
390:     /* destroy the old private KSP context */
391:     (*ksp->ops->destroy)(ksp);
392:     ksp->data = 0;
393:   }
394:   /* Get the function pointers for the iterative method requested */
395:   if (!KSPRegisterAllCalled) {KSPRegisterAll(PETSC_NULL);}
396:    PetscFListFind(ksp->comm,KSPList,type,(void (**)(void)) &r);
397:   if (!r) SETERRQ1(PETSC_ERR_ARG_UNKNOWN_TYPE,"Unknown KSP type given: %s",type);
398:   ksp->setupcalled = 0;
399:   (*r)(ksp);
400:   PetscObjectChangeTypeName((PetscObject)ksp,type);
401:   return(0);
402: }

406: /*@
407:    KSPRegisterDestroy - Frees the list of KSP methods that were
408:    registered by KSPRegisterDynamic().

410:    Not Collective

412:    Level: advanced

414: .keywords: KSP, register, destroy

416: .seealso: KSPRegisterDynamic(), KSPRegisterAll()
417: @*/
418: PetscErrorCode PETSCKSP_DLLEXPORT KSPRegisterDestroy(void)
419: {

423:   if (KSPList) {
424:     PetscFListDestroy(&KSPList);
425:     KSPList = 0;
426:   }
427:   KSPRegisterAllCalled = PETSC_FALSE;
428:   return(0);
429: }

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

436:    Not Collective

438:    Input Parameter:
439: .  ksp - Krylov context 

441:    Output Parameter:
442: .  name - name of KSP method 

444:    Level: intermediate

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

448: .seealso: KSPSetType()
449: @*/
450: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetType(KSP ksp,KSPType *type)
451: {
455:   *type = ksp->type_name;
456:   return(0);
457: }

461: /*@
462:    KSPSetFromOptions - Sets KSP options from the options database.
463:    This routine must be called before KSPSetUp() if the user is to be 
464:    allowed to set the Krylov type. 

466:    Collective on KSP

468:    Input Parameters:
469: .  ksp - the Krylov space context

471:    Options Database Keys:
472: +   -ksp_max_it - maximum number of linear iterations
473: .   -ksp_rtol rtol - relative tolerance used in default determination of convergence, i.e.
474:                 if residual norm decreases by this factor than convergence is declared
475: .   -ksp_atol abstol - absolute tolerance used in default convergence test, i.e. if residual 
476:                 norm is less than this then convergence is declared
477: .   -ksp_divtol tol - if residual norm increases by this factor than divergence is declared
478: .   -ksp_norm_type - none - skip norms used in convergence tests (useful only when not using 
479: $                       convergence test (say you always want to run with 5 iterations) to 
480: $                       save on communication overhead
481: $                    preconditioned - default for left preconditioning 
482: $                    unpreconditioned - see KSPSetNormType()
483: $                    natural - see KSPSetNormType()
484: .    -ksp_constant_null_space - assume the operator (matrix) has the constant vector in its null space
485: .    -ksp_test_null_space - tests the null space set with KSPSetNullSpace() to see if it truly is a null space
486: .   -ksp_knoll - compute initial guess by applying the preconditioner to the right hand side
487: .   -ksp_cancelmonitors - cancel all previous convergene monitor routines set
488: .   -ksp_monitor <optional filename> - print residual norm at each iteration
489: .   -ksp_xmonitor - plot residual norm at each iteration
490: .   -ksp_vecmonitor - plot solution at each iteration
491: -   -ksp_singmonitor - monitor extremem singular values at each iteration

493:    Notes:  
494:    To see all options, run your program with the -help option
495:    or consult the users manual.

497:    Level: beginner

499: .keywords: KSP, set, from, options, database

501: .seealso: 
502: @*/
503: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetFromOptions(KSP ksp)
504: {
506:   PetscInt       indx;
507:   char           type[256], monfilename[PETSC_MAX_PATH_LEN];
508:   const char     *stype[] = {"none","preconditioned","unpreconditioned","natural"};
509:   PetscViewer    monviewer;
510:   PetscTruth     flg;

514:   PCSetFromOptions(ksp->pc);

516:   if (!KSPRegisterAllCalled) {KSPRegisterAll(PETSC_NULL);}
517:   PetscOptionsBegin(ksp->comm,ksp->prefix,"Krylov Method (KSP) Options","KSP");
518:     PetscOptionsList("-ksp_type","Krylov method","KSPSetType",KSPList,(char*)(ksp->type_name?ksp->type_name:KSPGMRES),type,256,&flg);
519:     if (flg) {
520:       KSPSetType(ksp,type);
521:     }
522:     /*
523:       Set the type if it was never set.
524:     */
525:     if (!ksp->type_name) {
526:       KSPSetType(ksp,KSPGMRES);
527:     }

529:     PetscOptionsInt("-ksp_max_it","Maximum number of iterations","KSPSetTolerances",ksp->max_it,&ksp->max_it,PETSC_NULL);
530:     PetscOptionsReal("-ksp_rtol","Relative decrease in residual norm","KSPSetTolerances",ksp->rtol,&ksp->rtol,PETSC_NULL);
531:     PetscOptionsReal("-ksp_atol","Absolute value of residual norm","KSPSetTolerances",ksp->abstol,&ksp->abstol,PETSC_NULL);
532:     PetscOptionsReal("-ksp_divtol","Residual norm increase cause divergence","KSPSetTolerances",ksp->divtol,&ksp->divtol,PETSC_NULL);
533:     PetscOptionsTruth("-ksp_knoll","Use preconditioner applied to b for initial guess","KSPSetInitialGuessKnoll",ksp->guess_knoll,
534:                                   &ksp->guess_knoll,PETSC_NULL);

536:     PetscOptionsEList("-ksp_norm_type","KSP Norm type","KSPSetNormType",stype,4,"preconditioned",&indx,&flg);
537:     if (flg) {
538:       switch (indx) {
539:       case 0:
540:         KSPSetNormType(ksp,KSP_NO_NORM);
541:         KSPSetConvergenceTest(ksp,KSPSkipConverged,0);
542:         break;
543:       case 1:
544:         KSPSetNormType(ksp,KSP_PRECONDITIONED_NORM);
545:         break;
546:       case 2:
547:         KSPSetNormType(ksp,KSP_UNPRECONDITIONED_NORM);
548:         break;
549:       case 3:
550:         KSPSetNormType(ksp,KSP_NATURAL_NORM);
551:         break;
552:       }
553:     }

555:     PetscOptionsName("-ksp_diagonal_scale","Diagonal scale matrix before building preconditioner","KSPSetDiagonalScale",&flg);
556:     if (flg) {
557:       KSPSetDiagonalScale(ksp,PETSC_TRUE);
558:     }
559:     PetscOptionsName("-ksp_diagonal_scale_fix","Fix diagonaled scaled matrix after solve","KSPSetDiagonalScaleFix",&flg);
560:     if (flg) {
561:       KSPSetDiagonalScaleFix(ksp,PETSC_TRUE);
562:     }


565:     PetscOptionsName("-ksp_constant_null_space","Add constant null space to Krylov solver","KSPSetNullSpace",&flg);
566:     if (flg) {
567:       MatNullSpace nsp;

569:       MatNullSpaceCreate(ksp->comm,PETSC_TRUE,0,0,&nsp);
570:       KSPSetNullSpace(ksp,nsp);
571:       MatNullSpaceDestroy(nsp);
572:     }

574:     /* option is actually checked in KSPSetUp() */
575:     if (ksp->nullsp) {
576:       PetscOptionsName("-ksp_test_null_space","Is provided null space correct","None",&flg);
577:     }

579:     /*
580:       Prints reason for convergence or divergence of each linear solve
581:     */
582:     PetscOptionsName("-ksp_converged_reason","Print reason for converged or diverged","KSPSolve",&flg);
583:     if (flg) {
584:       ksp->printreason = PETSC_TRUE;
585:     }

587:     PetscOptionsName("-ksp_cancelmonitors","Remove any hardwired monitor routines","KSPClearMonitor",&flg);
588:     /* -----------------------------------------------------------------------*/
589:     /*
590:       Cancels all monitors hardwired into code before call to KSPSetFromOptions()
591:     */
592:     if (flg) {
593:       KSPClearMonitor(ksp);
594:     }
595:     /*
596:       Prints preconditioned residual norm at each iteration
597:     */
598:     PetscOptionsString("-ksp_monitor","Monitor preconditioned residual norm","KSPSetMonitor","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
599:     if (flg) {
600:       PetscViewerASCIIOpen(ksp->comm,monfilename,&monviewer);
601:       KSPSetMonitor(ksp,KSPDefaultMonitor,monviewer,(PetscErrorCode (*)(void*))PetscViewerDestroy);
602:     }
603:     /*
604:       Plots the vector solution 
605:     */
606:     PetscOptionsName("-ksp_vecmonitor","Monitor solution graphically","KSPSetMonitor",&flg);
607:     if (flg) {
608:       KSPSetMonitor(ksp,KSPVecViewMonitor,PETSC_NULL,PETSC_NULL);
609:     }
610:     /*
611:       Prints preconditioned and true residual norm at each iteration
612:     */
613:     PetscOptionsString("-ksp_truemonitor","Monitor preconditioned residual norm","KSPSetMonitor","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
614:     if (flg) {
615:       PetscViewerASCIIOpen(ksp->comm,monfilename,&monviewer);
616:       KSPSetMonitor(ksp,KSPTrueMonitor,monviewer,(PetscErrorCode (*)(void*))PetscViewerDestroy);
617:     }
618:     /*
619:       Prints extreme eigenvalue estimates at each iteration
620:     */
621:     PetscOptionsString("-ksp_singmonitor","Monitor singular values","KSPSetMonitor","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
622:     if (flg) {
623:       KSPSetComputeSingularValues(ksp,PETSC_TRUE);
624:       PetscViewerASCIIOpen(ksp->comm,monfilename,&monviewer);
625:       KSPSetMonitor(ksp,KSPSingularValueMonitor,monviewer,(PetscErrorCode (*)(void*))PetscViewerDestroy);
626:     }
627:     /*
628:       Prints preconditioned residual norm with fewer digits
629:     */
630:     PetscOptionsString("-ksp_smonitor","Monitor preconditioned residual norm with fewer digits","KSPSetMonitor","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
631:     if (flg) {
632:       PetscViewerASCIIOpen(ksp->comm,monfilename,&monviewer);
633:       KSPSetMonitor(ksp,KSPDefaultSMonitor,monviewer,(PetscErrorCode (*)(void*))PetscViewerDestroy);
634:     }
635:     /*
636:       Graphically plots preconditioned residual norm
637:     */
638:     PetscOptionsName("-ksp_xmonitor","Monitor graphically preconditioned residual norm","KSPSetMonitor",&flg);
639:     if (flg) {
640:       KSPSetMonitor(ksp,KSPLGMonitor,PETSC_NULL,PETSC_NULL);
641:     }
642:     /*
643:       Graphically plots preconditioned and true residual norm
644:     */
645:     PetscOptionsName("-ksp_xtruemonitor","Monitor graphically true residual norm","KSPSetMonitor",&flg);
646:     if (flg){
647:       KSPSetMonitor(ksp,KSPLGTrueMonitor,PETSC_NULL,PETSC_NULL);
648:     }

650:     /* -----------------------------------------------------------------------*/

652:     PetscOptionsTruthGroupBegin("-ksp_left_pc","Use left preconditioning","KSPSetPreconditionerSide",&flg);
653:     if (flg) { KSPSetPreconditionerSide(ksp,PC_LEFT); }
654:     PetscOptionsTruthGroup("-ksp_right_pc","Use right preconditioning","KSPSetPreconditionerSide",&flg);
655:     if (flg) { KSPSetPreconditionerSide(ksp,PC_RIGHT);}
656:     PetscOptionsTruthGroupEnd("-ksp_symmetric_pc","Use symmetric (factorized) preconditioning","KSPSetPreconditionerSide",&flg);
657:     if (flg) { KSPSetPreconditionerSide(ksp,PC_SYMMETRIC);}

659:     PetscOptionsName("-ksp_compute_singularvalues","Compute singular values of preconditioned operator","KSPSetComputeSingularValues",&flg);
660:     if (flg) { KSPSetComputeSingularValues(ksp,PETSC_TRUE); }
661:     PetscOptionsName("-ksp_compute_eigenvalues","Compute eigenvalues of preconditioned operator","KSPSetComputeSingularValues",&flg);
662:     if (flg) { KSPSetComputeSingularValues(ksp,PETSC_TRUE); }
663:     PetscOptionsName("-ksp_plot_eigenvalues","Scatter plot extreme eigenvalues","KSPSetComputeSingularValues",&flg);
664:     if (flg) { KSPSetComputeSingularValues(ksp,PETSC_TRUE); }

666:     if (ksp->ops->setfromoptions) {
667:       (*ksp->ops->setfromoptions)(ksp);
668:     }
669:     PetscOptionsName("-ksp_view","View linear solver parameters","KSPView",&flg);
670:   PetscOptionsEnd();
671:   return(0);
672: }

676: /*@C
677:   KSPRegister - See KSPRegisterDynamic()

679:   Level: advanced
680: @*/
681: PetscErrorCode PETSCKSP_DLLEXPORT KSPRegister(const char sname[],const char path[],const char name[],PetscErrorCode (*function)(KSP))
682: {
684:   char           fullname[PETSC_MAX_PATH_LEN];

687:   PetscFListConcat(path,name,fullname);
688:   PetscFListAdd(&KSPList,sname,fullname,(void (*)(void))function);
689:   return(0);
690: }

694: /*@
695:   KSPSetNullSpace - Sets the null space of the operator

697:   Collective on KSP

699:   Input Parameters:
700: +  ksp - the Krylov space object
701: -  nullsp - the null space of the operator

703:   Level: advanced

705: .seealso: KSPSetOperators(), MatNullSpaceCreate(), KSPGetNullSpace()
706: @*/
707: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetNullSpace(KSP ksp,MatNullSpace nullsp)
708: {

712:   if (ksp->nullsp) {
713:     MatNullSpaceDestroy(ksp->nullsp);
714:   }
715:   ksp->nullsp = nullsp;
716:   PetscObjectReference((PetscObject)ksp->nullsp);
717:   return(0);
718: }

722: /*@
723:   KSPGetNullSpace - Gets the null space of the operator

725:   Collective on KSP

727:   Input Parameters:
728: +  ksp - the Krylov space object
729: -  nullsp - the null space of the operator

731:   Level: advanced

733: .seealso: KSPSetOperators(), MatNullSpaceCreate(), KSPSetNullSpace()
734: @*/
735: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetNullSpace(KSP ksp,MatNullSpace *nullsp)
736: {
738:   *nullsp = ksp->nullsp;
739:   return(0);
740: }