Actual source code: itfunc.c

  1: #define PETSCKSP_DLL

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

 7:  #include src/ksp/ksp/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:    KSPSingularValueMonitor() (which can be set with option -ksp_singmonitor)
 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(), KSPSingularValueMonitor(), KSPComputeEigenvalues()
 36: @*/
 37: PetscErrorCode PETSCKSP_DLLEXPORT 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:    KSPSingularValueMonitor() (which can be set with option -ksp_singmonitor)
 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(), KSPSingularValueMonitor(), KSPComputeExtremeSingularValues()
103: @*/
104: PetscErrorCode PETSCKSP_DLLEXPORT 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 PETSCKSP_DLLEXPORT 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 PETSCKSP_DLLEXPORT 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);

195:   PetscLogEventBegin(KSP_SetUp,ksp,ksp->vec_rhs,ksp->vec_sol,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:   }
233:   PetscLogEventEnd(KSP_SetUp,ksp,ksp->vec_rhs,ksp->vec_sol,0);
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 

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
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 KSPSetMonitor(), 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 PETSCKSP_DLLEXPORT KSPSolve(KSP ksp,Vec b,Vec x)
296: {
298:   PetscMPIInt    rank;
299:   PetscTruth     flag1,flag2,viewed=PETSC_FALSE,flg;
300:   char           view[10];
301:   char           filename[PETSC_MAX_PATH_LEN];
302:   PetscViewer    viewer;


309: 
310:   ksp->vec_rhs = b;
311:   ksp->vec_sol = x;
312:   PetscOptionsHasName(ksp->prefix,"-ksp_view_binary",&flg);
313:   if (flg) {
314:     Mat mat;
315:     PCGetOperators(ksp->pc,&mat,PETSC_NULL,PETSC_NULL);
316:     MatView(mat,PETSC_VIEWER_BINARY_(ksp->comm));
317:     VecView(ksp->vec_rhs,PETSC_VIEWER_BINARY_(ksp->comm));
318:   }

320:   PetscLogEventBegin(KSP_Solve,ksp,ksp->vec_rhs,ksp->vec_sol,0);

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

325:   PetscOptionsGetString(ksp->prefix,"-ksp_view",view,10,&flg);
326:   if (flg) {
327:     PetscStrcmp(view,"before",&viewed);
328:     if (viewed){
329:       KSPView(ksp,PETSC_VIEWER_STDOUT_(ksp->comm));
330:     }
331:   }

333:   /* KSPSetUp() scales the matrix if needed */
334:   KSPSetUp(ksp);
335:   KSPSetUpOnBlocks(ksp);

337:   ksp->transpose_solve = PETSC_FALSE;

339:   /* diagonal scale RHS if called for */
340:   if (ksp->dscale) {
341:     VecPointwiseMult(ksp->vec_rhs,ksp->vec_rhs,ksp->diagonal);
342:     /* second time in, but matrix was scaled back to original */
343:     if (ksp->dscalefix && ksp->dscalefix2) {
344:       Mat mat;

346:       PCGetOperators(ksp->pc,&mat,PETSC_NULL,PETSC_NULL);
347:       MatDiagonalScale(mat,ksp->diagonal,ksp->diagonal);
348:     }

350:     /*  scale initial guess */
351:     if (!ksp->guess_zero) {
352:       if (!ksp->truediagonal) {
353:         VecDuplicate(ksp->diagonal,&ksp->truediagonal);
354:         VecCopy(ksp->diagonal,ksp->truediagonal);
355:         VecReciprocal(ksp->truediagonal);
356:       }
357:       VecPointwiseMult(ksp->vec_sol,ksp->vec_sol,ksp->truediagonal);
358:     }
359:   }
360:   PCPreSolve(ksp->pc,ksp);

362:   if (ksp->guess_zero) { VecSet(ksp->vec_sol,0.0);}
363:   if (ksp->guess_knoll) {
364:     PCApply(ksp->pc,ksp->vec_rhs,ksp->vec_sol);
365:     KSP_RemoveNullSpace(ksp,ksp->vec_sol);
366:     ksp->guess_zero = PETSC_FALSE;
367:   }
368:   (*ksp->ops->solve)(ksp);
369:   if (!ksp->reason) {
370:     SETERRQ(PETSC_ERR_PLIB,"Internal error, solver returned without setting converged reason");
371:   }
372:   if (ksp->printreason) {
373:     if (ksp->reason > 0) {
374:       PetscPrintf(ksp->comm,"Linear solve converged due to %s\n",KSPConvergedReasons[ksp->reason]);
375:     } else {
376:       PetscPrintf(ksp->comm,"Linear solve did not converge due to %s\n",KSPConvergedReasons[ksp->reason]);
377:     }
378:   }

380:   /* diagonal scale solution if called for */
381:   PCPostSolve(ksp->pc,ksp);
382:   if (ksp->dscale) {
383:     VecPointwiseMult(ksp->vec_sol,ksp->vec_sol,ksp->diagonal);
384:     /* unscale right hand side and matrix */
385:     if (ksp->dscalefix) {
386:       Mat mat;

388:       VecReciprocal(ksp->diagonal);
389:       VecPointwiseMult(ksp->vec_rhs,ksp->vec_rhs,ksp->diagonal);
390:       PCGetOperators(ksp->pc,&mat,PETSC_NULL,PETSC_NULL);
391:       MatDiagonalScale(mat,ksp->diagonal,ksp->diagonal);
392:       VecReciprocal(ksp->diagonal);
393:       ksp->dscalefix2 = PETSC_TRUE;
394:     }
395:   }
396:   PetscLogEventEnd(KSP_Solve,ksp,ksp->vec_rhs,ksp->vec_sol,0);

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

400:   PetscOptionsHasName(ksp->prefix,"-ksp_compute_eigenvalues",&flag1);
401:   PetscOptionsHasName(ksp->prefix,"-ksp_plot_eigenvalues",&flag2);
402:   if (flag1 || flag2) {
403:     PetscInt   nits,n,i,neig;
404:     PetscReal *r,*c;
405: 
406:     KSPGetIterationNumber(ksp,&nits);
407:     n = nits+2;

409:     if (!n) {
410:       PetscPrintf(ksp->comm,"Zero iterations in solver, cannot approximate any eigenvalues\n");
411:     } else {
412:       PetscMalloc(2*n*sizeof(PetscReal),&r);
413:       c = r + n;
414:       KSPComputeEigenvalues(ksp,n,r,c,&neig);
415:       if (flag1) {
416:         PetscPrintf(ksp->comm,"Iteratively computed eigenvalues\n");
417:         for (i=0; i<neig; i++) {
418:           if (c[i] >= 0.0) {PetscPrintf(ksp->comm,"%G + %Gi\n",r[i],c[i]);}
419:           else             {PetscPrintf(ksp->comm,"%G - %Gi\n",r[i],-c[i]);}
420:         }
421:       }
422:       if (flag2 && !rank) {
423:         PetscDraw   draw;
424:         PetscDrawSP drawsp;

426:         PetscViewerDrawOpen(PETSC_COMM_SELF,0,"Iteratively Computed Eigenvalues",PETSC_DECIDE,PETSC_DECIDE,300,300,&viewer);
427:         PetscViewerDrawGetDraw(viewer,0,&draw);
428:         PetscDrawSPCreate(draw,1,&drawsp);
429:         for (i=0; i<neig; i++) {
430:           PetscDrawSPAddPoint(drawsp,r+i,c+i);
431:         }
432:         PetscDrawSPDraw(drawsp);
433:         PetscDrawSPDestroy(drawsp);
434:         PetscViewerDestroy(viewer);
435:       }
436:       PetscFree(r);
437:     }
438:   }

440:   PetscOptionsHasName(ksp->prefix,"-ksp_compute_eigenvalues_explicitly",&flag1);
441:   PetscOptionsHasName(ksp->prefix,"-ksp_plot_eigenvalues_explicitly",&flag2);
442:   if (flag1 || flag2) {
443:     PetscInt  n,i;
444:     PetscReal *r,*c;
445:     VecGetSize(ksp->vec_sol,&n);
446:     PetscMalloc(2*n*sizeof(PetscReal),&r);
447:     c = r + n;
448:     KSPComputeEigenvaluesExplicitly(ksp,n,r,c);
449:     if (flag1) {
450:       PetscPrintf(ksp->comm,"Explicitly computed eigenvalues\n");
451:       for (i=0; i<n; i++) {
452:         if (c[i] >= 0.0) {PetscPrintf(ksp->comm,"%G + %Gi\n",r[i],c[i]);}
453:         else             {PetscPrintf(ksp->comm,"%G - %Gi\n",r[i],-c[i]);}
454:       }
455:     }
456:     if (flag2 && !rank) {
457:       PetscDraw   draw;
458:       PetscDrawSP drawsp;

460:       PetscViewerDrawOpen(PETSC_COMM_SELF,0,"Explicitly Computed Eigenvalues",0,320,300,300,&viewer);
461:       PetscViewerDrawGetDraw(viewer,0,&draw);
462:       PetscDrawSPCreate(draw,1,&drawsp);
463:       for (i=0; i<n; i++) {
464:         PetscDrawSPAddPoint(drawsp,r+i,c+i);
465:       }
466:       PetscDrawSPDraw(drawsp);
467:       PetscDrawSPDestroy(drawsp);
468:       PetscViewerDestroy(viewer);
469:     }
470:     PetscFree(r);
471:   }

473:   PetscOptionsHasName(ksp->prefix,"-ksp_view_operator",&flag2);
474:   if (flag2) {
475:     Mat A,B;
476:     PCGetOperators(ksp->pc,&A,PETSC_NULL,PETSC_NULL);
477:     MatComputeExplicitOperator(A,&B);
478:     PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(ksp->comm),PETSC_VIEWER_ASCII_MATLAB);
479:     MatView(B,PETSC_VIEWER_STDOUT_(ksp->comm));
480:     PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(ksp->comm));
481:     MatDestroy(B);
482:   }
483:   PetscOptionsHasName(ksp->prefix,"-ksp_view_operator_binary",&flag2);
484:   if (flag2) {
485:     Mat A,B;
486:     PCGetOperators(ksp->pc,&A,PETSC_NULL,PETSC_NULL);
487:     MatComputeExplicitOperator(A,&B);
488:     MatView(B,PETSC_VIEWER_BINARY_(ksp->comm));
489:     MatDestroy(B);
490:   }
491:   PetscOptionsHasName(ksp->prefix,"-ksp_view_preconditioned_operator_binary",&flag2);
492:   if (flag2) {
493:     Mat B;
494:     KSPComputeExplicitOperator(ksp,&B);
495:     MatView(B,PETSC_VIEWER_BINARY_(ksp->comm));
496:     MatDestroy(B);
497:   }
498:   if (!viewed) {
499:     PetscOptionsGetString(ksp->prefix,"-ksp_view",filename,PETSC_MAX_PATH_LEN,&flg);
500:     if (flg && !PetscPreLoadingOn) {
501:       PetscViewerASCIIOpen(ksp->comm,filename,&viewer);
502:       KSPView(ksp,viewer);
503:       PetscViewerDestroy(viewer);
504:     }
505:   }
506:   PetscOptionsHasName(ksp->prefix,"-ksp_final_residual",&flg);
507:   if (flg) {
508:     Mat         A;
509:     Vec         t;
510:     PetscReal   norm;
511:     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");
512:     PCGetOperators(ksp->pc,&A,0,0);
513:     VecDuplicate(ksp->vec_sol,&t);
514:     KSP_MatMult(ksp,A,ksp->vec_sol,t);
515:     VecWAXPY(t,-1.0,t,ksp->vec_rhs);
516:     VecNorm(t,NORM_2,&norm);
517:     VecDestroy(t);
518:     PetscPrintf(ksp->comm,"KSP final norm of residual %G\n",norm);
519:   }
520:   return(0);
521: }

