Actual source code: itfunc.c

  1: #define PETSCKSP_DLL

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

 7:  #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:   if (!ksp->pc) {KSPGetPC(ksp,&ksp->pc);}
159:   PCSetUpOnBlocks(ksp->pc);
160:   return(0);
161: }

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

169:    Collective on KSP

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

174:    Level: developer

176: .keywords: KSP, setup

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


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

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

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

196:   PetscLogEventBegin(KSP_SetUp,ksp,ksp->vec_rhs,ksp->vec_sol,0);

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

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

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

253: /*@
254:    KSPSolve - Solves linear system.

256:    Collective on KSP

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

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

274:    Notes:

276:    The operator is specified with PCSetOperators().

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

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

291:    Level: beginner

293: .keywords: KSP, solve, linear system

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


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

324:   PetscOptionsHasName(((PetscObject)ksp)->prefix,"-ksp_view_binary",&flg);
325:   if (flg) {
326:     Mat mat;
327:     PCGetOperators(ksp->pc,&mat,PETSC_NULL,PETSC_NULL);
328:     MatView(mat,PETSC_VIEWER_BINARY_(((PetscObject)ksp)->comm));
329:     VecView(ksp->vec_rhs,PETSC_VIEWER_BINARY_(((PetscObject)ksp)->comm));
330:   }
331:   PetscLogEventBegin(KSP_Solve,ksp,ksp->vec_rhs,ksp->vec_sol,0);

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

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

346:   ksp->transpose_solve = PETSC_FALSE;

348:   if (ksp->guess) {
349:     KSPFischerGuessFormGuess(ksp->guess,ksp->vec_rhs,ksp->vec_sol);
350:     ksp->guess_zero = PETSC_FALSE;
351:   }
352:   /* KSPSetUp() scales the matrix if needed */
353:   KSPSetUp(ksp);
354:   KSPSetUpOnBlocks(ksp);

356:   /* diagonal scale RHS if called for */
357:   if (ksp->dscale) {
358:     VecPointwiseMult(ksp->vec_rhs,ksp->vec_rhs,ksp->diagonal);
359:     /* second time in, but matrix was scaled back to original */
360:     if (ksp->dscalefix && ksp->dscalefix2) {
361:       Mat mat;

363:       PCGetOperators(ksp->pc,&mat,PETSC_NULL,PETSC_NULL);
364:       MatDiagonalScale(mat,ksp->diagonal,ksp->diagonal);
365:     }

367:     /*  scale initial guess */
368:     if (!ksp->guess_zero) {
369:       if (!ksp->truediagonal) {
370:         VecDuplicate(ksp->diagonal,&ksp->truediagonal);
371:         VecCopy(ksp->diagonal,ksp->truediagonal);
372:         VecReciprocal(ksp->truediagonal);
373:       }
374:       VecPointwiseMult(ksp->vec_sol,ksp->vec_sol,ksp->truediagonal);
375:     }
376:   }
377:   PCPreSolve(ksp->pc,ksp);

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

398:   /* diagonal scale solution if called for */
399:   if (ksp->dscale) {
400:     VecPointwiseMult(ksp->vec_sol,ksp->vec_sol,ksp->diagonal);
401:     /* unscale right hand side and matrix */
402:     if (ksp->dscalefix) {
403:       Mat mat;

405:       VecReciprocal(ksp->diagonal);
406:       VecPointwiseMult(ksp->vec_rhs,ksp->vec_rhs,ksp->diagonal);
407:       PCGetOperators(ksp->pc,&mat,PETSC_NULL,PETSC_NULL);
408:       MatDiagonalScale(mat,ksp->diagonal,ksp->diagonal);
409:       VecReciprocal(ksp->diagonal);
410:       ksp->dscalefix2 = PETSC_TRUE;
411:     }
412:   }
413:   PetscLogEventEnd(KSP_Solve,ksp,ksp->vec_rhs,ksp->vec_sol,0);

415:   if (ksp->guess) {
416:     KSPFischerGuessUpdate(ksp->guess,ksp->vec_sol);
417:   }

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

421:   PetscOptionsHasName(((PetscObject)ksp)->prefix,"-ksp_compute_eigenvalues",&flag1);
422:   PetscOptionsHasName(((PetscObject)ksp)->prefix,"-ksp_plot_eigenvalues",&flag2);
423:   if (flag1 || flag2) {
424:     PetscInt   nits,n,i,neig;
425:     PetscReal *r,*c;
426: 
427:     KSPGetIterationNumber(ksp,&nits);
428:     n = nits+2;

430:     if (!n) {
431:       PetscPrintf(((PetscObject)ksp)->comm,"Zero iterations in solver, cannot approximate any eigenvalues\n");
432:     } else {
433:       PetscMalloc(2*n*sizeof(PetscReal),&r);
434:       c = r + n;
435:       KSPComputeEigenvalues(ksp,n,r,c,&neig);
436:       if (flag1) {
437:         PetscPrintf(((PetscObject)ksp)->comm,"Iteratively computed eigenvalues\n");
438:         for (i=0; i<neig; i++) {
439:           if (c[i] >= 0.0) {PetscPrintf(((PetscObject)ksp)->comm,"%G + %Gi\n",r[i],c[i]);}
440:           else             {PetscPrintf(((PetscObject)ksp)->comm,"%G - %Gi\n",r[i],-c[i]);}
441:         }
442:       }
443:       if (flag2 && !rank) {
444:         PetscDraw   draw;
445:         PetscDrawSP drawsp;

447:         PetscViewerDrawOpen(PETSC_COMM_SELF,0,"Iteratively Computed Eigenvalues",PETSC_DECIDE,PETSC_DECIDE,300,300,&viewer);
448:         PetscViewerDrawGetDraw(viewer,0,&draw);
449:         PetscDrawSPCreate(draw,1,&drawsp);
450:         for (i=0; i<neig; i++) {
451:           PetscDrawSPAddPoint(drawsp,r+i,c+i);
452:         }
453:         PetscDrawSPDraw(drawsp);
454:         PetscDrawSPDestroy(drawsp);
455:         PetscViewerDestroy(viewer);
456:       }
457:       PetscFree(r);
458:     }
459:   }

