Actual source code: itfunc.c

  1: #define PETSCKSP_DLL

  3: /*
  4:       Interface KSP routines that the user calls.
  5: */

 7:  #include include/private/kspimpl.h

 11: /*@
 12:    KSPComputeExtremeSingularValues - Computes the extreme singular values
 13:    for the preconditioned operator. Called after or during KSPSolve().

 15:    Not Collective

 17:    Input Parameter:
 18: .  ksp - iterative context obtained from KSPCreate()

 20:    Output Parameters:
 21: .  emin, emax - extreme singular values

 23:    Notes:
 24:    One must call KSPSetComputeSingularValues() before calling KSPSetUp() 
 25:    (or use the option -ksp_compute_eigenvalues) in order for this routine to work correctly.

 27:    Many users may just want to use the monitoring routine
 28:    KSPMonitorSingularValue() (which can be set with option -ksp_monitor_singular_value)
 29:    to print the extreme singular values at each iteration of the linear solve.

 31:    Level: advanced

 33: .keywords: KSP, compute, extreme, singular, values

 35: .seealso: KSPSetComputeSingularValues(), KSPMonitorSingularValue(), KSPComputeEigenvalues()
 36: @*/
 37: PetscErrorCode  KSPComputeExtremeSingularValues(KSP ksp,PetscReal *emax,PetscReal *emin)
 38: {

 45:   if (!ksp->calc_sings) {
 46:     SETERRQ(4,"Singular values not requested before KSPSetUp()");
 47:   }

 49:   if (ksp->ops->computeextremesingularvalues) {
 50:     (*ksp->ops->computeextremesingularvalues)(ksp,emax,emin);
 51:   } else {
 52:     *emin = -1.0;
 53:     *emax = -1.0;
 54:   }
 55:   return(0);
 56: }

 60: /*@
 61:    KSPComputeEigenvalues - Computes the extreme eigenvalues for the
 62:    preconditioned operator. Called after or during KSPSolve().

 64:    Not Collective

 66:    Input Parameter:
 67: +  ksp - iterative context obtained from KSPCreate()
 68: -  n - size of arrays r and c. The number of eigenvalues computed (neig) will, in 
 69:        general, be less than this.

 71:    Output Parameters:
 72: +  r - real part of computed eigenvalues
 73: .  c - complex part of computed eigenvalues
 74: -  neig - number of eigenvalues computed (will be less than or equal to n)

 76:    Options Database Keys:
 77: +  -ksp_compute_eigenvalues - Prints eigenvalues to stdout
 78: -  -ksp_plot_eigenvalues - Plots eigenvalues in an x-window display

 80:    Notes:
 81:    The number of eigenvalues estimated depends on the size of the Krylov space
 82:    generated during the KSPSolve() ; for example, with 
 83:    CG it corresponds to the number of CG iterations, for GMRES it is the number 
 84:    of GMRES iterations SINCE the last restart. Any extra space in r[] and c[]
 85:    will be ignored.

 87:    KSPComputeEigenvalues() does not usually provide accurate estimates; it is
 88:    intended only for assistance in understanding the convergence of iterative 
 89:    methods, not for eigenanalysis. 

 91:    One must call KSPSetComputeEigenvalues() before calling KSPSetUp() 
 92:    in order for this routine to work correctly.

 94:    Many users may just want to use the monitoring routine
 95:    KSPMonitorSingularValue() (which can be set with option -ksp_monitor_singular_value)
 96:    to print the singular values at each iteration of the linear solve.

 98:    Level: advanced

100: .keywords: KSP, compute, extreme, singular, values

102: .seealso: KSPSetComputeSingularValues(), KSPMonitorSingularValue(), KSPComputeExtremeSingularValues()
103: @*/
104: PetscErrorCode  KSPComputeEigenvalues(KSP ksp,PetscInt n,PetscReal *r,PetscReal *c,PetscInt *neig)
105: {

113:   if (!ksp->calc_sings) {
114:     SETERRQ(4,"Eigenvalues not requested before KSPSetUp()");
115:   }

117:   if (ksp->ops->computeeigenvalues) {
118:     (*ksp->ops->computeeigenvalues)(ksp,n,r,c,neig);
119:   } else {
120:     *neig = 0;
121:   }
122:   return(0);
123: }

127: /*@
128:    KSPSetUpOnBlocks - Sets up the preconditioner for each block in
129:    the block Jacobi, block Gauss-Seidel, and overlapping Schwarz 
130:    methods.

132:    Collective on KSP

134:    Input Parameter:
135: .  ksp - the KSP context

137:    Notes:
138:    KSPSetUpOnBlocks() is a routine that the user can optinally call for
139:    more precise profiling (via -log_summary) of the setup phase for these
140:    block preconditioners.  If the user does not call KSPSetUpOnBlocks(),
141:    it will automatically be called from within KSPSolve().
142:    
143:    Calling KSPSetUpOnBlocks() is the same as calling PCSetUpOnBlocks()
144:    on the PC context within the KSP context.

146:    Level: advanced

148: .keywords: KSP, setup, blocks

150: .seealso: PCSetUpOnBlocks(), KSPSetUp(), PCSetUp()
151: @*/
152: PetscErrorCode  KSPSetUpOnBlocks(KSP ksp)
153: {

158:   PCSetUpOnBlocks(ksp->pc);
159:   return(0);
160: }

164: /*@
165:    KSPSetUp - Sets up the internal data structures for the
166:    later use of an iterative solver.

168:    Collective on KSP

170:    Input Parameter:
171: .  ksp   - iterative context obtained from KSPCreate()

173:    Level: developer

175: .keywords: KSP, setup

177: .seealso: KSPCreate(), KSPSolve(), KSPDestroy()
178: @*/
179: PetscErrorCode  KSPSetUp(KSP ksp)
180: {


186:   /* reset the convergence flag from the previous solves */
187:   ksp->reason = KSP_CONVERGED_ITERATING;

189:   if (!ksp->type_name){
190:     KSPSetType(ksp,KSPGMRES);
191:   }

193:   if (ksp->setupcalled == 2) return(0);


197:   if (!ksp->setupcalled) {
198:     (*ksp->ops->setup)(ksp);
199:   }

201:   /* scale the matrix if requested */
202:   if (ksp->dscale) {
203:     Mat mat,pmat;
204:     PCGetOperators(ksp->pc,&mat,&pmat,PETSC_NULL);
205:     if (mat == pmat) {
206:       PetscScalar  *xx;
207:       PetscInt     i,n;
208:       PetscTruth   zeroflag = PETSC_FALSE;

210:       if (!ksp->diagonal) { /* allocate vector to hold diagonal */
211:         MatGetVecs(pmat,&ksp->diagonal,0);
212:       }
213:       MatGetDiagonal(mat,ksp->diagonal);
214:       VecGetLocalSize(ksp->diagonal,&n);
215:       VecGetArray(ksp->diagonal,&xx);
216:       for (i=0; i<n; i++) {
217:         if (xx[i] != 0.0) xx[i] = 1.0/sqrt(PetscAbsScalar(xx[i]));
218:         else {
219:           xx[i]     = 1.0;
220:           zeroflag  = PETSC_TRUE;
221:         }
222:       }
223:       VecRestoreArray(ksp->diagonal,&xx);
224:       if (zeroflag) {
225:         PetscInfo(ksp,"Zero detected in diagonal of matrix, using 1 at those locations\n");
226:       }
227:       MatDiagonalScale(mat,ksp->diagonal,ksp->diagonal);
228:       ksp->dscalefix2 = PETSC_FALSE;
229:     } else {
230:       SETERRQ(PETSC_ERR_SUP,"No support for diagonal scaling of linear system if preconditioner matrix not actual matrix");
231:     }
232:   }
234:   PCSetUp(ksp->pc);
235:   if (ksp->nullsp) {
236:     PetscTruth test;
237:     PetscOptionsHasName(ksp->prefix,"-ksp_test_null_space",&test);
238:     if (test) {
239:       Mat mat;
240:       PCGetOperators(ksp->pc,&mat,PETSC_NULL,PETSC_NULL);
241:       MatNullSpaceTest(ksp->nullsp,mat);
242:     }
243:   }
244:   ksp->setupcalled = 2;
245:   return(0);
246: }