525: /*@
526:    KSPSolveTranspose - Solves the transpose of a linear system. Usually
527:    accessed through KSPSolveTranspose().

529:    Collective on KSP

531:    Input Parameter:
532: +  ksp - iterative context obtained from KSPCreate()
533: .  b - right hand side vector
534: -  x - solution vector

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

540:    Level: developer

542: .keywords: KSP, solve, linear system

544: .seealso: KSPCreate(), KSPSetUp(), KSPDestroy(), KSPSetTolerances(), KSPDefaultConverged(),
545:           KSPSolve()
546: @*/
547: PetscErrorCode PETSCKSP_DLLEXPORT KSPSolveTranspose(KSP ksp,Vec b,Vec x)
548: {
550:   PetscScalar    zero = 0.0;


557:   ksp->vec_rhs = b;
558:   ksp->vec_sol = x;
559:   KSPSetUp(ksp);
560:   if (ksp->guess_zero) { VecSet(ksp->vec_sol,zero);}
561:   ksp->transpose_solve = PETSC_TRUE;
562:   (*ksp->ops->solve)(ksp);
563:   return(0);
564: }

568: /*@
569:    KSPDestroy - Destroys KSP context.

571:    Collective on KSP

573:    Input Parameter:
574: .  ksp - iterative context obtained from KSPCreate()

576:    Level: beginner

578: .keywords: KSP, destroy

580: .seealso: KSPCreate(), KSPSetUp(), KSPSolve()
581: @*/
582: PetscErrorCode PETSCKSP_DLLEXPORT KSPDestroy(KSP ksp)
583: {

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

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

593:   if (ksp->ops->destroy) {
594:     (*ksp->ops->destroy)(ksp);
595:   }
596:   KSPClearMonitor(ksp);
597:   PCDestroy(ksp->pc);
598:   if (ksp->diagonal) {VecDestroy(ksp->diagonal);}
599:   if (ksp->truediagonal) {VecDestroy(ksp->truediagonal);}
600:   if (ksp->nullsp) {MatNullSpaceDestroy(ksp->nullsp);}
601:   PetscHeaderDestroy(ksp);
602:   return(0);
603: }