461:   PetscOptionsHasName(((PetscObject)ksp)->prefix,"-ksp_compute_eigenvalues_explicitly",&flag1);
462:   PetscOptionsHasName(((PetscObject)ksp)->prefix,"-ksp_plot_eigenvalues_explicitly",&flag2);
463:   if (flag1 || flag2) {
464:     PetscInt  n,i;
465:     PetscReal *r,*c;
466:     VecGetSize(ksp->vec_sol,&n);
467:     PetscMalloc(2*n*sizeof(PetscReal),&r);
468:     c = r + n;
469:     KSPComputeEigenvaluesExplicitly(ksp,n,r,c);
470:     if (flag1) {
471:       PetscPrintf(((PetscObject)ksp)->comm,"Explicitly computed eigenvalues\n");
472:       for (i=0; i<n; i++) {
473:         if (c[i] >= 0.0) {PetscPrintf(((PetscObject)ksp)->comm,"%G + %Gi\n",r[i],c[i]);}
474:         else             {PetscPrintf(((PetscObject)ksp)->comm,"%G - %Gi\n",r[i],-c[i]);}
475:       }
476:     }
477:     if (flag2 && !rank) {
478:       PetscDraw   draw;
479:       PetscDrawSP drawsp;

481:       PetscViewerDrawOpen(PETSC_COMM_SELF,0,"Explicitly Computed Eigenvalues",0,320,300,300,&viewer);
482:       PetscViewerDrawGetDraw(viewer,0,&draw);
483:       PetscDrawSPCreate(draw,1,&drawsp);
484:       for (i=0; i<n; i++) {
485:         PetscDrawSPAddPoint(drawsp,r+i,c+i);
486:       }
487:       PetscDrawSPDraw(drawsp);
488:       PetscDrawSPDestroy(drawsp);
489:       PetscViewerDestroy(viewer);
490:     }
491:     PetscFree(r);
492:   }

494:   PetscOptionsHasName(((PetscObject)ksp)->prefix,"-ksp_view_operator",&flag2);
495:   if (flag2) {
496:     Mat         A,B;
497:     PetscViewer viewer;

499:     PCGetOperators(ksp->pc,&A,PETSC_NULL,PETSC_NULL);
500:     MatComputeExplicitOperator(A,&B);
501:     PetscViewerASCIIGetStdout(((PetscObject)ksp)->comm,&viewer);
502:     PetscViewerPushFormat(viewer,PETSC_VIEWER_ASCII_MATLAB);
503:     MatView(B,viewer);
504:     PetscViewerPopFormat(viewer);
505:     MatDestroy(B);
506:   }
507:   PetscOptionsHasName(((PetscObject)ksp)->prefix,"-ksp_view_operator_binary",&flag2);
508:   if (flag2) {
509:     Mat A,B;
510:     PCGetOperators(ksp->pc,&A,PETSC_NULL,PETSC_NULL);
511:     MatComputeExplicitOperator(A,&B);
512:     MatView(B,PETSC_VIEWER_BINARY_(((PetscObject)ksp)->comm));
513:     MatDestroy(B);
514:   }
515:   PetscOptionsHasName(((PetscObject)ksp)->prefix,"-ksp_view_preconditioned_operator_binary",&flag2);
516:   if (flag2) {
517:     Mat B;
518:     KSPComputeExplicitOperator(ksp,&B);
519:     MatView(B,PETSC_VIEWER_BINARY_(((PetscObject)ksp)->comm));
520:     MatDestroy(B);
521:   }
522:   PetscOptionsHasName(((PetscObject)ksp)->prefix,"-ksp_view_preconditioner_binary",&flag2);
523:   if (flag2) {
524:     Mat B;
525:     PCComputeExplicitOperator(ksp->pc,&B);
526:     MatView(B,PETSC_VIEWER_BINARY_(((PetscObject)ksp)->comm));
527:     MatDestroy(B);
528:   }
529:   if (!viewed) {
530:     PetscOptionsGetString(((PetscObject)ksp)->prefix,"-ksp_view",filename,PETSC_MAX_PATH_LEN,&flg);
531:     if (flg && !PetscPreLoadingOn) {
532:       PetscViewerASCIIOpen(((PetscObject)ksp)->comm,filename,&viewer);
533:       KSPView(ksp,viewer);
534:       PetscViewerDestroy(viewer);
535:     }
536:   }
537:   PetscOptionsHasName(((PetscObject)ksp)->prefix,"-ksp_final_residual",&flg);
538:   if (flg) {
539:     Mat         A;
540:     Vec         t;
541:     PetscReal   norm;
542:     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");
543:     PCGetOperators(ksp->pc,&A,0,0);
544:     VecDuplicate(ksp->vec_sol,&t);
545:     KSP_MatMult(ksp,A,ksp->vec_sol,t);
546:     VecWAXPY(t,-1.0,t,ksp->vec_rhs);
547:     VecNorm(t,NORM_2,&norm);
548:     VecDestroy(t);
549:     PetscPrintf(((PetscObject)ksp)->comm,"KSP final norm of residual %G\n",norm);
550:   }
551:   if (inXisinB) {
552:     VecCopy(x,b);
553:     VecDestroy(x);
554:   }
555:   return(0);
556: }