250: /*@
251:    KSPSolve - Solves linear system.

253:    Collective on KSP

255:    Parameter:
256: +  ksp - iterative context obtained from KSPCreate()
257: .  b - the right hand side vector
258: -  x - the solution  (this may be the same vector as b, then b will be overwritten with answer)

260:    Options Database Keys:
261: +  -ksp_compute_eigenvalues - compute preconditioned operators eigenvalues
262: .  -ksp_plot_eigenvalues - plot the computed eigenvalues in an X-window
263: .  -ksp_compute_eigenvalues_explicitly - compute the eigenvalues by forming the dense operator and useing LAPACK
264: .  -ksp_plot_eigenvalues_explicitly - plot the explicitly computing eigenvalues
265: .  -ksp_view_binary - save matrix and right hand side that define linear system to the default binary viewer (can be
266:                                 read later with src/ksp/examples/tutorials/ex10.c for testing solvers)
267: .  -ksp_converged_reason - print reason for converged or diverged, also prints number of iterations
268: .  -ksp_final_residual - print 2-norm of true linear system residual at the end of the solution process
269: -  -ksp_view - print the ksp data structure at the end of the system solution

271:    Notes:

273:    The operator is specified with PCSetOperators().

275:    Call KSPGetConvergedReason() to determine if the solver converged or failed and 
276:    why. The number of iterations can be obtained from KSPGetIterationNumber().
277:    
278:    If using a direct method (e.g., via the KSP solver
279:    KSPPREONLY and a preconditioner such as PCLU/PCILU),
280:    then its=1.  See KSPSetTolerances() and KSPDefaultConverged()
281:    for more details.

283:    Understanding Convergence:
284:    The routines KSPMonitorSet(), KSPComputeEigenvalues(), and
285:    KSPComputeEigenvaluesExplicitly() provide information on additional
286:    options to monitor convergence and print eigenvalue information.

288:    Level: beginner

290: .keywords: KSP, solve, linear system

292: .seealso: KSPCreate(), KSPSetUp(), KSPDestroy(), KSPSetTolerances(), KSPDefaultConverged(),
293:           KSPSolveTranspose(), KSPGetIterationNumber()
294: @*/
295: PetscErrorCode  KSPSolve(KSP ksp,Vec b,Vec x)
296: {
298:   PetscMPIInt    rank;
299:   PetscTruth     flag1,flag2,viewed=PETSC_FALSE,flg,inXisinB=PETSC_FALSE;
300:   char           view[10];
301:   char           filename[PETSC_MAX_PATH_LEN];
302:   PetscViewer    viewer;
303: 


310:   if (x == b) {
311:     VecDuplicate(b,&x);
312:     inXisinB = PETSC_TRUE;
313:   }
314:   PetscObjectReference((PetscObject)b);
315:   PetscObjectReference((PetscObject)x);
316:   if (ksp->vec_rhs) {VecDestroy(ksp->vec_rhs);}
317:   if (ksp->vec_sol) {VecDestroy(ksp->vec_sol);}
318:   ksp->vec_rhs = b;
319:   ksp->vec_sol = x;

321:   PetscOptionsHasName(ksp->prefix,"-ksp_view_binary",&flg);
322:   if (flg) {
323:     Mat mat;
324:     PCGetOperators(ksp->pc,&mat,PETSC_NULL,PETSC_NULL);
325:     MatView(mat,PETSC_VIEWER_BINARY_(ksp->comm));
326:     VecView(ksp->vec_rhs,PETSC_VIEWER_BINARY_(ksp->comm));
327:   }


331:   /* reset the residual history list if requested */
332:   if (ksp->res_hist_reset) ksp->res_hist_len = 0;

334:   PetscOptionsGetString(ksp->prefix,"-ksp_view",view,10,&flg);
335:   if (flg) {
336:     PetscStrcmp(view,"before",&viewed);
337:     if (viewed){
338:       PetscViewer viewer;
339:       PetscViewerASCIIGetStdout(ksp->comm,&viewer);
340:       KSPView(ksp,viewer);
341:     }
342:   }

344:   ksp->transpose_solve = PETSC_FALSE;
345: 
346:   /* KSPSetUp() scales the matrix if needed */
347:   KSPSetUp(ksp);
348:   KSPSetUpOnBlocks(ksp);

350:   /* diagonal scale RHS if called for */
351:   if (ksp->dscale) {
352:     VecPointwiseMult(ksp->vec_rhs,ksp->vec_rhs,ksp->diagonal);
353:     /* second time in, but matrix was scaled back to original */
354:     if (ksp->dscalefix && ksp->dscalefix2) {
355:       Mat mat;

357:       PCGetOperators(ksp->pc,&mat,PETSC_NULL,PETSC_NULL);
358:       MatDiagonalScale(mat,ksp->diagonal,ksp->diagonal);
359:     }

361:     /*  scale initial guess */
362:     if (!ksp->guess_zero) {
363:       if (!ksp->truediagonal) {
364:         VecDuplicate(ksp->diagonal,&ksp->truediagonal);
365:         VecCopy(ksp->diagonal,ksp->truediagonal);
366:         VecReciprocal(ksp->truediagonal);
367:       }
368:       VecPointwiseMult(ksp->vec_sol,ksp->vec_sol,ksp->truediagonal);
369:     }
370:   }
371:   PCPreSolve(ksp->pc,ksp);

373:   if (ksp->guess_zero) { VecSet(ksp->vec_sol,0.0);}
374:   if (ksp->guess_knoll) {
375:     PCApply(ksp->pc,ksp->vec_rhs,ksp->vec_sol);
376:     KSP_RemoveNullSpace(ksp,ksp->vec_sol);
377:     ksp->guess_zero = PETSC_FALSE;
378:   }
379:   (*ksp->ops->solve)(ksp);
380:   if (!ksp->reason) {
381:     SETERRQ(PETSC_ERR_PLIB,"Internal error, solver returned without setting converged reason");
382:   }
383:   if (ksp->printreason) {
384:     if (ksp->reason > 0) {
385:       PetscPrintf(ksp->comm,"Linear solve converged due to %s iterations %D\n",KSPConvergedReasons[ksp->reason],ksp->its);
386:     } else {
387:       PetscPrintf(ksp->comm,"Linear solve did not converge due to %s iterations %D\n",KSPConvergedReasons[ksp->reason],ksp->its);
388:     }
389:   }
390:   PCPostSolve(ksp->pc,ksp);

392:   /* diagonal scale solution if called for */
393:   if (ksp->dscale) {
394:     VecPointwiseMult(ksp->vec_sol,ksp->vec_sol,ksp->diagonal);
395:     /* unscale right hand side and matrix */
396:     if (ksp->dscalefix) {
397:       Mat mat;

399:       VecReciprocal(ksp->diagonal);
400:       VecPointwiseMult(ksp->vec_rhs,ksp->vec_rhs,ksp->diagonal);
401:       PCGetOperators(ksp->pc,&mat,PETSC_NULL,PETSC_NULL);
402:       MatDiagonalScale(mat,ksp->diagonal,ksp->diagonal);
403:       VecReciprocal(ksp->diagonal);
404:       ksp->dscalefix2 = PETSC_TRUE;
405:     }
406:   }

409:   MPI_Comm_rank(ksp->comm,&rank);

411:   PetscOptionsHasName(ksp->prefix,"-ksp_compute_eigenvalues",&flag1);
412:   PetscOptionsHasName(ksp->prefix,"-ksp_plot_eigenvalues",&flag2);
413:   if (flag1 || flag2) {
414:     PetscInt   nits,n,i,neig;
415:     PetscReal *r,*c;
416: 
417:     KSPGetIterationNumber(ksp,&nits);
418:     n = nits+2;

420:     if (!n) {
421:       PetscPrintf(ksp->comm,"Zero iterations in solver, cannot approximate any eigenvalues\n");
422:     } else {
423:       PetscMalloc(2*n*sizeof(PetscReal),&r);
424:       c = r + n;
425:       KSPComputeEigenvalues(ksp,n,r,c,&neig);
426:       if (flag1) {
427:         PetscPrintf(ksp->comm,"Iteratively computed eigenvalues\n");
428:         for (i=0; i<neig; i++) {
429:           if (c[i] >= 0.0) {PetscPrintf(ksp->comm,"%G + %Gi\n",r[i],c[i]);}
430:           else             {PetscPrintf(ksp->comm,"%G - %Gi\n",r[i],-c[i]);}
431:         }
432:       }
433:       if (flag2 && !rank) {
434:         PetscDraw   draw;
435:         PetscDrawSP drawsp;

437:         PetscViewerDrawOpen(PETSC_COMM_SELF,0,"Iteratively Computed Eigenvalues",PETSC_DECIDE,PETSC_DECIDE,300,300,&viewer);
438:         PetscViewerDrawGetDraw(viewer,0,&draw);
439:         PetscDrawSPCreate(draw,1,&drawsp);
440:         for (i=0; i<neig; i++) {
441:           PetscDrawSPAddPoint(drawsp,r+i,c+i);
442:         }
443:         PetscDrawSPDraw(drawsp);
444:         PetscDrawSPDestroy(drawsp);
445:         PetscViewerDestroy(viewer);
446:       }
447:       PetscFree(r);
448:     }
449:   }

451:   PetscOptionsHasName(ksp->prefix,"-ksp_compute_eigenvalues_explicitly",&flag1);
452:   PetscOptionsHasName(ksp->prefix,"-ksp_plot_eigenvalues_explicitly",&flag2);
453:   if (flag1 || flag2) {
454:     PetscInt  n,i;
455:     PetscReal *r,*c;
456:     VecGetSize(ksp->vec_sol,&n);
457:     PetscMalloc(2*n*sizeof(PetscReal),&r);
458:     c = r + n;
459:     KSPComputeEigenvaluesExplicitly(ksp,n,r,c);
460:     if (flag1) {
461:       PetscPrintf(ksp->comm,"Explicitly computed eigenvalues\n");
462:       for (i=0; i<n; i++) {
463:         if (c[i] >= 0.0) {PetscPrintf(ksp->comm,"%G + %Gi\n",r[i],c[i]);}
464:         else             {PetscPrintf(ksp->comm,"%G - %Gi\n",r[i],-c[i]);}
465:       }
466:     }
467:     if (flag2 && !rank) {
468:       PetscDraw   draw;
469:       PetscDrawSP drawsp;

471:       PetscViewerDrawOpen(PETSC_COMM_SELF,0,"Explicitly Computed Eigenvalues",0,320,300,300,&viewer);
472:       PetscViewerDrawGetDraw(viewer,0,&draw);
473:       PetscDrawSPCreate(draw,1,&drawsp);
474:       for (i=0; i<n; i++) {
475:         PetscDrawSPAddPoint(drawsp,r+i,c+i);
476:       }
477:       PetscDrawSPDraw(drawsp);
478:       PetscDrawSPDestroy(drawsp);
479:       PetscViewerDestroy(viewer);
480:     }
481:     PetscFree(r);
482:   }

484:   PetscOptionsHasName(ksp->prefix,"-ksp_view_operator",&flag2);
485:   if (flag2) {
486:     Mat         A,B;
487:     PetscViewer viewer;

489:     PCGetOperators(ksp->pc,&A,PETSC_NULL,PETSC_NULL);
490:     MatComputeExplicitOperator(A,&B);
491:     PetscViewerASCIIGetStdout(ksp->comm,&viewer);
492:     PetscViewerPushFormat(viewer,PETSC_VIEWER_ASCII_MATLAB);
493:     MatView(B,viewer);
494:     PetscViewerPopFormat(viewer);
495:     MatDestroy(B);
496:   }
497:   PetscOptionsHasName(ksp->prefix,"-ksp_view_operator_binary",&flag2);
498:   if (flag2) {
499:     Mat A,B;
500:     PCGetOperators(ksp->pc,&A,PETSC_NULL,PETSC_NULL);
501:     MatComputeExplicitOperator(A,&B);
502:     MatView(B,PETSC_VIEWER_BINARY_(ksp->comm));
503:     MatDestroy(B);
504:   }
505:   PetscOptionsHasName(ksp->prefix,"-ksp_view_preconditioned_operator_binary",&flag2);
506:   if (flag2) {
507:     Mat B;
508:     KSPComputeExplicitOperator(ksp,&B);
509:     MatView(B,PETSC_VIEWER_BINARY_(ksp->comm));
510:     MatDestroy(B);
511:   }
512:   if (!viewed) {
513:     PetscOptionsGetString(ksp->prefix,"-ksp_view",filename,PETSC_MAX_PATH_LEN,&flg);
514:     if (flg && !PetscPreLoadingOn) {
515:       PetscViewerASCIIOpen(ksp->comm,filename,&viewer);
516:       KSPView(ksp,viewer);
517:       PetscViewerDestroy(viewer);
518:     }
519:   }
520:   PetscOptionsHasName(ksp->prefix,"-ksp_final_residual",&flg);
521:   if (flg) {
522:     Mat         A;
523:     Vec         t;
524:     PetscReal   norm;
525:     if (ksp->dscale && !ksp->dscalefix) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot compute final scale with -ksp_diagonal_scale except also with -ksp_diagonal_scale_fix");
526:     PCGetOperators(ksp->pc,&A,0,0);
527:     VecDuplicate(ksp->vec_sol,&t);
528:     KSP_MatMult(ksp,A,ksp->vec_sol,t);
529:     VecWAXPY(t,-1.0,t,ksp->vec_rhs);
530:     VecNorm(t,NORM_2,&norm);
531:     VecDestroy(t);
532:     PetscPrintf(ksp->comm,"KSP final norm of residual %G\n",norm);
533:   }
534:   if (inXisinB) {
535:     VecCopy(x,b);
536:     VecDestroy(x);
537:   }
538:   return(0);
539: }