607: /*@
608:     KSPSetPreconditionerSide - Sets the preconditioning side.

610:     Collective on KSP

612:     Input Parameter:
613: .   ksp - iterative context obtained from KSPCreate()

615:     Output Parameter:
616: .   side - the preconditioning side, where side is one of
617: .vb
618:       PC_LEFT - left preconditioning (default)
619:       PC_RIGHT - right preconditioning
620:       PC_SYMMETRIC - symmetric preconditioning
621: .ve

623:     Options Database Keys:
624: +   -ksp_left_pc - Sets left preconditioning
625: .   -ksp_right_pc - Sets right preconditioning
626: -   -ksp_symmetric_pc - Sets symmetric preconditioning

628:     Notes:
629:     Left preconditioning is used by default.  Symmetric preconditioning is
630:     currently available only for the KSPQCG method. Note, however, that
631:     symmetric preconditioning can be emulated by using either right or left
632:     preconditioning and a pre or post processing step.

634:     Level: intermediate

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

638: .seealso: KSPGetPreconditionerSide()
639: @*/
640: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetPreconditionerSide(KSP ksp,PCSide side)
641: {
644:   ksp->pc_side = side;
645:   return(0);
646: }

650: /*@
651:     KSPGetPreconditionerSide - Gets the preconditioning side.

653:     Not Collective

655:     Input Parameter:
656: .   ksp - iterative context obtained from KSPCreate()

658:     Output Parameter:
659: .   side - the preconditioning side, where side is one of
660: .vb
661:       PC_LEFT - left preconditioning (default)
662:       PC_RIGHT - right preconditioning
663:       PC_SYMMETRIC - symmetric preconditioning
664: .ve

666:     Level: intermediate

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

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

683: /*@
684:    KSPGetTolerances - Gets the relative, absolute, divergence, and maximum
685:    iteration tolerances used by the default KSP convergence tests. 

687:    Not Collective

689:    Input Parameter:
690: .  ksp - the Krylov subspace context
691:   
692:    Output Parameters:
693: +  rtol - the relative convergence tolerance
694: .  abstol - the absolute convergence tolerance
695: .  dtol - the divergence tolerance
696: -  maxits - maximum number of iterations

698:    Notes:
699:    The user can specify PETSC_NULL for any parameter that is not needed.

701:    Level: intermediate

703: .keywords: KSP, get, tolerance, absolute, relative, divergence, convergence,
704:            maximum, iterations

706: .seealso: KSPSetTolerances()
707: @*/
708: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetTolerances(KSP ksp,PetscReal *rtol,PetscReal *abstol,PetscReal *dtol,PetscInt *maxits)
709: {
712:   if (abstol)   *abstol   = ksp->abstol;
713:   if (rtol)   *rtol   = ksp->rtol;
714:   if (dtol)   *dtol   = ksp->divtol;
715:   if (maxits) *maxits = ksp->max_it;
716:   return(0);
717: }