560: /*@
561:    KSPSolveTranspose - Solves the transpose of a linear system. Usually
562:    accessed through KSPSolveTranspose().

564:    Collective on KSP

566:    Input Parameter:
567: +  ksp - iterative context obtained from KSPCreate()
568: .  b - right hand side vector
569: -  x - solution vector

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

575:    Level: developer

577: .keywords: KSP, solve, linear system

579: .seealso: KSPCreate(), KSPSetUp(), KSPDestroy(), KSPSetTolerances(), KSPDefaultConverged(),
580:           KSPSolve()
581: @*/
582: PetscErrorCode  KSPSolveTranspose(KSP ksp,Vec b,Vec x)
583: {
585:   PetscTruth     inXisinB=PETSC_FALSE;

591:   if (x == b) {
592:     VecDuplicate(b,&x);
593:     inXisinB = PETSC_TRUE;
594:   }
595:   PetscObjectReference((PetscObject)b);
596:   PetscObjectReference((PetscObject)x);
597:   if (ksp->vec_rhs) {VecDestroy(ksp->vec_rhs);}
598:   if (ksp->vec_sol) {VecDestroy(ksp->vec_sol);}
599:   ksp->vec_rhs = b;
600:   ksp->vec_sol = x;
601:   ksp->transpose_solve = PETSC_TRUE;
602:   KSPSetUp(ksp);
603:   if (ksp->guess_zero) { VecSet(ksp->vec_sol,0.0);}
604:   (*ksp->ops->solve)(ksp);
605:   if (inXisinB) {
606:     VecCopy(x,b);
607:     VecDestroy(x);
608:   }
609:   return(0);
610: }

614: /*@
615:    KSPDestroy - Destroys KSP context.

617:    Collective on KSP

619:    Input Parameter:
620: .  ksp - iterative context obtained from KSPCreate()

622:    Level: beginner

624: .keywords: KSP, destroy

626: .seealso: KSPCreate(), KSPSetUp(), KSPSolve()
627: @*/
628: PetscErrorCode  KSPDestroy(KSP ksp)
629: {

634:   if (--((PetscObject)ksp)->refct > 0) return(0);

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

639:   if (ksp->ops->destroy) {
640:     (*ksp->ops->destroy)(ksp);
641:   }
642:   if (ksp->guess) {
643:     KSPFischerGuessDestroy(ksp->guess);
644:   }
645:   PetscFree(ksp->res_hist_alloc);
646:   KSPMonitorCancel(ksp);
647:   if (ksp->pc) {PCDestroy(ksp->pc);}
648:   if (ksp->vec_rhs) {VecDestroy(ksp->vec_rhs);}
649:   if (ksp->vec_sol) {VecDestroy(ksp->vec_sol);}
650:   if (ksp->diagonal) {VecDestroy(ksp->diagonal);}
651:   if (ksp->truediagonal) {VecDestroy(ksp->truediagonal);}
652:   if (ksp->nullsp) {MatNullSpaceDestroy(ksp->nullsp);}
653:   if (ksp->convergeddestroy) {(*ksp->convergeddestroy)(ksp->cnvP);}
654:   PetscHeaderDestroy(ksp);
655:   return(0);
656: }

660: /*@
661:     KSPSetPreconditionerSide - Sets the preconditioning side.

663:     Collective on KSP

665:     Input Parameter:
666: .   ksp - iterative context obtained from KSPCreate()

668:     Output Parameter:
669: .   side - the preconditioning side, where side is one of
670: .vb
671:       PC_LEFT - left preconditioning (default)
672:       PC_RIGHT - right preconditioning
673:       PC_SYMMETRIC - symmetric preconditioning
674: .ve

676:     Options Database Keys:
677: +   -ksp_left_pc - Sets left preconditioning
678: .   -ksp_right_pc - Sets right preconditioning
679: -   -ksp_symmetric_pc - Sets symmetric preconditioning

681:     Notes:
682:     Left preconditioning is used by default.  Symmetric preconditioning is
683:     currently available only for the KSPQCG method. Note, however, that
684:     symmetric preconditioning can be emulated by using either right or left
685:     preconditioning and a pre or post processing step.

687:     Level: intermediate

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

691: .seealso: KSPGetPreconditionerSide()
692: @*/
693: PetscErrorCode  KSPSetPreconditionerSide(KSP ksp,PCSide side)
694: {
697:   ksp->pc_side = side;
698:   return(0);
699: }

703: /*@
704:     KSPGetPreconditionerSide - Gets the preconditioning side.

706:     Not Collective

708:     Input Parameter:
709: .   ksp - iterative context obtained from KSPCreate()

711:     Output Parameter:
712: .   side - the preconditioning side, where side is one of
713: .vb
714:       PC_LEFT - left preconditioning (default)
715:       PC_RIGHT - right preconditioning
716:       PC_SYMMETRIC - symmetric preconditioning
717: .ve

719:     Level: intermediate

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

723: .seealso: KSPSetPreconditionerSide()
724: @*/
725: PetscErrorCode  KSPGetPreconditionerSide(KSP ksp,PCSide *side)
726: {
730:   *side = ksp->pc_side;
731:   return(0);
732: }