543: /*@
544:    KSPSolveTranspose - Solves the transpose of a linear system. Usually
545:    accessed through KSPSolveTranspose().

547:    Collective on KSP

549:    Input Parameter:
550: +  ksp - iterative context obtained from KSPCreate()
551: .  b - right hand side vector
552: -  x - solution vector

554:    Note:
555:    Currently only supported by KSPType of KSPPREONLY. This routine is usally 
556:    only used internally by the BiCG solver on the subblocks in BJacobi and ASM.

558:    Level: developer

560: .keywords: KSP, solve, linear system

562: .seealso: KSPCreate(), KSPSetUp(), KSPDestroy(), KSPSetTolerances(), KSPDefaultConverged(),
563:           KSPSolve()
564: @*/
565: PetscErrorCode  KSPSolveTranspose(KSP ksp,Vec b,Vec x)
566: {
568:   PetscTruth     inXisinB=PETSC_FALSE;

574:   if (x == b) {
575:     VecDuplicate(b,&x);
576:     inXisinB = PETSC_TRUE;
577:   }
578:   PetscObjectReference((PetscObject)b);
579:   PetscObjectReference((PetscObject)x);
580:   if (ksp->vec_rhs) {VecDestroy(ksp->vec_rhs);}
581:   if (ksp->vec_sol) {VecDestroy(ksp->vec_sol);}
582:   ksp->vec_rhs = b;
583:   ksp->vec_sol = x;
584:   ksp->transpose_solve = PETSC_TRUE;
585:   KSPSetUp(ksp);
586:   if (ksp->guess_zero) { VecSet(ksp->vec_sol,0.0);}
587:   (*ksp->ops->solve)(ksp);
588:   if (inXisinB) {
589:     VecCopy(x,b);
590:     VecDestroy(x);
591:   }
592:   return(0);
593: }