721: /*@
722:    KSPSetTolerances - Sets the relative, absolute, divergence, and maximum
723:    iteration tolerances used by the default KSP convergence testers. 

725:    Collective on KSP

727:    Input Parameters:
728: +  ksp - the Krylov subspace context
729: .  rtol - the relative convergence tolerance
730:    (relative decrease in the residual norm)
731: .  abstol - the absolute convergence tolerance 
732:    (absolute size of the residual norm)
733: .  dtol - the divergence tolerance
734:    (amount residual can increase before KSPDefaultConverged()
735:    concludes that the method is diverging)
736: -  maxits - maximum number of iterations to use

738:    Options Database Keys:
739: +  -ksp_atol <abstol> - Sets abstol
740: .  -ksp_rtol <rtol> - Sets rtol
741: .  -ksp_divtol <dtol> - Sets dtol
742: -  -ksp_max_it <maxits> - Sets maxits

744:    Notes:
745:    Use PETSC_DEFAULT to retain the default value of any of the tolerances.

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

751:    Level: intermediate

753: .keywords: KSP, set, tolerance, absolute, relative, divergence, 
754:            convergence, maximum, iterations

756: .seealso: KSPGetTolerances(), KSPDefaultConverged(), KSPSetConvergenceTest()
757: @*/
758: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetTolerances(KSP ksp,PetscReal rtol,PetscReal abstol,PetscReal dtol,PetscInt maxits)
759: {
762:   if (abstol != PETSC_DEFAULT)   ksp->abstol   = abstol;
763:   if (rtol != PETSC_DEFAULT)   ksp->rtol   = rtol;
764:   if (dtol != PETSC_DEFAULT)   ksp->divtol = dtol;
765:   if (maxits != PETSC_DEFAULT) ksp->max_it = maxits;
766:   return(0);
767: }

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

776:    Collective on KSP

778:    Input Parameters:
779: +  ksp - iterative context obtained from KSPCreate()
780: -  flg - PETSC_TRUE indicates the guess is non-zero, PETSC_FALSE indicates the guess is zero

782:    Level: beginner

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

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

789: .seealso: KSPGetInitialGuessNonzero(), KSPSetInitialGuessKnoll(), KSPGetInitialGuessKnoll()
790: @*/
791: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetInitialGuessNonzero(KSP ksp,PetscTruth flg)
792: {
794:   ksp->guess_zero   = (PetscTruth)!(int)flg;
795:   return(0);
796: }

800: /*@
801:    KSPGetInitialGuessNonzero - Determines whether the KSP solver is using
802:    a zero initial guess.

804:    Not Collective

806:    Input Parameter:
807: .  ksp - iterative context obtained from KSPCreate()

809:    Output Parameter:
810: .  flag - PETSC_TRUE if guess is nonzero, else PETSC_FALSE

812:    Level: intermediate

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

816: .seealso: KSPSetInitialGuessNonzero(), KSPSetInitialGuessKnoll(), KSPGetInitialGuessKnoll()
817: @*/
818: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetInitialGuessNonzero(KSP ksp,PetscTruth *flag)
819: {
821:   if (ksp->guess_zero) *flag = PETSC_FALSE;
822:   else                 *flag = PETSC_TRUE;
823:   return(0);
824: }

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

831:    Collective on KSP

833:    Input Parameters:
834: +  ksp - iterative context obtained from KSPCreate()
835: -  flg - PETSC_TRUE or PETSC_FALSE

837:    Level: advanced


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

842: .seealso: KSPGetInitialGuessKnoll(), KSPSetInitialGuessNonzero(), KSPGetInitialGuessNonzero()
843: @*/
844: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetInitialGuessKnoll(KSP ksp,PetscTruth flg)
845: {
847:   ksp->guess_knoll   = flg;
848:   return(0);
849: }

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

857:    Not Collective

859:    Input Parameter:
860: .  ksp - iterative context obtained from KSPCreate()

862:    Output Parameter:
863: .  flag - PETSC_TRUE if using Knoll trick, else PETSC_FALSE

865:    Level: advanced

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

869: .seealso: KSPSetInitialGuessKnoll(), KSPSetInitialGuessNonzero(), KSPGetInitialGuessNonzero()
870: @*/
871: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetInitialGuessKnoll(KSP ksp,PetscTruth *flag)
872: {
874:   *flag = ksp->guess_knoll;
875:   return(0);
876: }