736: /*@
737:    KSPGetTolerances - Gets the relative, absolute, divergence, and maximum
738:    iteration tolerances used by the default KSP convergence tests. 

740:    Not Collective

742:    Input Parameter:
743: .  ksp - the Krylov subspace context
744:   
745:    Output Parameters:
746: +  rtol - the relative convergence tolerance
747: .  abstol - the absolute convergence tolerance
748: .  dtol - the divergence tolerance
749: -  maxits - maximum number of iterations

751:    Notes:
752:    The user can specify PETSC_NULL for any parameter that is not needed.

754:    Level: intermediate

756: .keywords: KSP, get, tolerance, absolute, relative, divergence, convergence,
757:            maximum, iterations

759: .seealso: KSPSetTolerances()
760: @*/
761: PetscErrorCode  KSPGetTolerances(KSP ksp,PetscReal *rtol,PetscReal *abstol,PetscReal *dtol,PetscInt *maxits)
762: {
765:   if (abstol)   *abstol   = ksp->abstol;
766:   if (rtol)   *rtol   = ksp->rtol;
767:   if (dtol)   *dtol   = ksp->divtol;
768:   if (maxits) *maxits = ksp->max_it;
769:   return(0);
770: }

774: /*@
775:    KSPSetTolerances - Sets the relative, absolute, divergence, and maximum
776:    iteration tolerances used by the default KSP convergence testers. 

778:    Collective on KSP

780:    Input Parameters:
781: +  ksp - the Krylov subspace context
782: .  rtol - the relative convergence tolerance
783:    (relative decrease in the residual norm)
784: .  abstol - the absolute convergence tolerance 
785:    (absolute size of the residual norm)
786: .  dtol - the divergence tolerance
787:    (amount residual can increase before KSPDefaultConverged()
788:    concludes that the method is diverging)
789: -  maxits - maximum number of iterations to use

791:    Options Database Keys:
792: +  -ksp_atol <abstol> - Sets abstol
793: .  -ksp_rtol <rtol> - Sets rtol
794: .  -ksp_divtol <dtol> - Sets dtol
795: -  -ksp_max_it <maxits> - Sets maxits

797:    Notes:
798:    Use PETSC_DEFAULT to retain the default value of any of the tolerances.

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

804:    Level: intermediate

806: .keywords: KSP, set, tolerance, absolute, relative, divergence, 
807:            convergence, maximum, iterations

809: .seealso: KSPGetTolerances(), KSPDefaultConverged(), KSPSetConvergenceTest()
810: @*/
811: PetscErrorCode  KSPSetTolerances(KSP ksp,PetscReal rtol,PetscReal abstol,PetscReal dtol,PetscInt maxits)
812: {
815:   if (abstol != PETSC_DEFAULT)   ksp->abstol   = abstol;
816:   if (rtol != PETSC_DEFAULT)   ksp->rtol   = rtol;
817:   if (dtol != PETSC_DEFAULT)   ksp->divtol = dtol;
818:   if (maxits != PETSC_DEFAULT) ksp->max_it = maxits;
819:   return(0);
820: }

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

829:    Collective on KSP

831:    Input Parameters:
832: +  ksp - iterative context obtained from KSPCreate()
833: -  flg - PETSC_TRUE indicates the guess is non-zero, PETSC_FALSE indicates the guess is zero

835:    Level: beginner

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

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

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

854: /*@
855:    KSPGetInitialGuessNonzero - Determines whether the KSP solver is using
856:    a zero initial guess.

858:    Not Collective

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

863:    Output Parameter:
864: .  flag - PETSC_TRUE if guess is nonzero, else PETSC_FALSE

866:    Level: intermediate

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

870: .seealso: KSPSetInitialGuessNonzero(), KSPSetInitialGuessKnoll(), KSPGetInitialGuessKnoll()
871: @*/
872: PetscErrorCode  KSPGetInitialGuessNonzero(KSP ksp,PetscTruth *flag)
873: {
877:   if (ksp->guess_zero) *flag = PETSC_FALSE;
878:   else                 *flag = PETSC_TRUE;
879:   return(0);
880: }

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

887:    Collective on KSP

889:    Input Parameters:
890: +  ksp - iterative context obtained from KSPCreate()
891: -  flg - PETSC_TRUE or PETSC_FALSE

893:    Level: advanced


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

898: .seealso: KSPGetInitialGuessKnoll(), KSPSetInitialGuessNonzero(), KSPGetInitialGuessNonzero()
899: @*/
900: PetscErrorCode  KSPSetInitialGuessKnoll(KSP ksp,PetscTruth flg)
901: {
904:   ksp->guess_knoll   = flg;
905:   return(0);
906: }

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

914:    Not Collective

916:    Input Parameter:
917: .  ksp - iterative context obtained from KSPCreate()

919:    Output Parameter:
920: .  flag - PETSC_TRUE if using Knoll trick, else PETSC_FALSE

922:    Level: advanced

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

926: .seealso: KSPSetInitialGuessKnoll(), KSPSetInitialGuessNonzero(), KSPGetInitialGuessNonzero()
927: @*/
928: PetscErrorCode  KSPGetInitialGuessKnoll(KSP ksp,PetscTruth *flag)
929: {
933:   *flag = ksp->guess_knoll;
934:   return(0);
935: }

939: /*@
940:    KSPGetComputeSingularValues - Gets the flag indicating whether the extreme singular 
941:    values will be calculated via a Lanczos or Arnoldi process as the linear 
942:    system is solved.

944:    Collective on KSP

946:    Input Parameter:
947: .  ksp - iterative context obtained from KSPCreate()

949:    Output Parameter:
950: .  flg - PETSC_TRUE or PETSC_FALSE

952:    Options Database Key:
953: .  -ksp_monitor_singular_value - Activates KSPSetComputeSingularValues()

955:    Notes:
956:    Currently this option is not valid for all iterative methods.

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

962:    Level: advanced

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

966: .seealso: KSPComputeExtremeSingularValues(), KSPMonitorSingularValue()
967: @*/
968: PetscErrorCode  KSPGetComputeSingularValues(KSP ksp,PetscTruth *flg)
969: {
973:   *flg = ksp->calc_sings;
974:   return(0);
975: }