597: /*@
598:    KSPDestroy - Destroys KSP context.

600:    Collective on KSP

602:    Input Parameter:
603: .  ksp - iterative context obtained from KSPCreate()

605:    Level: beginner

607: .keywords: KSP, destroy

609: .seealso: KSPCreate(), KSPSetUp(), KSPSolve()
610: @*/
611: PetscErrorCode  KSPDestroy(KSP ksp)
612: {

617:   if (--ksp->refct > 0) return(0);

619:   /* if memory was published with AMS then destroy it */
620:   PetscObjectDepublish(ksp);

622:   if (ksp->ops->destroy) {
623:     (*ksp->ops->destroy)(ksp);
624:   }
625:   PetscFree(ksp->res_hist_alloc);
626:   KSPMonitorCancel(ksp);
627:   PCDestroy(ksp->pc);
628:   if (ksp->vec_rhs) {VecDestroy(ksp->vec_rhs);}
629:   if (ksp->vec_sol) {VecDestroy(ksp->vec_sol);}
630:   if (ksp->diagonal) {VecDestroy(ksp->diagonal);}
631:   if (ksp->truediagonal) {VecDestroy(ksp->truediagonal);}
632:   if (ksp->nullsp) {MatNullSpaceDestroy(ksp->nullsp);}
633:   PetscHeaderDestroy(ksp);
634:   return(0);
635: }

639: /*@
640:     KSPSetPreconditionerSide - Sets the preconditioning side.

642:     Collective on KSP

644:     Input Parameter:
645: .   ksp - iterative context obtained from KSPCreate()

647:     Output Parameter:
648: .   side - the preconditioning side, where side is one of
649: .vb
650:       PC_LEFT - left preconditioning (default)
651:       PC_RIGHT - right preconditioning
652:       PC_SYMMETRIC - symmetric preconditioning
653: .ve

655:     Options Database Keys:
656: +   -ksp_left_pc - Sets left preconditioning
657: .   -ksp_right_pc - Sets right preconditioning
658: -   -ksp_symmetric_pc - Sets symmetric preconditioning

660:     Notes:
661:     Left preconditioning is used by default.  Symmetric preconditioning is
662:     currently available only for the KSPQCG method. Note, however, that
663:     symmetric preconditioning can be emulated by using either right or left
664:     preconditioning and a pre or post processing step.

666:     Level: intermediate

668: .keywords: KSP, set, right, left, symmetric, side, preconditioner, flag

670: .seealso: KSPGetPreconditionerSide()
671: @*/
672: PetscErrorCode  KSPSetPreconditionerSide(KSP ksp,PCSide side)
673: {
676:   ksp->pc_side = side;
677:   return(0);
678: }

682: /*@
683:     KSPGetPreconditionerSide - Gets the preconditioning side.

685:     Not Collective

687:     Input Parameter:
688: .   ksp - iterative context obtained from KSPCreate()

690:     Output Parameter:
691: .   side - the preconditioning side, where side is one of
692: .vb
693:       PC_LEFT - left preconditioning (default)
694:       PC_RIGHT - right preconditioning
695:       PC_SYMMETRIC - symmetric preconditioning
696: .ve

698:     Level: intermediate

700: .keywords: KSP, get, right, left, symmetric, side, preconditioner, flag

702: .seealso: KSPSetPreconditionerSide()
703: @*/
704: PetscErrorCode  KSPGetPreconditionerSide(KSP ksp,PCSide *side)
705: {
709:   *side = ksp->pc_side;
710:   return(0);
711: }

715: /*@
716:    KSPGetTolerances - Gets the relative, absolute, divergence, and maximum
717:    iteration tolerances used by the default KSP convergence tests. 

719:    Not Collective

721:    Input Parameter:
722: .  ksp - the Krylov subspace context
723:   
724:    Output Parameters:
725: +  rtol - the relative convergence tolerance
726: .  abstol - the absolute convergence tolerance
727: .  dtol - the divergence tolerance
728: -  maxits - maximum number of iterations

730:    Notes:
731:    The user can specify PETSC_NULL for any parameter that is not needed.

733:    Level: intermediate

735: .keywords: KSP, get, tolerance, absolute, relative, divergence, convergence,
736:            maximum, iterations

738: .seealso: KSPSetTolerances()
739: @*/
740: PetscErrorCode  KSPGetTolerances(KSP ksp,PetscReal *rtol,PetscReal *abstol,PetscReal *dtol,PetscInt *maxits)
741: {
744:   if (abstol)   *abstol   = ksp->abstol;
745:   if (rtol)   *rtol   = ksp->rtol;
746:   if (dtol)   *dtol   = ksp->divtol;
747:   if (maxits) *maxits = ksp->max_it;
748:   return(0);
749: }

753: /*@
754:    KSPSetTolerances - Sets the relative, absolute, divergence, and maximum
755:    iteration tolerances used by the default KSP convergence testers. 

757:    Collective on KSP

759:    Input Parameters:
760: +  ksp - the Krylov subspace context
761: .  rtol - the relative convergence tolerance
762:    (relative decrease in the residual norm)
763: .  abstol - the absolute convergence tolerance 
764:    (absolute size of the residual norm)
765: .  dtol - the divergence tolerance
766:    (amount residual can increase before KSPDefaultConverged()
767:    concludes that the method is diverging)
768: -  maxits - maximum number of iterations to use

770:    Options Database Keys:
771: +  -ksp_atol <abstol> - Sets abstol
772: .  -ksp_rtol <rtol> - Sets rtol
773: .  -ksp_divtol <dtol> - Sets dtol
774: -  -ksp_max_it <maxits> - Sets maxits

776:    Notes:
777:    Use PETSC_DEFAULT to retain the default value of any of the tolerances.

779:    See KSPDefaultConverged() for details on the use of these parameters
780:    in the default convergence test.  See also KSPSetConvergenceTest() 
781:    for setting user-defined stopping criteria.

783:    Level: intermediate

785: .keywords: KSP, set, tolerance, absolute, relative, divergence, 
786:            convergence, maximum, iterations

788: .seealso: KSPGetTolerances(), KSPDefaultConverged(), KSPSetConvergenceTest()
789: @*/
790: PetscErrorCode  KSPSetTolerances(KSP ksp,PetscReal rtol,PetscReal abstol,PetscReal dtol,PetscInt maxits)
791: {
794:   if (abstol != PETSC_DEFAULT)   ksp->abstol   = abstol;
795:   if (rtol != PETSC_DEFAULT)   ksp->rtol   = rtol;
796:   if (dtol != PETSC_DEFAULT)   ksp->divtol = dtol;
797:   if (maxits != PETSC_DEFAULT) ksp->max_it = maxits;
798:   return(0);
799: }