880: /*@
881:    KSPGetComputeSingularValues - Gets the flag indicating whether the extreme singular 
882:    values will be calculated via a Lanczos or Arnoldi process as the linear 
883:    system is solved.

885:    Collective on KSP

887:    Input Parameter:
888: .  ksp - iterative context obtained from KSPCreate()

890:    Output Parameter:
891: .  flg - PETSC_TRUE or PETSC_FALSE

893:    Options Database Key:
894: .  -ksp_singmonitor - Activates KSPSetComputeSingularValues()

896:    Notes:
897:    Currently this option is not valid for all iterative methods.

899:    Many users may just want to use the monitoring routine
900:    KSPSingularValueMonitor() (which can be set with option -ksp_singmonitor)
901:    to print the singular values at each iteration of the linear solve.

903:    Level: advanced

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

907: .seealso: KSPComputeExtremeSingularValues(), KSPSingularValueMonitor()
908: @*/
909: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetComputeSingularValues(KSP ksp,PetscTruth *flg)
910: {
914:   *flg = ksp->calc_sings;
915:   return(0);
916: }

920: /*@
921:    KSPSetComputeSingularValues - Sets a flag so that the extreme singular 
922:    values will be calculated via a Lanczos or Arnoldi process as the linear 
923:    system is solved.

925:    Collective on KSP

927:    Input Parameters:
928: +  ksp - iterative context obtained from KSPCreate()
929: -  flg - PETSC_TRUE or PETSC_FALSE

931:    Options Database Key:
932: .  -ksp_singmonitor - Activates KSPSetComputeSingularValues()

934:    Notes:
935:    Currently this option is not valid for all iterative methods.

937:    Many users may just want to use the monitoring routine
938:    KSPSingularValueMonitor() (which can be set with option -ksp_singmonitor)
939:    to print the singular values at each iteration of the linear solve.

941:    Level: advanced

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

945: .seealso: KSPComputeExtremeSingularValues(), KSPSingularValueMonitor()
946: @*/
947: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetComputeSingularValues(KSP ksp,PetscTruth flg)
948: {
951:   ksp->calc_sings  = flg;
952:   return(0);
953: }

957: /*@
958:    KSPGetComputeEigenvalues - Gets the flag indicating that the extreme eigenvalues
959:    values will be calculated via a Lanczos or Arnoldi process as the linear 
960:    system is solved.

962:    Collective on KSP

964:    Input Parameter:
965: .  ksp - iterative context obtained from KSPCreate()

967:    Output Parameter:
968: .  flg - PETSC_TRUE or PETSC_FALSE

970:    Notes:
971:    Currently this option is not valid for all iterative methods.

973:    Level: advanced

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

977: .seealso: KSPComputeEigenvalues(), KSPComputeEigenvaluesExplicitly()
978: @*/
979: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetComputeEigenvalues(KSP ksp,PetscTruth *flg)
980: {
984:   *flg = ksp->calc_sings;
985:   return(0);
986: }

990: /*@
991:    KSPSetComputeEigenvalues - Sets a flag so that the extreme eigenvalues
992:    values will be calculated via a Lanczos or Arnoldi process as the linear 
993:    system is solved.

995:    Collective on KSP

997:    Input Parameters:
998: +  ksp - iterative context obtained from KSPCreate()
999: -  flg - PETSC_TRUE or PETSC_FALSE

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

1004:    Level: advanced

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

1008: .seealso: KSPComputeEigenvalues(), KSPComputeEigenvaluesExplicitly()
1009: @*/
1010: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetComputeEigenvalues(KSP ksp,PetscTruth flg)
1011: {
1014:   ksp->calc_sings  = flg;
1015:   return(0);
1016: }

1020: /*@
1021:    KSPGetRhs - Gets the right-hand-side vector for the linear system to
1022:    be solved.

1024:    Not Collective

1026:    Input Parameter:
1027: .  ksp - iterative context obtained from KSPCreate()

1029:    Output Parameter:
1030: .  r - right-hand-side vector

1032:    Level: developer

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

1036: .seealso: KSPGetSolution(), KSPSolve()
1037: @*/
1038: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetRhs(KSP ksp,Vec *r)
1039: {
1042:   *r = ksp->vec_rhs;
1043:   return(0);
1044: }

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

1053:    Not Collective

1055:    Input Parameters:
1056: .  ksp - iterative context obtained from KSPCreate()

1058:    Output Parameters:
1059: .  v - solution vector

1061:    Level: developer

1063: .keywords: KSP, get, solution

1065: .seealso: KSPGetRhs(),  KSPBuildSolution(), KSPSolve()
1066: @*/
1067: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetSolution(KSP ksp,Vec *v)
1068: {
1072:   *v = ksp->vec_sol;
1073:   return(0);
1074: }

1078: /*@
1079:    KSPSetPC - Sets the preconditioner to be used to calculate the 
1080:    application of the preconditioner on a vector. 

1082:    Collective on KSP

1084:    Input Parameters:
1085: +  ksp - iterative context obtained from KSPCreate()
1086: -  pc   - the preconditioner object

1088:    Notes:
1089:    Use KSPGetPC() to retrieve the preconditioner context (for example,
1090:    to free it at the end of the computations).

1092:    Level: developer

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

1096: .seealso: KSPGetPC()
1097: @*/
1098: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetPC(KSP ksp,PC pc)
1099: {

1106:   if (ksp->pc) {PCDestroy(ksp->pc);}
1107:   ksp->pc = pc;
1108:   PetscObjectReference((PetscObject)ksp->pc);
1109:   return(0);
1110: }