979: /*@
980:    KSPSetComputeSingularValues - Sets a flag so that the extreme singular 
981:    values will be calculated via a Lanczos or Arnoldi process as the linear 
982:    system is solved.

984:    Collective on KSP

986:    Input Parameters:
987: +  ksp - iterative context obtained from KSPCreate()
988: -  flg - PETSC_TRUE or PETSC_FALSE

990:    Options Database Key:
991: .  -ksp_monitor_singular_value - Activates KSPSetComputeSingularValues()

993:    Notes:
994:    Currently this option is not valid for all iterative methods.

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

1000:    Level: advanced

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

1004: .seealso: KSPComputeExtremeSingularValues(), KSPMonitorSingularValue()
1005: @*/
1006: PetscErrorCode  KSPSetComputeSingularValues(KSP ksp,PetscTruth flg)
1007: {
1010:   ksp->calc_sings  = flg;
1011:   return(0);
1012: }

1016: /*@
1017:    KSPGetComputeEigenvalues - Gets the flag indicating that the extreme eigenvalues
1018:    values will be calculated via a Lanczos or Arnoldi process as the linear 
1019:    system is solved.

1021:    Collective on KSP

1023:    Input Parameter:
1024: .  ksp - iterative context obtained from KSPCreate()

1026:    Output Parameter:
1027: .  flg - PETSC_TRUE or PETSC_FALSE

1029:    Notes:
1030:    Currently this option is not valid for all iterative methods.

1032:    Level: advanced

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

1036: .seealso: KSPComputeEigenvalues(), KSPComputeEigenvaluesExplicitly()
1037: @*/
1038: PetscErrorCode  KSPGetComputeEigenvalues(KSP ksp,PetscTruth *flg)
1039: {
1043:   *flg = ksp->calc_sings;
1044:   return(0);
1045: }

1049: /*@
1050:    KSPSetComputeEigenvalues - Sets a flag so that the extreme eigenvalues
1051:    values will be calculated via a Lanczos or Arnoldi process as the linear 
1052:    system is solved.

1054:    Collective on KSP

1056:    Input Parameters:
1057: +  ksp - iterative context obtained from KSPCreate()
1058: -  flg - PETSC_TRUE or PETSC_FALSE

1060:    Notes:
1061:    Currently this option is not valid for all iterative methods.

1063:    Level: advanced

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

1067: .seealso: KSPComputeEigenvalues(), KSPComputeEigenvaluesExplicitly()
1068: @*/
1069: PetscErrorCode  KSPSetComputeEigenvalues(KSP ksp,PetscTruth flg)
1070: {
1073:   ksp->calc_sings  = flg;
1074:   return(0);
1075: }

1079: /*@
1080:    KSPGetRhs - Gets the right-hand-side vector for the linear system to
1081:    be solved.

1083:    Not Collective

1085:    Input Parameter:
1086: .  ksp - iterative context obtained from KSPCreate()

1088:    Output Parameter:
1089: .  r - right-hand-side vector

1091:    Level: developer

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

1095: .seealso: KSPGetSolution(), KSPSolve()
1096: @*/
1097: PetscErrorCode  KSPGetRhs(KSP ksp,Vec *r)
1098: {
1102:   *r = ksp->vec_rhs;
1103:   return(0);
1104: }

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

1113:    Not Collective

1115:    Input Parameters:
1116: .  ksp - iterative context obtained from KSPCreate()

1118:    Output Parameters:
1119: .  v - solution vector

1121:    Level: developer

1123: .keywords: KSP, get, solution

1125: .seealso: KSPGetRhs(),  KSPBuildSolution(), KSPSolve()
1126: @*/
1127: PetscErrorCode  KSPGetSolution(KSP ksp,Vec *v)
1128: {
1132:   *v = ksp->vec_sol;
1133:   return(0);
1134: }

1138: /*@
1139:    KSPSetPC - Sets the preconditioner to be used to calculate the 
1140:    application of the preconditioner on a vector. 

1142:    Collective on KSP

1144:    Input Parameters:
1145: +  ksp - iterative context obtained from KSPCreate()
1146: -  pc   - the preconditioner object

1148:    Notes:
1149:    Use KSPGetPC() to retrieve the preconditioner context (for example,
1150:    to free it at the end of the computations).

1152:    Level: developer

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

1156: .seealso: KSPGetPC()
1157: @*/
1158: PetscErrorCode  KSPSetPC(KSP ksp,PC pc)
1159: {

1166:   PetscObjectReference((PetscObject)pc);
1167:   if (ksp->pc) {PCDestroy(ksp->pc);}
1168:   ksp->pc = pc;
1169:   return(0);
1170: }

1174: /*@
1175:    KSPGetPC - Returns a pointer to the preconditioner context
1176:    set with KSPSetPC().

1178:    Not Collective

1180:    Input Parameters:
1181: .  ksp - iterative context obtained from KSPCreate()

1183:    Output Parameter:
1184: .  pc - preconditioner context

1186:    Level: developer

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

1190: .seealso: KSPSetPC()
1191: @*/
1192: PetscErrorCode  KSPGetPC(KSP ksp,PC *pc)
1193: {

1199:   if (!ksp->pc) {
1200:     PCCreate(((PetscObject)ksp)->comm,&ksp->pc);
1201:     PetscObjectIncrementTabLevel((PetscObject)ksp->pc,(PetscObject)ksp,0);
1202:   }
1203:   *pc = ksp->pc;
1204:   return(0);
1205: }