803: /*@
804:    KSPSetInitialGuessNonzero - Tells the iterative solver that the 
805:    initial guess is nonzero; otherwise KSP assumes the initial guess
806:    is to be zero (and thus zeros it out before solving).

808:    Collective on KSP

810:    Input Parameters:
811: +  ksp - iterative context obtained from KSPCreate()
812: -  flg - PETSC_TRUE indicates the guess is non-zero, PETSC_FALSE indicates the guess is zero

814:    Level: beginner

816:    Notes:
817:     If this is not called the X vector is zeroed in the call to KSPSolve().

819: .keywords: KSP, set, initial guess, nonzero

821: .seealso: KSPGetInitialGuessNonzero(), KSPSetInitialGuessKnoll(), KSPGetInitialGuessKnoll()
822: @*/
823: PetscErrorCode  KSPSetInitialGuessNonzero(KSP ksp,PetscTruth flg)
824: {
826:   ksp->guess_zero   = (PetscTruth)!(int)flg;
827:   return(0);
828: }

832: /*@
833:    KSPGetInitialGuessNonzero - Determines whether the KSP solver is using
834:    a zero initial guess.

836:    Not Collective

838:    Input Parameter:
839: .  ksp - iterative context obtained from KSPCreate()

841:    Output Parameter:
842: .  flag - PETSC_TRUE if guess is nonzero, else PETSC_FALSE

844:    Level: intermediate

846: .keywords: KSP, set, initial guess, nonzero

848: .seealso: KSPSetInitialGuessNonzero(), KSPSetInitialGuessKnoll(), KSPGetInitialGuessKnoll()
849: @*/
850: PetscErrorCode  KSPGetInitialGuessNonzero(KSP ksp,PetscTruth *flag)
851: {
853:   if (ksp->guess_zero) *flag = PETSC_FALSE;
854:   else                 *flag = PETSC_TRUE;
855:   return(0);
856: }

860: /*@
861:    KSPSetInitialGuessKnoll - Tells the iterative solver to use PCApply(pc,b,..) to compute the initial guess (The Knoll trick)

863:    Collective on KSP

865:    Input Parameters:
866: +  ksp - iterative context obtained from KSPCreate()
867: -  flg - PETSC_TRUE or PETSC_FALSE

869:    Level: advanced


872: .keywords: KSP, set, initial guess, nonzero

874: .seealso: KSPGetInitialGuessKnoll(), KSPSetInitialGuessNonzero(), KSPGetInitialGuessNonzero()
875: @*/
876: PetscErrorCode  KSPSetInitialGuessKnoll(KSP ksp,PetscTruth flg)
877: {
879:   ksp->guess_knoll   = flg;
880:   return(0);
881: }

885: /*@
886:    KSPGetInitialGuessKnoll - Determines whether the KSP solver is using the Knoll trick (using PCApply(pc,b,...) to compute
887:      the initial guess

889:    Not Collective

891:    Input Parameter:
892: .  ksp - iterative context obtained from KSPCreate()

894:    Output Parameter:
895: .  flag - PETSC_TRUE if using Knoll trick, else PETSC_FALSE

897:    Level: advanced

899: .keywords: KSP, set, initial guess, nonzero

901: .seealso: KSPSetInitialGuessKnoll(), KSPSetInitialGuessNonzero(), KSPGetInitialGuessNonzero()
902: @*/
903: PetscErrorCode  KSPGetInitialGuessKnoll(KSP ksp,PetscTruth *flag)
904: {
906:   *flag = ksp->guess_knoll;
907:   return(0);
908: }

912: /*@
913:    KSPGetComputeSingularValues - Gets the flag indicating whether the extreme singular 
914:    values will be calculated via a Lanczos or Arnoldi process as the linear 
915:    system is solved.

917:    Collective on KSP

919:    Input Parameter:
920: .  ksp - iterative context obtained from KSPCreate()

922:    Output Parameter:
923: .  flg - PETSC_TRUE or PETSC_FALSE

925:    Options Database Key:
926: .  -ksp_monitor_singular_value - Activates KSPSetComputeSingularValues()

928:    Notes:
929:    Currently this option is not valid for all iterative methods.

931:    Many users may just want to use the monitoring routine
932:    KSPMonitorSingularValue() (which can be set with option -ksp_monitor_singular_value)
933:    to print the singular values at each iteration of the linear solve.

935:    Level: advanced

937: .keywords: KSP, set, compute, singular values

939: .seealso: KSPComputeExtremeSingularValues(), KSPMonitorSingularValue()
940: @*/
941: PetscErrorCode  KSPGetComputeSingularValues(KSP ksp,PetscTruth *flg)
942: {
946:   *flg = ksp->calc_sings;
947:   return(0);
948: }

952: /*@
953:    KSPSetComputeSingularValues - Sets a flag so that the extreme singular 
954:    values will be calculated via a Lanczos or Arnoldi process as the linear 
955:    system is solved.

957:    Collective on KSP

959:    Input Parameters:
960: +  ksp - iterative context obtained from KSPCreate()
961: -  flg - PETSC_TRUE or PETSC_FALSE

963:    Options Database Key:
964: .  -ksp_monitor_singular_value - Activates KSPSetComputeSingularValues()

966:    Notes:
967:    Currently this option is not valid for all iterative methods.

969:    Many users may just want to use the monitoring routine
970:    KSPMonitorSingularValue() (which can be set with option -ksp_monitor_singular_value)
971:    to print the singular values at each iteration of the linear solve.

973:    Level: advanced

975: .keywords: KSP, set, compute, singular values

977: .seealso: KSPComputeExtremeSingularValues(), KSPMonitorSingularValue()
978: @*/
979: PetscErrorCode  KSPSetComputeSingularValues(KSP ksp,PetscTruth flg)
980: {
983:   ksp->calc_sings  = flg;
984:   return(0);
985: }

989: /*@
990:    KSPGetComputeEigenvalues - Gets the flag indicating that the extreme eigenvalues
991:    values will be calculated via a Lanczos or Arnoldi process as the linear 
992:    system is solved.

994:    Collective on KSP

996:    Input Parameter:
997: .  ksp - iterative context obtained from KSPCreate()

999:    Output Parameter:
1000: .  flg - PETSC_TRUE or PETSC_FALSE

1002:    Notes:
1003:    Currently this option is not valid for all iterative methods.

1005:    Level: advanced

1007: .keywords: KSP, set, compute, eigenvalues

1009: .seealso: KSPComputeEigenvalues(), KSPComputeEigenvaluesExplicitly()
1010: @*/
1011: PetscErrorCode  KSPGetComputeEigenvalues(KSP ksp,PetscTruth *flg)
1012: {
1016:   *flg = ksp->calc_sings;
1017:   return(0);
1018: }

1022: /*@
1023:    KSPSetComputeEigenvalues - Sets a flag so that the extreme eigenvalues
1024:    values will be calculated via a Lanczos or Arnoldi process as the linear 
1025:    system is solved.

1027:    Collective on KSP

1029:    Input Parameters:
1030: +  ksp - iterative context obtained from KSPCreate()
1031: -  flg - PETSC_TRUE or PETSC_FALSE

1033:    Notes:
1034:    Currently this option is not valid for all iterative methods.

1036:    Level: advanced

1038: .keywords: KSP, set, compute, eigenvalues

1040: .seealso: KSPComputeEigenvalues(), KSPComputeEigenvaluesExplicitly()
1041: @*/
1042: PetscErrorCode  KSPSetComputeEigenvalues(KSP ksp,PetscTruth flg)
1043: {
1046:   ksp->calc_sings  = flg;
1047:   return(0);
1048: }