1114: /*@
1115:    KSPGetPC - Returns a pointer to the preconditioner context
1116:    set with KSPSetPC().

1118:    Not Collective

1120:    Input Parameters:
1121: .  ksp - iterative context obtained from KSPCreate()

1123:    Output Parameter:
1124: .  pc - preconditioner context

1126:    Level: developer

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

1130: .seealso: KSPSetPC()
1131: @*/
1132: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetPC(KSP ksp,PC *pc)
1133: {
1137:   *pc = ksp->pc;
1138:   return(0);
1139: }

1143: /*@C
1144:    KSPSetMonitor - Sets an ADDITIONAL function to be called at every iteration to monitor 
1145:    the residual/error etc.
1146:       
1147:    Collective on KSP

1149:    Input Parameters:
1150: +  ksp - iterative context obtained from KSPCreate()
1151: .  monitor - pointer to function (if this is PETSC_NULL, it turns off monitoring
1152: .  mctx    - [optional] context for private data for the
1153:              monitor routine (use PETSC_NULL if no context is desired)
1154: -  monitordestroy - [optional] routine that frees monitor context
1155:           (may be PETSC_NULL)

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

1160: +  ksp - iterative context obtained from KSPCreate()
1161: .  it - iteration number
1162: .  rnorm - (estimated) 2-norm of (preconditioned) residual
1163: -  mctx  - optional monitoring context, as set by KSPSetMonitor()

1165:    Options Database Keys:
1166: +    -ksp_monitor        - sets KSPDefaultMonitor()
1167: .    -ksp_truemonitor    - sets KSPTrueMonitor()
1168: .    -ksp_xmonitor       - sets line graph monitor,
1169:                            uses KSPLGMonitorCreate()
1170: .    -ksp_xtruemonitor   - sets line graph monitor,
1171:                            uses KSPLGMonitorCreate()
1172: .    -ksp_singmonitor    - sets KSPSingularValueMonitor()
1173: -    -ksp_cancelmonitors - cancels all monitors that have
1174:                           been hardwired into a code by 
1175:                           calls to KSPSetMonitor(), but
1176:                           does not cancel those set via
1177:                           the options database.

1179:    Notes:  
1180:    The default is to do nothing.  To print the residual, or preconditioned 
1181:    residual if KSPSetNormType(ksp,KSP_PRECONDITIONED_NORM) was called, use 
1182:    KSPDefaultMonitor() as the monitoring routine, with a null monitoring 
1183:    context. 

1185:    Several different monitoring routines may be set by calling
1186:    KSPSetMonitor() multiple times; all will be called in the 
1187:    order in which they were set.

1189:    Level: beginner

1191: .keywords: KSP, set, monitor

1193: .seealso: KSPDefaultMonitor(), KSPLGMonitorCreate(), KSPClearMonitor()
1194: @*/
1195: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetMonitor(KSP ksp,PetscErrorCode (*monitor)(KSP,PetscInt,PetscReal,void*),void *mctx,PetscErrorCode (*monitordestroy)(void*))
1196: {
1199:   if (ksp->numbermonitors >= MAXKSPMONITORS) {
1200:     SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Too many KSP monitors set");
1201:   }
1202:   ksp->monitor[ksp->numbermonitors]           = monitor;
1203:   ksp->monitordestroy[ksp->numbermonitors]    = monitordestroy;
1204:   ksp->monitorcontext[ksp->numbermonitors++]  = (void*)mctx;
1205:   return(0);
1206: }

1210: /*@
1211:    KSPClearMonitor - Clears all monitors for a KSP object.

1213:    Collective on KSP

1215:    Input Parameters:
1216: .  ksp - iterative context obtained from KSPCreate()

1218:    Options Database Key:
1219: .  -ksp_cancelmonitors - Cancels all monitors that have
1220:     been hardwired into a code by calls to KSPSetMonitor(), 
1221:     but does not cancel those set via the options database.

1223:    Level: intermediate

1225: .keywords: KSP, set, monitor

1227: .seealso: KSPDefaultMonitor(), KSPLGMonitorCreate(), KSPSetMonitor()
1228: @*/
1229: PetscErrorCode PETSCKSP_DLLEXPORT KSPClearMonitor(KSP ksp)
1230: {
1232:   PetscInt       i;

1236:   for (i=0; i<ksp->numbermonitors; i++) {
1237:     if (ksp->monitordestroy[i]) {
1238:       (*ksp->monitordestroy[i])(ksp->monitorcontext[i]);
1239:     }
1240:   }
1241:   ksp->numbermonitors = 0;
1242:   return(0);
1243: }

1247: /*@C
1248:    KSPGetMonitorContext - Gets the monitoring context, as set by 
1249:    KSPSetMonitor() for the FIRST monitor only.

1251:    Not Collective

1253:    Input Parameter:
1254: .  ksp - iterative context obtained from KSPCreate()

1256:    Output Parameter:
1257: .  ctx - monitoring context

1259:    Level: intermediate

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

1263: .seealso: KSPDefaultMonitor(), KSPLGMonitorCreate()
1264: @*/
1265: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetMonitorContext(KSP ksp,void **ctx)
1266: {
1269:   *ctx =      (ksp->monitorcontext[0]);
1270:   return(0);
1271: }

