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: }