1209: /*@C
1210:    KSPMonitorSet - Sets an ADDITIONAL function to be called at every iteration to monitor 
1211:    the residual/error etc.
1212:       
1213:    Collective on KSP

1215:    Input Parameters:
1216: +  ksp - iterative context obtained from KSPCreate()
1217: .  monitor - pointer to function (if this is PETSC_NULL, it turns off monitoring
1218: .  mctx    - [optional] context for private data for the
1219:              monitor routine (use PETSC_NULL if no context is desired)
1220: -  monitordestroy - [optional] routine that frees monitor context
1221:           (may be PETSC_NULL)

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

1226: +  ksp - iterative context obtained from KSPCreate()
1227: .  it - iteration number
1228: .  rnorm - (estimated) 2-norm of (preconditioned) residual
1229: -  mctx  - optional monitoring context, as set by KSPMonitorSet()

1231:    Options Database Keys:
1232: +    -ksp_monitor        - sets KSPMonitorDefault()
1233: .    -ksp_monitor_true_residual    - sets KSPMonitorTrueResidualNorm()
1234: .    -ksp_monitor_draw    - sets line graph monitor,
1235:                            uses KSPMonitorLGCreate()
1236: .    -ksp_monitor_draw_true_residual   - sets line graph monitor,
1237:                            uses KSPMonitorLGCreate()
1238: .    -ksp_monitor_singular_value    - sets KSPMonitorSingularValue()
1239: -    -ksp_monitor_cancel - cancels all monitors that have
1240:                           been hardwired into a code by 
1241:                           calls to KSPMonitorSet(), but
1242:                           does not cancel those set via
1243:                           the options database.

1245:    Notes:  
1246:    The default is to do nothing.  To print the residual, or preconditioned 
1247:    residual if KSPSetNormType(ksp,KSP_NORM_PRECONDITIONED) was called, use 
1248:    KSPMonitorDefault() as the monitoring routine, with a null monitoring 
1249:    context. 

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

1255:    Fortran notes: Only a single monitor function can be set for each KSP object

1257:    Level: beginner

1259: .keywords: KSP, set, monitor

1261: .seealso: KSPMonitorDefault(), KSPMonitorLGCreate(), KSPMonitorCancel()
1262: @*/
1263: PetscErrorCode  KSPMonitorSet(KSP ksp,PetscErrorCode (*monitor)(KSP,PetscInt,PetscReal,void*),void *mctx,PetscErrorCode (*monitordestroy)(void*))
1264: {
1265:   PetscInt i;

1269:   if (ksp->numbermonitors >= MAXKSPMONITORS) {
1270:     SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Too many KSP monitors set");
1271:   }
1272:   for (i=0; i<ksp->numbermonitors;i++) {
1273:     if (monitor == ksp->monitor[i] && monitordestroy == ksp->monitordestroy[i] && mctx == ksp->monitorcontext[i]) return(0);

1275:     /* check if both default monitors that share common ASCII viewer */
1276:     if (monitor == ksp->monitor[i] && monitor == KSPMonitorDefault) {
1277:       if (mctx && ksp->monitorcontext[i]) {
1278:         PetscErrorCode          ierr;
1279:         PetscViewerASCIIMonitor viewer1 = (PetscViewerASCIIMonitor) mctx;
1280:         PetscViewerASCIIMonitor viewer2 = (PetscViewerASCIIMonitor) ksp->monitorcontext[i];
1281:         if (viewer1->viewer == viewer2->viewer) {
1282:           (*monitordestroy)(mctx);
1283:           return(0);
1284:         }
1285:       }
1286:     }
1287:   }
1288:   ksp->monitor[ksp->numbermonitors]           = monitor;
1289:   ksp->monitordestroy[ksp->numbermonitors]    = monitordestroy;
1290:   ksp->monitorcontext[ksp->numbermonitors++]  = (void*)mctx;
1291:   return(0);
1292: }

1296: /*@
1297:    KSPMonitorCancel - Clears all monitors for a KSP object.

1299:    Collective on KSP

1301:    Input Parameters:
1302: .  ksp - iterative context obtained from KSPCreate()

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

1309:    Level: intermediate

1311: .keywords: KSP, set, monitor

1313: .seealso: KSPMonitorDefault(), KSPMonitorLGCreate(), KSPMonitorSet()
1314: @*/
1315: PetscErrorCode  KSPMonitorCancel(KSP ksp)
1316: {
1318:   PetscInt       i;

1322:   for (i=0; i<ksp->numbermonitors; i++) {
1323:     if (ksp->monitordestroy[i]) {
1324:       (*ksp->monitordestroy[i])(ksp->monitorcontext[i]);
1325:     }
1326:   }
1327:   ksp->numbermonitors = 0;
1328:   return(0);
1329: }

1333: /*@C
1334:    KSPGetMonitorContext - Gets the monitoring context, as set by 
1335:    KSPMonitorSet() for the FIRST monitor only.

1337:    Not Collective

1339:    Input Parameter:
1340: .  ksp - iterative context obtained from KSPCreate()

1342:    Output Parameter:
1343: .  ctx - monitoring context

1345:    Level: intermediate

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

1349: .seealso: KSPMonitorDefault(), KSPMonitorLGCreate()
1350: @*/
1351: PetscErrorCode  KSPGetMonitorContext(KSP ksp,void **ctx)
1352: {
1355:   *ctx =      (ksp->monitorcontext[0]);
1356:   return(0);
1357: }