1275: /*@
1276:    KSPSetResidualHistory - Sets the array used to hold the residual history.
1277:    If set, this array will contain the residual norms computed at each
1278:    iteration of the solver.

1280:    Not Collective

1282:    Input Parameters:
1283: +  ksp - iterative context obtained from KSPCreate()
1284: .  a   - array to hold history
1285: .  na  - size of a
1286: -  reset - PETSC_TRUE indicates the history counter is reset to zero
1287:            for each new linear solve

1289:    Level: advanced

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

1294:    If 'na' is PETSC_DECIDE or 'a' is PETSC_NULL, then a default array of
1295:    length 1000 is allocated.

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

1299: .seealso: KSPGetResidualHistory()

1301: @*/
1302: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetResidualHistory(KSP ksp,PetscReal a[],PetscInt na,PetscTruth reset)
1303: {

1308:   if (na != PETSC_DECIDE && a) {
1309:     ksp->res_hist        = a;
1310:     ksp->res_hist_max    = na;
1311:   } else {
1312:     ksp->res_hist_max    = 1000;
1313:     PetscMalloc(ksp->res_hist_max*sizeof(PetscReal),&ksp->res_hist);
1314:   }
1315:   ksp->res_hist_len    = 0;
1316:   ksp->res_hist_reset  = reset;


1319:   return(0);
1320: }

1324: /*@C
1325:    KSPGetResidualHistory - Gets the array used to hold the residual history
1326:    and the number of residuals it contains.

1328:    Not Collective

1330:    Input Parameter:
1331: .  ksp - iterative context obtained from KSPCreate()

1333:    Output Parameters:
1334: +  a   - pointer to array to hold history (or PETSC_NULL)
1335: -  na  - number of used entries in a (or PETSC_NULL)

1337:    Level: advanced

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

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

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

1347: .seealso: KSPGetResidualHistory()

1349: @*/
1350: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetResidualHistory(KSP ksp,PetscReal *a[],PetscInt *na)
1351: {
1354:   if (a)  *a = ksp->res_hist;
1355:   if (na) *na = ksp->res_hist_len;
1356:   return(0);
1357: }

1361: /*@C
1362:    KSPSetConvergenceTest - Sets the function to be used to determine
1363:    convergence.  

1365:    Collective on KSP

1367:    Input Parameters:
1368: +  ksp - iterative context obtained from KSPCreate()
1369: .  converge - pointer to int function
1370: -  cctx    - context for private data for the convergence routine (may be null)

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

1375: +  ksp - iterative context obtained from KSPCreate()
1376: .  it - iteration number
1377: .  rnorm - (estimated) 2-norm of (preconditioned) residual
1378: .  reason - the reason why it has converged or diverged
1379: -  cctx  - optional convergence context, as set by KSPSetConvergenceTest()


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

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

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

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

1396:    Level: advanced

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

1400: .seealso: KSPDefaultConverged(), KSPGetConvergenceContext()
1401: @*/
1402: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetConvergenceTest(KSP ksp,PetscErrorCode (*converge)(KSP,PetscInt,PetscReal,KSPConvergedReason*,void*),void *cctx)
1403: {
1406:   ksp->converged = converge;
1407:   ksp->cnvP      = (void*)cctx;
1408:   return(0);
1409: }

1413: /*@C
1414:    KSPGetConvergenceContext - Gets the convergence context set with 
1415:    KSPSetConvergenceTest().  

1417:    Not Collective

1419:    Input Parameter:
1420: .  ksp - iterative context obtained from KSPCreate()

1422:    Output Parameter:
1423: .  ctx - monitoring context

1425:    Level: advanced

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

1429: .seealso: KSPDefaultConverged(), KSPSetConvergenceTest()
1430: @*/
1431: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetConvergenceContext(KSP ksp,void **ctx)
1432: {
1435:   *ctx = ksp->cnvP;
1436:   return(0);
1437: }

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

1445:    Collective on KSP

1447:    Input Parameter:
1448: .  ctx - iterative context obtained from KSPCreate()

1450:    Output Parameter: 
1451:    Provide exactly one of
1452: +  v - location to stash solution.   
1453: -  V - the solution is returned in this location. This vector is created 
1454:        internally. This vector should NOT be destroyed by the user with
1455:        VecDestroy().

1457:    Notes:
1458:    This routine can be used in one of two ways
1459: .vb
1460:       KSPBuildSolution(ksp,PETSC_NULL,&V);
1461:    or
1462:       KSPBuildSolution(ksp,v,PETSC_NULL); 
1463: .ve
1464:    In the first case an internal vector is allocated to store the solution
1465:    (the user cannot destroy this vector). In the second case the solution
1466:    is generated in the vector that the user provides. Note that for certain 
1467:    methods, such as KSPCG, the second case requires a copy of the solution,
1468:    while in the first case the call is essentially free since it simply 
1469:    returns the vector where the solution already is stored.

1471:    Level: advanced

1473: .keywords: KSP, build, solution

1475: .seealso: KSPGetSolution(), KSPBuildResidual()
1476: @*/
1477: PetscErrorCode PETSCKSP_DLLEXPORT KSPBuildSolution(KSP ksp,Vec v,Vec *V)
1478: {

1483:   if (!V && !v) SETERRQ(PETSC_ERR_ARG_WRONG,"Must provide either v or V");
1484:   if (!V) V = &v;
1485:   (*ksp->ops->buildsolution)(ksp,v,V);
1486:   return(0);
1487: }