1052: /*@
1053:    KSPGetRhs - Gets the right-hand-side vector for the linear system to
1054:    be solved.

1056:    Not Collective

1058:    Input Parameter:
1059: .  ksp - iterative context obtained from KSPCreate()

1061:    Output Parameter:
1062: .  r - right-hand-side vector

1064:    Level: developer

1066: .keywords: KSP, get, right-hand-side, rhs

1068: .seealso: KSPGetSolution(), KSPSolve()
1069: @*/
1070: PetscErrorCode  KSPGetRhs(KSP ksp,Vec *r)
1071: {
1075:   *r = ksp->vec_rhs;
1076:   return(0);
1077: }

1081: /*@
1082:    KSPGetSolution - Gets the location of the solution for the 
1083:    linear system to be solved.  Note that this may not be where the solution
1084:    is stored during the iterative process; see KSPBuildSolution().

1086:    Not Collective

1088:    Input Parameters:
1089: .  ksp - iterative context obtained from KSPCreate()

1091:    Output Parameters:
1092: .  v - solution vector

1094:    Level: developer

1096: .keywords: KSP, get, solution

1098: .seealso: KSPGetRhs(),  KSPBuildSolution(), KSPSolve()
1099: @*/
1100: PetscErrorCode  KSPGetSolution(KSP ksp,Vec *v)
1101: {
1105:   *v = ksp->vec_sol;
1106:   return(0);
1107: }

1111: /*@
1112:    KSPSetPC - Sets the preconditioner to be used to calculate the 
1113:    application of the preconditioner on a vector. 

1115:    Collective on KSP

1117:    Input Parameters:
1118: +  ksp - iterative context obtained from KSPCreate()
1119: -  pc   - the preconditioner object

1121:    Notes:
1122:    Use KSPGetPC() to retrieve the preconditioner context (for example,
1123:    to free it at the end of the computations).

1125:    Level: developer

1127: .keywords: KSP, set, precondition, Binv

1129: .seealso: KSPGetPC()
1130: @*/
1131: PetscErrorCode  KSPSetPC(KSP ksp,PC pc)
1132: {

1139:   PetscObjectReference((PetscObject)pc);
1140:   if (ksp->pc) {PCDestroy(ksp->pc);}
1141:   ksp->pc = pc;
1142:   return(0);
1143: }

1147: /*@
1148:    KSPGetPC - Returns a pointer to the preconditioner context
1149:    set with KSPSetPC().

1151:    Not Collective

1153:    Input Parameters:
1154: .  ksp - iterative context obtained from KSPCreate()

1156:    Output Parameter:
1157: .  pc - preconditioner context

1159:    Level: developer

1161: .keywords: KSP, get, preconditioner, Binv

1163: .seealso: KSPSetPC()
1164: @*/
1165: PetscErrorCode  KSPGetPC(KSP ksp,PC *pc)
1166: {
1170:   *pc = ksp->pc;
1171:   return(0);
1172: }

1176: /*@C
1177:    KSPMonitorSet - Sets an ADDITIONAL function to be called at every iteration to monitor 
1178:    the residual/error etc.
1179:       
1180:    Collective on KSP

1182:    Input Parameters:
1183: +  ksp - iterative context obtained from KSPCreate()
1184: .  monitor - pointer to function (if this is PETSC_NULL, it turns off monitoring
1185: .  mctx    - [optional] context for private data for the
1186:              monitor routine (use PETSC_NULL if no context is desired)
1187: -  monitordestroy - [optional] routine that frees monitor context
1188:           (may be PETSC_NULL)

1190:    Calling Sequence of monitor:
1191: $     monitor (KSP ksp, int it, PetscReal rnorm, void *mctx)

1193: +  ksp - iterative context obtained from KSPCreate()
1194: .  it - iteration number
1195: .  rnorm - (estimated) 2-norm of (preconditioned) residual
1196: -  mctx  - optional monitoring context, as set by KSPMonitorSet()

1198:    Options Database Keys:
1199: +    -ksp_monitor        - sets KSPMonitorDefault()
1200: .    -ksp_monitor_true_residual    - sets KSPMonitorTrueResidualNorm()
1201: .    -ksp_monitor_draw    - sets line graph monitor,
1202:                            uses KSPMonitorLGCreate()
1203: .    -ksp_monitor_draw_true_residual   - sets line graph monitor,
1204:                            uses KSPMonitorLGCreate()
1205: .    -ksp_monitor_singular_value    - sets KSPMonitorSingularValue()
1206: -    -ksp_monitor_cancel - cancels all monitors that have
1207:                           been hardwired into a code by 
1208:                           calls to KSPMonitorSet(), but
1209:                           does not cancel those set via
1210:                           the options database.

1212:    Notes:  
1213:    The default is to do nothing.  To print the residual, or preconditioned 
1214:    residual if KSPSetNormType(ksp,KSP_NORM_PRECONDITIONED) was called, use 
1215:    KSPMonitorDefault() as the monitoring routine, with a null monitoring 
1216:    context. 

1218:    Several different monitoring routines may be set by calling
1219:    KSPMonitorSet() multiple times; all will be called in the 
1220:    order in which they were set.

1222:    Level: beginner

1224: .keywords: KSP, set, monitor

1226: .seealso: KSPMonitorDefault(), KSPMonitorLGCreate(), KSPMonitorCancel()
1227: @*/
1228: PetscErrorCode  KSPMonitorSet(KSP ksp,PetscErrorCode (*monitor)(KSP,PetscInt,PetscReal,void*),void *mctx,PetscErrorCode (*monitordestroy)(void*))
1229: {
1230:   PetscInt i;

1234:   if (ksp->numbermonitors >= MAXKSPMONITORS) {
1235:     SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Too many KSP monitors set");
1236:   }
1237:   for (i=0; i<ksp->numbermonitors;i++) {
1238:     if (monitor == ksp->monitor[i] && monitordestroy == ksp->monitordestroy[i] && mctx == ksp->monitorcontext[i]) return(0);

1240:     /* check if both default monitors that share common ASCII viewer */
1241:     if (monitor == ksp->monitor[i] && monitor == KSPMonitorDefault) {
1242:       if (mctx && ksp->monitorcontext[i]) {
1243:         PetscErrorCode          ierr;
1244:         PetscViewerASCIIMonitor viewer1 = (PetscViewerASCIIMonitor) mctx;
1245:         PetscViewerASCIIMonitor viewer2 = (PetscViewerASCIIMonitor) ksp->monitorcontext[i];
1246:         if (viewer1->viewer == viewer2->viewer) {
1247:           (*monitordestroy)(mctx);
1248:           return(0);
1249:         }
1250:       }
1251:     }
1252:   }
1253:   ksp->monitor[ksp->numbermonitors]           = monitor;
1254:   ksp->monitordestroy[ksp->numbermonitors]    = monitordestroy;
1255:   ksp->monitorcontext[ksp->numbermonitors++]  = (void*)mctx;
1256:   return(0);
1257: }