1361: /*@
1362:    KSPSetResidualHistory - Sets the array used to hold the residual history.
1363:    If set, this array will contain the residual norms computed at each
1364:    iteration of the solver.

1366:    Not Collective

1368:    Input Parameters:
1369: +  ksp - iterative context obtained from KSPCreate()
1370: .  a   - array to hold history
1371: .  na  - size of a
1372: -  reset - PETSC_TRUE indicates the history counter is reset to zero
1373:            for each new linear solve

1375:    Level: advanced

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

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

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

1385: .seealso: KSPGetResidualHistory()

1387: @*/
1388: PetscErrorCode  KSPSetResidualHistory(KSP ksp,PetscReal a[],PetscInt na,PetscTruth reset)
1389: {


1395:   PetscFree(ksp->res_hist_alloc);
1396:   if (na != PETSC_DECIDE && na != PETSC_DEFAULT && a) {
1397:     ksp->res_hist        = a;
1398:     ksp->res_hist_max    = na;
1399:   } else {
1400:     if (na != PETSC_DECIDE && na != PETSC_DEFAULT)
1401:       ksp->res_hist_max = na;
1402:     else
1403:       ksp->res_hist_max = 10000; /* like default ksp->max_it */
1404:     PetscMalloc(ksp->res_hist_max*sizeof(PetscReal),&ksp->res_hist_alloc);
1405:     ksp->res_hist = ksp->res_hist_alloc;
1406:   }
1407:   ksp->res_hist_len    = 0;
1408:   ksp->res_hist_reset  = reset;

1410:   return(0);
1411: }

1415: /*@C
1416:    KSPGetResidualHistory - Gets the array used to hold the residual history
1417:    and the number of residuals it contains.

1419:    Not Collective

1421:    Input Parameter:
1422: .  ksp - iterative context obtained from KSPCreate()

1424:    Output Parameters:
1425: +  a   - pointer to array to hold history (or PETSC_NULL)
1426: -  na  - number of used entries in a (or PETSC_NULL)

1428:    Level: advanced

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

1433:      The Fortran version of this routine has a calling sequence
1434: $   call KSPGetResidualHistory(KSP ksp, integer na, integer ierr)
1435:     note that you have passed a Fortran array into KSPSetResidualHistory() and you need
1436:     to access the residual values from this Fortran array you provided. Only the na (number of
1437:     residual norms currently held) is set.

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

1441: .seealso: KSPGetResidualHistory()

1443: @*/
1444: PetscErrorCode  KSPGetResidualHistory(KSP ksp,PetscReal *a[],PetscInt *na)
1445: {
1448:   if (a)  *a  = ksp->res_hist;
1449:   if (na) *na = ksp->res_hist_len;
1450:   return(0);
1451: }

1455: /*@C
1456:    KSPSetConvergenceTest - Sets the function to be used to determine
1457:    convergence.  

1459:    Collective on KSP

1461:    Input Parameters:
1462: +  ksp - iterative context obtained from KSPCreate()
1463: .  converge - pointer to int function
1464: .  cctx    - context for private data for the convergence routine (may be null)
1465: -  destroy - a routine for destroying the context (may be null)

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

1470: +  ksp - iterative context obtained from KSPCreate()
1471: .  it - iteration number
1472: .  rnorm - (estimated) 2-norm of (preconditioned) residual
1473: .  reason - the reason why it has converged or diverged
1474: -  cctx  - optional convergence context, as set by KSPSetConvergenceTest()


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

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

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

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

1491:    Level: advanced

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

1495: .seealso: KSPDefaultConverged(), KSPGetConvergenceContext()
1496: @*/
1497: PetscErrorCode  KSPSetConvergenceTest(KSP ksp,PetscErrorCode (*converge)(KSP,PetscInt,PetscReal,KSPConvergedReason*,void*),void *cctx,PetscErrorCode (*destroy)(void*))
1498: {

1503:   if (ksp->convergeddestroy) {
1504:     (*ksp->convergeddestroy)(ksp->cnvP);
1505:   }
1506:   ksp->converged        = converge;
1507:   ksp->convergeddestroy = destroy;
1508:   ksp->cnvP             = (void*)cctx;
1509:   return(0);
1510: }

1514: /*@C
1515:    KSPGetConvergenceContext - Gets the convergence context set with 
1516:    KSPSetConvergenceTest().  

1518:    Not Collective

1520:    Input Parameter:
1521: .  ksp - iterative context obtained from KSPCreate()

1523:    Output Parameter:
1524: .  ctx - monitoring context

1526:    Level: advanced

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

1530: .seealso: KSPDefaultConverged(), KSPSetConvergenceTest()
1531: @*/
1532: PetscErrorCode  KSPGetConvergenceContext(KSP ksp,void **ctx)
1533: {
1536:   *ctx = ksp->cnvP;
1537:   return(0);
1538: }

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

1546:    Collective on KSP

1548:    Input Parameter:
1549: .  ctx - iterative context obtained from KSPCreate()

1551:    Output Parameter: 
1552:    Provide exactly one of
1553: +  v - location to stash solution.   
1554: -  V - the solution is returned in this location. This vector is created 
1555:        internally. This vector should NOT be destroyed by the user with
1556:        VecDestroy().

1558:    Notes:
1559:    This routine can be used in one of two ways
1560: .vb
1561:       KSPBuildSolution(ksp,PETSC_NULL,&V);
1562:    or
1563:       KSPBuildSolution(ksp,v,PETSC_NULL); or KSPBuildSolution(ksp,v,&v);
1564: .ve
1565:    In the first case an internal vector is allocated to store the solution
1566:    (the user cannot destroy this vector). In the second case the solution
1567:    is generated in the vector that the user provides. Note that for certain 
1568:    methods, such as KSPCG, the second case requires a copy of the solution,
1569:    while in the first case the call is essentially free since it simply 
1570:    returns the vector where the solution already is stored. For some methods
1571:    like GMRES this is a reasonably expensive operation and should only be
1572:    used in truly needed.

1574:    Level: advanced

1576: .keywords: KSP, build, solution