1491: /*@
1492:    KSPBuildResidual - Builds the residual in a vector provided.

1494:    Collective on KSP

1496:    Input Parameter:
1497: .  ksp - iterative context obtained from KSPCreate()

1499:    Output Parameters:
1500: +  v - optional location to stash residual.  If v is not provided,
1501:        then a location is generated.
1502: .  t - work vector.  If not provided then one is generated.
1503: -  V - the residual

1505:    Notes:
1506:    Regardless of whether or not v is provided, the residual is 
1507:    returned in V.

1509:    Level: advanced

1511: .keywords: KSP, build, residual

1513: .seealso: KSPBuildSolution()
1514: @*/
1515: PetscErrorCode PETSCKSP_DLLEXPORT KSPBuildResidual(KSP ksp,Vec t,Vec v,Vec *V)
1516: {
1518:   PetscTruth     flag = PETSC_FALSE;
1519:   Vec            w = v,tt = t;

1523:   if (!w) {
1524:     VecDuplicate(ksp->vec_rhs,&w);
1525:     PetscLogObjectParent((PetscObject)ksp,w);
1526:   }
1527:   if (!tt) {
1528:     VecDuplicate(ksp->vec_sol,&tt); flag = PETSC_TRUE;
1529:     PetscLogObjectParent((PetscObject)ksp,tt);
1530:   }
1531:   (*ksp->ops->buildresidual)(ksp,tt,w,V);
1532:   if (flag) {VecDestroy(tt);}
1533:   return(0);
1534: }

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

1542:    Collective on KSP

1544:    Input Parameter:
1545: +  ksp - the KSP context
1546: -  scale - PETSC_TRUE or PETSC_FALSE

1548:    Options Database Key:
1549: +   -ksp_diagonal_scale - 
1550: -   -ksp_diagonal_scale_fix - scale the matrix back AFTER the solve 


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

1557:     This routine is only used if the matrix and preconditioner matrix are
1558:     the same thing.

1560:     This should NOT be used within the SNES solves if you are using a line
1561:     search.
1562:  
1563:     If you use this with the PCType Eisenstat preconditioner than you can 
1564:     use the PCEisenstatNoDiagonalScaling() option, or -pc_eisenstat_no_diagonal_scaling
1565:     to save some unneeded, redundant flops.

1567:    Level: intermediate

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

1571: .seealso: KSPGetDiagonalScale(), KSPSetDiagonalScaleFix()
1572: @*/
1573: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetDiagonalScale(KSP ksp,PetscTruth scale)
1574: {
1577:   ksp->dscale = scale;
1578:   return(0);
1579: }

1583: /*@C
1584:    KSPGetDiagonalScale - Checks if KSP solver scales the matrix and
1585:                           right hand side

1587:    Not Collective

1589:    Input Parameter:
1590: .  ksp - the KSP context

1592:    Output Parameter:
1593: .  scale - PETSC_TRUE or PETSC_FALSE

1595:    Notes:
1596:     BE CAREFUL with this routine: it actually scales the matrix and right 
1597:     hand side that define the system. After the system is solved the matrix
1598:     and right hand side remain scaled.

1600:     This routine is only used if the matrix and preconditioner matrix are
1601:     the same thing.

1603:    Level: intermediate

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

1607: .seealso: KSPSetDiagonalScale(), KSPSetDiagonalScaleFix()
1608: @*/
1609: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetDiagonalScale(KSP ksp,PetscTruth *scale)
1610: {
1614:   *scale = ksp->dscale;
1615:   return(0);
1616: }

1620: /*@
1621:    KSPSetDiagonalScaleFix - Tells KSP to diagonally scale the system
1622:      back after solving.

1624:    Collective on KSP

1626:    Input Parameter:
1627: +  ksp - the KSP context
1628: -  fix - PETSC_TRUE to scale back after the system solve, PETSC_FALSE to not 
1629:          rescale (default)

1631:    Notes:
1632:      Must be called after KSPSetDiagonalScale()

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

1639:     This routine is only used if the matrix and preconditioner matrix are
1640:     the same thing.

1642:    Level: intermediate

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

1646: .seealso: KSPGetDiagonalScale(), KSPSetDiagonalScale(), KSPGetDiagonalScaleFix()
1647: @*/
1648: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetDiagonalScaleFix(KSP ksp,PetscTruth fix)
1649: {
1652:   ksp->dscalefix = fix;
1653:   return(0);
1654: }

1658: /*@
1659:    KSPGetDiagonalScaleFix - Determines if KSP diagonally scales the system
1660:      back after solving.

1662:    Collective on KSP

1664:    Input Parameter:
1665: .  ksp - the KSP context

1667:    Output Parameter:
1668: .  fix - PETSC_TRUE to scale back after the system solve, PETSC_FALSE to not 
1669:          rescale (default)

1671:    Notes:
1672:      Must be called after KSPSetDiagonalScale()

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

1679:     This routine is only used if the matrix and preconditioner matrix are
1680:     the same thing.

1682:    Level: intermediate

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

1686: .seealso: KSPGetDiagonalScale(), KSPSetDiagonalScale(), KSPSetDiagonalScaleFix()
1687: @*/
1688: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetDiagonalScaleFix(KSP ksp,PetscTruth *fix)
1689: {
1693:   *fix = ksp->dscalefix;
1694:   return(0);
1695: }