1261: /*@
1262:    KSPMonitorCancel - Clears all monitors for a KSP object.

1264:    Collective on KSP

1266:    Input Parameters:
1267: .  ksp - iterative context obtained from KSPCreate()

1269:    Options Database Key:
1270: .  -ksp_monitor_cancel - Cancels all monitors that have
1271:     been hardwired into a code by calls to KSPMonitorSet(), 
1272:     but does not cancel those set via the options database.

1274:    Level: intermediate

1276: .keywords: KSP, set, monitor

1278: .seealso: KSPMonitorDefault(), KSPMonitorLGCreate(), KSPMonitorSet()
1279: @*/
1280: PetscErrorCode  KSPMonitorCancel(KSP ksp)
1281: {
1283:   PetscInt       i;

1287:   for (i=0; i<ksp->numbermonitors; i++) {
1288:     if (ksp->monitordestroy[i]) {
1289:       (*ksp->monitordestroy[i])(ksp->monitorcontext[i]);
1290:     }
1291:   }
1292:   ksp->numbermonitors = 0;
1293:   return(0);
1294: }

1298: /*@C
1299:    KSPGetMonitorContext - Gets the monitoring context, as set by 
1300:    KSPMonitorSet() for the FIRST monitor only.

1302:    Not Collective

1304:    Input Parameter:
1305: .  ksp - iterative context obtained from KSPCreate()

1307:    Output Parameter:
1308: .  ctx - monitoring context

1310:    Level: intermediate

1312: .keywords: KSP, get, monitor, context

1314: .seealso: KSPMonitorDefault(), KSPMonitorLGCreate()
1315: @*/
1316: PetscErrorCode  KSPGetMonitorContext(KSP ksp,void **ctx)
1317: {
1320:   *ctx =      (ksp->monitorcontext[0]);
1321:   return(0);
1322: }

1326: /*@
1327:    KSPSetResidualHistory - Sets the array used to hold the residual history.
1328:    If set, this array will contain the residual norms computed at each
1329:    iteration of the solver.

1331:    Not Collective

1333:    Input Parameters:
1334: +  ksp - iterative context obtained from KSPCreate()
1335: .  a   - array to hold history
1336: .  na  - size of a
1337: -  reset - PETSC_TRUE indicates the history counter is reset to zero
1338:            for each new linear solve

1340:    Level: advanced

1342:    Notes: The array is NOT freed by PETSc so the user needs to keep track of 
1343:            it and destroy once the KSP object is destroyed.

1345:    If 'na' is PETSC_DECIDE or PETSC_DEFAULT, or 'a' is PETSC_NULL, then a 
1346:    default array of length 10000 is allocated.

1348: .keywords: KSP, set, residual, history, norm

1350: .seealso: KSPGetResidualHistory()

1352: @*/
1353: PetscErrorCode  KSPSetResidualHistory(KSP ksp,PetscReal a[],PetscInt na,PetscTruth reset)
1354: {


1360:   PetscFree(ksp->res_hist_alloc);
1361:   if (na != PETSC_DECIDE && na != PETSC_DEFAULT && a) {
1362:     ksp->res_hist        = a;
1363:     ksp->res_hist_max    = na;
1364:   } else {
1365:     if (na != PETSC_DECIDE && na != PETSC_DEFAULT)
1366:       ksp->res_hist_max = na;
1367:     else
1368:       ksp->res_hist_max = 10000; /* like default ksp->max_it */
1369:     PetscMalloc(ksp->res_hist_max*sizeof(PetscReal),&ksp->res_hist_alloc);
1370:     ksp->res_hist = ksp->res_hist_alloc;
1371:   }
1372:   ksp->res_hist_len    = 0;
1373:   ksp->res_hist_reset  = reset;

1375:   return(0);
1376: }

1380: /*@C
1381:    KSPGetResidualHistory - Gets the array used to hold the residual history
1382:    and the number of residuals it contains.

1384:    Not Collective

1386:    Input Parameter:
1387: .  ksp - iterative context obtained from KSPCreate()

1389:    Output Parameters:
1390: +  a   - pointer to array to hold history (or PETSC_NULL)
1391: -  na  - number of used entries in a (or PETSC_NULL)

1393:    Level: advanced

1395:    Notes:
1396:      Can only be called after a KSPSetResidualHistory() otherwise a and na are set to zero

1398:      The Fortran version of this routine has a calling sequence
1399: $   call KSPGetResidualHistory(KSP ksp, integer na, integer ierr)

1401: .keywords: KSP, get, residual, history, norm

1403: .seealso: KSPGetResidualHistory()

1405: @*/
1406: PetscErrorCode  KSPGetResidualHistory(KSP ksp,PetscReal *a[],PetscInt *na)
1407: {
1410:   if (a)  *a  = ksp->res_hist;
1411:   if (na) *na = ksp->res_hist_len;
1412:   return(0);
1413: }

1417: /*@C
1418:    KSPSetConvergenceTest - Sets the function to be used to determine
1419:    convergence.  

1421:    Collective on KSP

1423:    Input Parameters:
1424: +  ksp - iterative context obtained from KSPCreate()
1425: .  converge - pointer to int function
1426: -  cctx    - context for private data for the convergence routine (may be null)

1428:    Calling sequence of converge:
1429: $     converge (KSP ksp, int it, PetscReal rnorm, KSPConvergedReason *reason,void *mctx)

1431: +  ksp - iterative context obtained from KSPCreate()
1432: .  it - iteration number
1433: .  rnorm - (estimated) 2-norm of (preconditioned) residual
1434: .  reason - the reason why it has converged or diverged
1435: -  cctx  - optional convergence context, as set by KSPSetConvergenceTest()


1438:    Notes:
1439:    Must be called after the KSP type has been set so put this after
1440:    a call to KSPSetType(), or KSPSetFromOptions().

1442:    The default convergence test, KSPDefaultConverged(), aborts if the 
1443:    residual grows to more than 10000 times the initial residual.

1445:    The default is a combination of relative and absolute tolerances.  
1446:    The residual value that is tested may be an approximation; routines 
1447:    that need exact values should compute them.

1449:    In the default PETSc convergence test, the precise values of reason
1450:    are macros such as KSP_CONVERGED_RTOL, which are defined in petscksp.h.

1452:    Level: advanced

1454: .keywords: KSP, set, convergence, test, context

1456: .seealso: KSPDefaultConverged(), KSPGetConvergenceContext()
1457: @*/
1458: PetscErrorCode  KSPSetConvergenceTest(KSP ksp,PetscErrorCode (*converge)(KSP,PetscInt,PetscReal,KSPConvergedReason*,void*),void *cctx)
1459: {
1462:   ksp->converged = converge;
1463:   ksp->cnvP      = (void*)cctx;
1464:   return(0);
1465: }

1469: /*@C
1470:    KSPGetConvergenceContext - Gets the convergence context set with 
1471:    KSPSetConvergenceTest().  

1473:    Not Collective

1475:    Input Parameter:
1476: .  ksp - iterative context obtained from KSPCreate()

1478:    Output Parameter:
1479: .  ctx - monitoring context

1481:    Level: advanced

1483: .keywords: KSP, get, convergence, test, context

1485: .seealso: KSPDefaultConverged(), KSPSetConvergenceTest()
1486: @*/
1487: PetscErrorCode  KSPGetConvergenceContext(KSP ksp,void **ctx)
1488: {
1491:   *ctx = ksp->cnvP;
1492:   return(0);
1493: }