1578: .seealso: KSPGetSolution(), KSPBuildResidual()
1579: @*/
1580: PetscErrorCode  KSPBuildSolution(KSP ksp,Vec v,Vec *V)
1581: {

1586:   if (!V && !v) SETERRQ(PETSC_ERR_ARG_WRONG,"Must provide either v or V");
1587:   if (!V) V = &v;
1588:   (*ksp->ops->buildsolution)(ksp,v,V);
1589:   return(0);
1590: }

1594: /*@
1595:    KSPBuildResidual - Builds the residual in a vector provided.

1597:    Collective on KSP

1599:    Input Parameter:
1600: .  ksp - iterative context obtained from KSPCreate()

1602:    Output Parameters:
1603: +  v - optional location to stash residual.  If v is not provided,
1604:        then a location is generated.
1605: .  t - work vector.  If not provided then one is generated.
1606: -  V - the residual

1608:    Notes:
1609:    Regardless of whether or not v is provided, the residual is 
1610:    returned in V.

1612:    Level: advanced

1614: .keywords: KSP, build, residual

1616: .seealso: KSPBuildSolution()
1617: @*/
1618: PetscErrorCode  KSPBuildResidual(KSP ksp,Vec t,Vec v,Vec *V)
1619: {
1621:   PetscTruth     flag = PETSC_FALSE;
1622:   Vec            w = v,tt = t;

1626:   if (!w) {
1627:     VecDuplicate(ksp->vec_rhs,&w);
1628:     PetscLogObjectParent((PetscObject)ksp,w);
1629:   }
1630:   if (!tt) {
1631:     VecDuplicate(ksp->vec_sol,&tt); flag = PETSC_TRUE;
1632:     PetscLogObjectParent((PetscObject)ksp,tt);
1633:   }
1634:   (*ksp->ops->buildresidual)(ksp,tt,w,V);
1635:   if (flag) {VecDestroy(tt);}
1636:   return(0);
1637: }

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

1645:    Collective on KSP

1647:    Input Parameter:
1648: +  ksp - the KSP context
1649: -  scale - PETSC_TRUE or PETSC_FALSE

1651:    Options Database Key:
1652: +   -ksp_diagonal_scale - 
1653: -   -ksp_diagonal_scale_fix - scale the matrix back AFTER the solve 


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

1660:     This routine is only used if the matrix and preconditioner matrix are
1661:     the same thing.

1663:     This should NOT be used within the SNES solves if you are using a line
1664:     search.
1665:  
1666:     If you use this with the PCType Eisenstat preconditioner than you can 
1667:     use the PCEisenstatNoDiagonalScaling() option, or -pc_eisenstat_no_diagonal_scaling
1668:     to save some unneeded, redundant flops.

1670:    Level: intermediate

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

1674: .seealso: KSPGetDiagonalScale(), KSPSetDiagonalScaleFix()
1675: @*/
1676: PetscErrorCode  KSPSetDiagonalScale(KSP ksp,PetscTruth scale)
1677: {
1680:   ksp->dscale = scale;
1681:   return(0);
1682: }

1686: /*@
1687:    KSPGetDiagonalScale - Checks if KSP solver scales the matrix and
1688:                           right hand side

1690:    Not Collective

1692:    Input Parameter:
1693: .  ksp - the KSP context

1695:    Output Parameter:
1696: .  scale - PETSC_TRUE or PETSC_FALSE

1698:    Notes:
1699:     BE CAREFUL with this routine: it actually scales the matrix and right 
1700:     hand side that define the system. After the system is solved the matrix
1701:     and right hand side remain scaled.

1703:     This routine is only used if the matrix and preconditioner matrix are
1704:     the same thing.

1706:    Level: intermediate

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

1710: .seealso: KSPSetDiagonalScale(), KSPSetDiagonalScaleFix()
1711: @*/
1712: PetscErrorCode  KSPGetDiagonalScale(KSP ksp,PetscTruth *scale)
1713: {
1717:   *scale = ksp->dscale;
1718:   return(0);
1719: }

1723: /*@
1724:    KSPSetDiagonalScaleFix - Tells KSP to diagonally scale the system
1725:      back after solving.

1727:    Collective on KSP

1729:    Input Parameter:
1730: +  ksp - the KSP context
1731: -  fix - PETSC_TRUE to scale back after the system solve, PETSC_FALSE to not 
1732:          rescale (default)

1734:    Notes:
1735:      Must be called after KSPSetDiagonalScale()

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

1742:     This routine is only used if the matrix and preconditioner matrix are
1743:     the same thing.

1745:    Level: intermediate

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

1749: .seealso: KSPGetDiagonalScale(), KSPSetDiagonalScale(), KSPGetDiagonalScaleFix()
1750: @*/
1751: PetscErrorCode  KSPSetDiagonalScaleFix(KSP ksp,PetscTruth fix)
1752: {
1755:   ksp->dscalefix = fix;
1756:   return(0);
1757: }

1761: /*@
1762:    KSPGetDiagonalScaleFix - Determines if KSP diagonally scales the system
1763:      back after solving.

1765:    Collective on KSP

1767:    Input Parameter:
1768: .  ksp - the KSP context

1770:    Output Parameter:
1771: .  fix - PETSC_TRUE to scale back after the system solve, PETSC_FALSE to not 
1772:          rescale (default)

1774:    Notes:
1775:      Must be called after KSPSetDiagonalScale()

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

1782:     This routine is only used if the matrix and preconditioner matrix are
1783:     the same thing.

1785:    Level: intermediate

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

1789: .seealso: KSPGetDiagonalScale(), KSPSetDiagonalScale(), KSPSetDiagonalScaleFix()
1790: @*/
1791: PetscErrorCode  KSPGetDiagonalScaleFix(KSP ksp,PetscTruth *fix)
1792: {
1796:   *fix = ksp->dscalefix;
1797:   return(0);
1798: }