1497: /*@
1498:    KSPBuildSolution - Builds the approximate solution in a vector provided.
1499:    This routine is NOT commonly needed (see KSPSolve()).

1501:    Collective on KSP

1503:    Input Parameter:
1504: .  ctx - iterative context obtained from KSPCreate()

1506:    Output Parameter: 
1507:    Provide exactly one of
1508: +  v - location to stash solution.   
1509: -  V - the solution is returned in this location. This vector is created 
1510:        internally. This vector should NOT be destroyed by the user with
1511:        VecDestroy().

1513:    Notes:
1514:    This routine can be used in one of two ways
1515: .vb
1516:       KSPBuildSolution(ksp,PETSC_NULL,&V);
1517:    or
1518:       KSPBuildSolution(ksp,v,PETSC_NULL); 
1519: .ve
1520:    In the first case an internal vector is allocated to store the solution
1521:    (the user cannot destroy this vector). In the second case the solution
1522:    is generated in the vector that the user provides. Note that for certain 
1523:    methods, such as KSPCG, the second case requires a copy of the solution,
1524:    while in the first case the call is essentially free since it simply 
1525:    returns the vector where the solution already is stored.

1527:    Level: advanced

1529: .keywords: KSP, build, solution

1531: .seealso: KSPGetSolution(), KSPBuildResidual()
1532: @*/
1533: PetscErrorCode  KSPBuildSolution(KSP ksp,Vec v,Vec *V)
1534: {

1539:   if (!V && !v) SETERRQ(PETSC_ERR_ARG_WRONG,"Must provide either v or V");
1540:   if (!V) V = &v;
1541:   (*ksp->ops->buildsolution)(ksp,v,V);
1542:   return(0);
1543: }

1547: /*@
1548:    KSPBuildResidual - Builds the residual in a vector provided.

1550:    Collective on KSP

1552:    Input Parameter:
1553: .  ksp - iterative context obtained from KSPCreate()

1555:    Output Parameters:
1556: +  v - optional location to stash residual.  If v is not provided,
1557:        then a location is generated.
1558: .  t - work vector.  If not provided then one is generated.
1559: -  V - the residual

1561:    Notes:
1562:    Regardless of whether or not v is provided, the residual is 
1563:    returned in V.

1565:    Level: advanced

1567: .keywords: KSP, build, residual

1569: .seealso: KSPBuildSolution()
1570: @*/
1571: PetscErrorCode  KSPBuildResidual(KSP ksp,Vec t,Vec v,Vec *V)
1572: {
1574:   PetscTruth     flag = PETSC_FALSE;
1575:   Vec            w = v,tt = t;

1579:   if (!w) {
1580:     VecDuplicate(ksp->vec_rhs,&w);
1581:     PetscLogObjectParent((PetscObject)ksp,w);
1582:   }
1583:   if (!tt) {
1584:     VecDuplicate(ksp->vec_sol,&tt); flag = PETSC_TRUE;
1585:     PetscLogObjectParent((PetscObject)ksp,tt);
1586:   }
1587:   (*ksp->ops->buildresidual)(ksp,tt,w,V);
1588:   if (flag) {VecDestroy(tt);}
1589:   return(0);
1590: }

1594: /*@
1595:    KSPSetDiagonalScale - Tells KSP to symmetrically diagonally scale the system
1596:      before solving. This actually CHANGES the matrix (and right hand side).

1598:    Collective on KSP

1600:    Input Parameter:
1601: +  ksp - the KSP context
1602: -  scale - PETSC_TRUE or PETSC_FALSE

1604:    Options Database Key:
1605: +   -ksp_diagonal_scale - 
1606: -   -ksp_diagonal_scale_fix - scale the matrix back AFTER the solve 


1609:     BE CAREFUL with this routine: it actually scales the matrix and right 
1610:     hand side that define the system. After the system is solved the matrix
1611:     and right hand side remain scaled.

1613:     This routine is only used if the matrix and preconditioner matrix are
1614:     the same thing.

1616:     This should NOT be used within the SNES solves if you are using a line
1617:     search.
1618:  
1619:     If you use this with the PCType Eisenstat preconditioner than you can 
1620:     use the PCEisenstatNoDiagonalScaling() option, or -pc_eisenstat_no_diagonal_scaling
1621:     to save some unneeded, redundant flops.

1623:    Level: intermediate

1625: .keywords: KSP, set, options, prefix, database

1627: .seealso: KSPGetDiagonalScale(), KSPSetDiagonalScaleFix()
1628: @*/
1629: PetscErrorCode  KSPSetDiagonalScale(KSP ksp,PetscTruth scale)
1630: {
1633:   ksp->dscale = scale;
1634:   return(0);
1635: }

1639: /*@C
1640:    KSPGetDiagonalScale - Checks if KSP solver scales the matrix and
1641:                           right hand side

1643:    Not Collective

1645:    Input Parameter:
1646: .  ksp - the KSP context

1648:    Output Parameter:
1649: .  scale - PETSC_TRUE or PETSC_FALSE

1651:    Notes:
1652:     BE CAREFUL with this routine: it actually scales the matrix and right 
1653:     hand side that define the system. After the system is solved the matrix
1654:     and right hand side remain scaled.

1656:     This routine is only used if the matrix and preconditioner matrix are
1657:     the same thing.

1659:    Level: intermediate

1661: .keywords: KSP, set, options, prefix, database

1663: .seealso: KSPSetDiagonalScale(), KSPSetDiagonalScaleFix()
1664: @*/
1665: PetscErrorCode  KSPGetDiagonalScale(KSP ksp,PetscTruth *scale)
1666: {
1670:   *scale = ksp->dscale;
1671:   return(0);
1672: }

1676: /*@
1677:    KSPSetDiagonalScaleFix - Tells KSP to diagonally scale the system
1678:      back after solving.

1680:    Collective on KSP

1682:    Input Parameter:
1683: +  ksp - the KSP context
1684: -  fix - PETSC_TRUE to scale back after the system solve, PETSC_FALSE to not 
1685:          rescale (default)

1687:    Notes:
1688:      Must be called after KSPSetDiagonalScale()

1690:      Using this will slow things down, because it rescales the matrix before and
1691:      after each linear solve. This is intended mainly for testing to allow one
1692:      to easily get back the original system to make sure the solution computed is
1693:      accurate enough.

1695:     This routine is only used if the matrix and preconditioner matrix are
1696:     the same thing.

1698:    Level: intermediate

1700: .keywords: KSP, set, options, prefix, database

1702: .seealso: KSPGetDiagonalScale(), KSPSetDiagonalScale(), KSPGetDiagonalScaleFix()
1703: @*/
1704: PetscErrorCode  KSPSetDiagonalScaleFix(KSP ksp,PetscTruth fix)
1705: {
1708:   ksp->dscalefix = fix;
1709:   return(0);
1710: }

1714: /*@
1715:    KSPGetDiagonalScaleFix - Determines if KSP diagonally scales the system
1716:      back after solving.

1718:    Collective on KSP

1720:    Input Parameter:
1721: .  ksp - the KSP context

1723:    Output Parameter:
1724: .  fix - PETSC_TRUE to scale back after the system solve, PETSC_FALSE to not 
1725:          rescale (default)

1727:    Notes:
1728:      Must be called after KSPSetDiagonalScale()

1730:      If PETSC_TRUE will slow things down, because it rescales the matrix before and
1731:      after each linear solve. This is intended mainly for testing to allow one
1732:      to easily get back the original system to make sure the solution computed is
1733:      accurate enough.

1735:     This routine is only used if the matrix and preconditioner matrix are
1736:     the same thing.

1738:    Level: intermediate

1740: .keywords: KSP, set, options, prefix, database

1742: .seealso: KSPGetDiagonalScale(), KSPSetDiagonalScale(), KSPSetDiagonalScaleFix()
1743: @*/
1744: PetscErrorCode  KSPGetDiagonalScaleFix(KSP ksp,PetscTruth *fix)
1745: {
1749:   *fix = ksp->dscalefix;
1750:   return(0);
1751: }