Actual source code: itfunc.c
1: #define PETSCKSP_DLL
3: /*
4: Interface KSP routines that the user calls.
5: */
7: #include include/private/kspimpl.h
11: /*@
12: KSPComputeExtremeSingularValues - Computes the extreme singular values
13: for the preconditioned operator. Called after or during KSPSolve().
15: Not Collective
17: Input Parameter:
18: . ksp - iterative context obtained from KSPCreate()
20: Output Parameters:
21: . emin, emax - extreme singular values
23: Notes:
24: One must call KSPSetComputeSingularValues() before calling KSPSetUp()
25: (or use the option -ksp_compute_eigenvalues) in order for this routine to work correctly.
27: Many users may just want to use the monitoring routine
28: KSPMonitorSingularValue() (which can be set with option -ksp_monitor_singular_value)
29: to print the extreme singular values at each iteration of the linear solve.
31: Level: advanced
33: .keywords: KSP, compute, extreme, singular, values
35: .seealso: KSPSetComputeSingularValues(), KSPMonitorSingularValue(), KSPComputeEigenvalues()
36: @*/
37: PetscErrorCode KSPComputeExtremeSingularValues(KSP ksp,PetscReal *emax,PetscReal *emin)
38: {
45: if (!ksp->calc_sings) {
46: SETERRQ(4,"Singular values not requested before KSPSetUp()");
47: }
49: if (ksp->ops->computeextremesingularvalues) {
50: (*ksp->ops->computeextremesingularvalues)(ksp,emax,emin);
51: } else {
52: *emin = -1.0;
53: *emax = -1.0;
54: }
55: return(0);
56: }
60: /*@
61: KSPComputeEigenvalues - Computes the extreme eigenvalues for the
62: preconditioned operator. Called after or during KSPSolve().
64: Not Collective
66: Input Parameter:
67: + ksp - iterative context obtained from KSPCreate()
68: - n - size of arrays r and c. The number of eigenvalues computed (neig) will, in
69: general, be less than this.
71: Output Parameters:
72: + r - real part of computed eigenvalues
73: . c - complex part of computed eigenvalues
74: - neig - number of eigenvalues computed (will be less than or equal to n)
76: Options Database Keys:
77: + -ksp_compute_eigenvalues - Prints eigenvalues to stdout
78: - -ksp_plot_eigenvalues - Plots eigenvalues in an x-window display
80: Notes:
81: The number of eigenvalues estimated depends on the size of the Krylov space
82: generated during the KSPSolve() ; for example, with
83: CG it corresponds to the number of CG iterations, for GMRES it is the number
84: of GMRES iterations SINCE the last restart. Any extra space in r[] and c[]
85: will be ignored.
87: KSPComputeEigenvalues() does not usually provide accurate estimates; it is
88: intended only for assistance in understanding the convergence of iterative
89: methods, not for eigenanalysis.
91: One must call KSPSetComputeEigenvalues() before calling KSPSetUp()
92: in order for this routine to work correctly.
94: Many users may just want to use the monitoring routine
95: KSPMonitorSingularValue() (which can be set with option -ksp_monitor_singular_value)
96: to print the singular values at each iteration of the linear solve.
98: Level: advanced
100: .keywords: KSP, compute, extreme, singular, values
102: .seealso: KSPSetComputeSingularValues(), KSPMonitorSingularValue(), KSPComputeExtremeSingularValues()
103: @*/
104: PetscErrorCode KSPComputeEigenvalues(KSP ksp,PetscInt n,PetscReal *r,PetscReal *c,PetscInt *neig)
105: {
113: if (!ksp->calc_sings) {
114: SETERRQ(4,"Eigenvalues not requested before KSPSetUp()");
115: }
117: if (ksp->ops->computeeigenvalues) {
118: (*ksp->ops->computeeigenvalues)(ksp,n,r,c,neig);
119: } else {
120: *neig = 0;
121: }
122: return(0);
123: }
127: /*@
128: KSPSetUpOnBlocks - Sets up the preconditioner for each block in
129: the block Jacobi, block Gauss-Seidel, and overlapping Schwarz
130: methods.
132: Collective on KSP
134: Input Parameter:
135: . ksp - the KSP context
137: Notes:
138: KSPSetUpOnBlocks() is a routine that the user can optinally call for
139: more precise profiling (via -log_summary) of the setup phase for these
140: block preconditioners. If the user does not call KSPSetUpOnBlocks(),
141: it will automatically be called from within KSPSolve().
142:
143: Calling KSPSetUpOnBlocks() is the same as calling PCSetUpOnBlocks()
144: on the PC context within the KSP context.
146: Level: advanced
148: .keywords: KSP, setup, blocks
150: .seealso: PCSetUpOnBlocks(), KSPSetUp(), PCSetUp()
151: @*/
152: PetscErrorCode KSPSetUpOnBlocks(KSP ksp)
153: {
158: PCSetUpOnBlocks(ksp->pc);
159: return(0);
160: }
164: /*@
165: KSPSetUp - Sets up the internal data structures for the
166: later use of an iterative solver.
168: Collective on KSP
170: Input Parameter:
171: . ksp - iterative context obtained from KSPCreate()
173: Level: developer
175: .keywords: KSP, setup
177: .seealso: KSPCreate(), KSPSolve(), KSPDestroy()
178: @*/
179: PetscErrorCode KSPSetUp(KSP ksp)
180: {
186: /* reset the convergence flag from the previous solves */
187: ksp->reason = KSP_CONVERGED_ITERATING;
189: if (!ksp->type_name){
190: KSPSetType(ksp,KSPGMRES);
191: }
193: if (ksp->setupcalled == 2) return(0);
197: if (!ksp->setupcalled) {
198: (*ksp->ops->setup)(ksp);
199: }
201: /* scale the matrix if requested */
202: if (ksp->dscale) {
203: Mat mat,pmat;
204: PCGetOperators(ksp->pc,&mat,&pmat,PETSC_NULL);
205: if (mat == pmat) {
206: PetscScalar *xx;
207: PetscInt i,n;
208: PetscTruth zeroflag = PETSC_FALSE;
210: if (!ksp->diagonal) { /* allocate vector to hold diagonal */
211: MatGetVecs(pmat,&ksp->diagonal,0);
212: }
213: MatGetDiagonal(mat,ksp->diagonal);
214: VecGetLocalSize(ksp->diagonal,&n);
215: VecGetArray(ksp->diagonal,&xx);
216: for (i=0; i<n; i++) {
217: if (xx[i] != 0.0) xx[i] = 1.0/sqrt(PetscAbsScalar(xx[i]));
218: else {
219: xx[i] = 1.0;
220: zeroflag = PETSC_TRUE;
221: }
222: }
223: VecRestoreArray(ksp->diagonal,&xx);
224: if (zeroflag) {
225: PetscInfo(ksp,"Zero detected in diagonal of matrix, using 1 at those locations\n");
226: }
227: MatDiagonalScale(mat,ksp->diagonal,ksp->diagonal);
228: ksp->dscalefix2 = PETSC_FALSE;
229: } else {
230: SETERRQ(PETSC_ERR_SUP,"No support for diagonal scaling of linear system if preconditioner matrix not actual matrix");
231: }
232: }
234: PCSetUp(ksp->pc);
235: if (ksp->nullsp) {
236: PetscTruth test;
237: PetscOptionsHasName(ksp->prefix,"-ksp_test_null_space",&test);
238: if (test) {
239: Mat mat;
240: PCGetOperators(ksp->pc,&mat,PETSC_NULL,PETSC_NULL);
241: MatNullSpaceTest(ksp->nullsp,mat);
242: }
243: }
244: ksp->setupcalled = 2;
245: return(0);
246: }
250: /*@
251: KSPSolve - Solves linear system.
253: Collective on KSP
255: Parameter:
256: + ksp - iterative context obtained from KSPCreate()
257: . b - the right hand side vector
258: - x - the solution (this may be the same vector as b, then b will be overwritten with answer)
260: Options Database Keys:
261: + -ksp_compute_eigenvalues - compute preconditioned operators eigenvalues
262: . -ksp_plot_eigenvalues - plot the computed eigenvalues in an X-window
263: . -ksp_compute_eigenvalues_explicitly - compute the eigenvalues by forming the dense operator and useing LAPACK
264: . -ksp_plot_eigenvalues_explicitly - plot the explicitly computing eigenvalues
265: . -ksp_view_binary - save matrix and right hand side that define linear system to the default binary viewer (can be
266: read later with src/ksp/examples/tutorials/ex10.c for testing solvers)
267: . -ksp_converged_reason - print reason for converged or diverged, also prints number of iterations
268: . -ksp_final_residual - print 2-norm of true linear system residual at the end of the solution process
269: - -ksp_view - print the ksp data structure at the end of the system solution
271: Notes:
273: The operator is specified with PCSetOperators().
275: Call KSPGetConvergedReason() to determine if the solver converged or failed and
276: why. The number of iterations can be obtained from KSPGetIterationNumber().
277:
278: If using a direct method (e.g., via the KSP solver
279: KSPPREONLY and a preconditioner such as PCLU/PCILU),
280: then its=1. See KSPSetTolerances() and KSPDefaultConverged()
281: for more details.
283: Understanding Convergence:
284: The routines KSPMonitorSet(), KSPComputeEigenvalues(), and
285: KSPComputeEigenvaluesExplicitly() provide information on additional
286: options to monitor convergence and print eigenvalue information.
288: Level: beginner
290: .keywords: KSP, solve, linear system
292: .seealso: KSPCreate(), KSPSetUp(), KSPDestroy(), KSPSetTolerances(), KSPDefaultConverged(),
293: KSPSolveTranspose(), KSPGetIterationNumber()
294: @*/
295: PetscErrorCode KSPSolve(KSP ksp,Vec b,Vec x)
296: {
298: PetscMPIInt rank;
299: PetscTruth flag1,flag2,viewed=PETSC_FALSE,flg,inXisinB=PETSC_FALSE;
300: char view[10];
301: char filename[PETSC_MAX_PATH_LEN];
302: PetscViewer viewer;
303:
310: if (x == b) {
311: VecDuplicate(b,&x);
312: inXisinB = PETSC_TRUE;
313: }
314: PetscObjectReference((PetscObject)b);
315: PetscObjectReference((PetscObject)x);
316: if (ksp->vec_rhs) {VecDestroy(ksp->vec_rhs);}
317: if (ksp->vec_sol) {VecDestroy(ksp->vec_sol);}
318: ksp->vec_rhs = b;
319: ksp->vec_sol = x;
321: PetscOptionsHasName(ksp->prefix,"-ksp_view_binary",&flg);
322: if (flg) {
323: Mat mat;
324: PCGetOperators(ksp->pc,&mat,PETSC_NULL,PETSC_NULL);
325: MatView(mat,PETSC_VIEWER_BINARY_(ksp->comm));
326: VecView(ksp->vec_rhs,PETSC_VIEWER_BINARY_(ksp->comm));
327: }
331: /* reset the residual history list if requested */
332: if (ksp->res_hist_reset) ksp->res_hist_len = 0;
334: PetscOptionsGetString(ksp->prefix,"-ksp_view",view,10,&flg);
335: if (flg) {
336: PetscStrcmp(view,"before",&viewed);
337: if (viewed){
338: PetscViewer viewer;
339: PetscViewerASCIIGetStdout(ksp->comm,&viewer);
340: KSPView(ksp,viewer);
341: }
342: }
344: ksp->transpose_solve = PETSC_FALSE;
345:
346: /* KSPSetUp() scales the matrix if needed */
347: KSPSetUp(ksp);
348: KSPSetUpOnBlocks(ksp);
350: /* diagonal scale RHS if called for */
351: if (ksp->dscale) {
352: VecPointwiseMult(ksp->vec_rhs,ksp->vec_rhs,ksp->diagonal);
353: /* second time in, but matrix was scaled back to original */
354: if (ksp->dscalefix && ksp->dscalefix2) {
355: Mat mat;
357: PCGetOperators(ksp->pc,&mat,PETSC_NULL,PETSC_NULL);
358: MatDiagonalScale(mat,ksp->diagonal,ksp->diagonal);
359: }
361: /* scale initial guess */
362: if (!ksp->guess_zero) {
363: if (!ksp->truediagonal) {
364: VecDuplicate(ksp->diagonal,&ksp->truediagonal);
365: VecCopy(ksp->diagonal,ksp->truediagonal);
366: VecReciprocal(ksp->truediagonal);
367: }
368: VecPointwiseMult(ksp->vec_sol,ksp->vec_sol,ksp->truediagonal);
369: }
370: }
371: PCPreSolve(ksp->pc,ksp);
373: if (ksp->guess_zero) { VecSet(ksp->vec_sol,0.0);}
374: if (ksp->guess_knoll) {
375: PCApply(ksp->pc,ksp->vec_rhs,ksp->vec_sol);
376: KSP_RemoveNullSpace(ksp,ksp->vec_sol);
377: ksp->guess_zero = PETSC_FALSE;
378: }
379: (*ksp->ops->solve)(ksp);
380: if (!ksp->reason) {
381: SETERRQ(PETSC_ERR_PLIB,"Internal error, solver returned without setting converged reason");
382: }
383: if (ksp->printreason) {
384: if (ksp->reason > 0) {
385: PetscPrintf(ksp->comm,"Linear solve converged due to %s iterations %D\n",KSPConvergedReasons[ksp->reason],ksp->its);
386: } else {
387: PetscPrintf(ksp->comm,"Linear solve did not converge due to %s iterations %D\n",KSPConvergedReasons[ksp->reason],ksp->its);
388: }
389: }
390: PCPostSolve(ksp->pc,ksp);
392: /* diagonal scale solution if called for */
393: if (ksp->dscale) {
394: VecPointwiseMult(ksp->vec_sol,ksp->vec_sol,ksp->diagonal);
395: /* unscale right hand side and matrix */
396: if (ksp->dscalefix) {
397: Mat mat;
399: VecReciprocal(ksp->diagonal);
400: VecPointwiseMult(ksp->vec_rhs,ksp->vec_rhs,ksp->diagonal);
401: PCGetOperators(ksp->pc,&mat,PETSC_NULL,PETSC_NULL);
402: MatDiagonalScale(mat,ksp->diagonal,ksp->diagonal);
403: VecReciprocal(ksp->diagonal);
404: ksp->dscalefix2 = PETSC_TRUE;
405: }
406: }
409: MPI_Comm_rank(ksp->comm,&rank);
411: PetscOptionsHasName(ksp->prefix,"-ksp_compute_eigenvalues",&flag1);
412: PetscOptionsHasName(ksp->prefix,"-ksp_plot_eigenvalues",&flag2);
413: if (flag1 || flag2) {
414: PetscInt nits,n,i,neig;
415: PetscReal *r,*c;
416:
417: KSPGetIterationNumber(ksp,&nits);
418: n = nits+2;
420: if (!n) {
421: PetscPrintf(ksp->comm,"Zero iterations in solver, cannot approximate any eigenvalues\n");
422: } else {
423: PetscMalloc(2*n*sizeof(PetscReal),&r);
424: c = r + n;
425: KSPComputeEigenvalues(ksp,n,r,c,&neig);
426: if (flag1) {
427: PetscPrintf(ksp->comm,"Iteratively computed eigenvalues\n");
428: for (i=0; i<neig; i++) {
429: if (c[i] >= 0.0) {PetscPrintf(ksp->comm,"%G + %Gi\n",r[i],c[i]);}
430: else {PetscPrintf(ksp->comm,"%G - %Gi\n",r[i],-c[i]);}
431: }
432: }
433: if (flag2 && !rank) {
434: PetscDraw draw;
435: PetscDrawSP drawsp;
437: PetscViewerDrawOpen(PETSC_COMM_SELF,0,"Iteratively Computed Eigenvalues",PETSC_DECIDE,PETSC_DECIDE,300,300,&viewer);
438: PetscViewerDrawGetDraw(viewer,0,&draw);
439: PetscDrawSPCreate(draw,1,&drawsp);
440: for (i=0; i<neig; i++) {
441: PetscDrawSPAddPoint(drawsp,r+i,c+i);
442: }
443: PetscDrawSPDraw(drawsp);
444: PetscDrawSPDestroy(drawsp);
445: PetscViewerDestroy(viewer);
446: }
447: PetscFree(r);
448: }
449: }
451: PetscOptionsHasName(ksp->prefix,"-ksp_compute_eigenvalues_explicitly",&flag1);
452: PetscOptionsHasName(ksp->prefix,"-ksp_plot_eigenvalues_explicitly",&flag2);
453: if (flag1 || flag2) {
454: PetscInt n,i;
455: PetscReal *r,*c;
456: VecGetSize(ksp->vec_sol,&n);
457: PetscMalloc(2*n*sizeof(PetscReal),&r);
458: c = r + n;
459: KSPComputeEigenvaluesExplicitly(ksp,n,r,c);
460: if (flag1) {
461: PetscPrintf(ksp->comm,"Explicitly computed eigenvalues\n");
462: for (i=0; i<n; i++) {
463: if (c[i] >= 0.0) {PetscPrintf(ksp->comm,"%G + %Gi\n",r[i],c[i]);}
464: else {PetscPrintf(ksp->comm,"%G - %Gi\n",r[i],-c[i]);}
465: }
466: }
467: if (flag2 && !rank) {
468: PetscDraw draw;
469: PetscDrawSP drawsp;
471: PetscViewerDrawOpen(PETSC_COMM_SELF,0,"Explicitly Computed Eigenvalues",0,320,300,300,&viewer);
472: PetscViewerDrawGetDraw(viewer,0,&draw);
473: PetscDrawSPCreate(draw,1,&drawsp);
474: for (i=0; i<n; i++) {
475: PetscDrawSPAddPoint(drawsp,r+i,c+i);
476: }
477: PetscDrawSPDraw(drawsp);
478: PetscDrawSPDestroy(drawsp);
479: PetscViewerDestroy(viewer);
480: }
481: PetscFree(r);
482: }
484: PetscOptionsHasName(ksp->prefix,"-ksp_view_operator",&flag2);
485: if (flag2) {
486: Mat A,B;
487: PetscViewer viewer;
489: PCGetOperators(ksp->pc,&A,PETSC_NULL,PETSC_NULL);
490: MatComputeExplicitOperator(A,&B);
491: PetscViewerASCIIGetStdout(ksp->comm,&viewer);
492: PetscViewerPushFormat(viewer,PETSC_VIEWER_ASCII_MATLAB);
493: MatView(B,viewer);
494: PetscViewerPopFormat(viewer);
495: MatDestroy(B);
496: }
497: PetscOptionsHasName(ksp->prefix,"-ksp_view_operator_binary",&flag2);
498: if (flag2) {
499: Mat A,B;
500: PCGetOperators(ksp->pc,&A,PETSC_NULL,PETSC_NULL);
501: MatComputeExplicitOperator(A,&B);
502: MatView(B,PETSC_VIEWER_BINARY_(ksp->comm));
503: MatDestroy(B);
504: }
505: PetscOptionsHasName(ksp->prefix,"-ksp_view_preconditioned_operator_binary",&flag2);
506: if (flag2) {
507: Mat B;
508: KSPComputeExplicitOperator(ksp,&B);
509: MatView(B,PETSC_VIEWER_BINARY_(ksp->comm));
510: MatDestroy(B);
511: }
512: if (!viewed) {
513: PetscOptionsGetString(ksp->prefix,"-ksp_view",filename,PETSC_MAX_PATH_LEN,&flg);
514: if (flg && !PetscPreLoadingOn) {
515: PetscViewerASCIIOpen(ksp->comm,filename,&viewer);
516: KSPView(ksp,viewer);
517: PetscViewerDestroy(viewer);
518: }
519: }
520: PetscOptionsHasName(ksp->prefix,"-ksp_final_residual",&flg);
521: if (flg) {
522: Mat A;
523: Vec t;
524: PetscReal norm;
525: if (ksp->dscale && !ksp->dscalefix) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot compute final scale with -ksp_diagonal_scale except also with -ksp_diagonal_scale_fix");
526: PCGetOperators(ksp->pc,&A,0,0);
527: VecDuplicate(ksp->vec_sol,&t);
528: KSP_MatMult(ksp,A,ksp->vec_sol,t);
529: VecWAXPY(t,-1.0,t,ksp->vec_rhs);
530: VecNorm(t,NORM_2,&norm);
531: VecDestroy(t);
532: PetscPrintf(ksp->comm,"KSP final norm of residual %G\n",norm);
533: }
534: if (inXisinB) {
535: VecCopy(x,b);
536: VecDestroy(x);
537: }
538: return(0);
539: }
543: /*@
544: KSPSolveTranspose - Solves the transpose of a linear system. Usually
545: accessed through KSPSolveTranspose().
547: Collective on KSP
549: Input Parameter:
550: + ksp - iterative context obtained from KSPCreate()
551: . b - right hand side vector
552: - x - solution vector
554: Note:
555: Currently only supported by KSPType of KSPPREONLY. This routine is usally
556: only used internally by the BiCG solver on the subblocks in BJacobi and ASM.
558: Level: developer
560: .keywords: KSP, solve, linear system
562: .seealso: KSPCreate(), KSPSetUp(), KSPDestroy(), KSPSetTolerances(), KSPDefaultConverged(),
563: KSPSolve()
564: @*/
565: PetscErrorCode KSPSolveTranspose(KSP ksp,Vec b,Vec x)
566: {
568: PetscTruth inXisinB=PETSC_FALSE;
574: if (x == b) {
575: VecDuplicate(b,&x);
576: inXisinB = PETSC_TRUE;
577: }
578: PetscObjectReference((PetscObject)b);
579: PetscObjectReference((PetscObject)x);
580: if (ksp->vec_rhs) {VecDestroy(ksp->vec_rhs);}
581: if (ksp->vec_sol) {VecDestroy(ksp->vec_sol);}
582: ksp->vec_rhs = b;
583: ksp->vec_sol = x;
584: ksp->transpose_solve = PETSC_TRUE;
585: KSPSetUp(ksp);
586: if (ksp->guess_zero) { VecSet(ksp->vec_sol,0.0);}
587: (*ksp->ops->solve)(ksp);
588: if (inXisinB) {
589: VecCopy(x,b);
590: VecDestroy(x);
591: }
592: return(0);
593: }
597: /*@
598: KSPDestroy - Destroys KSP context.
600: Collective on KSP
602: Input Parameter:
603: . ksp - iterative context obtained from KSPCreate()
605: Level: beginner
607: .keywords: KSP, destroy
609: .seealso: KSPCreate(), KSPSetUp(), KSPSolve()
610: @*/
611: PetscErrorCode KSPDestroy(KSP ksp)
612: {
617: if (--ksp->refct > 0) return(0);
619: /* if memory was published with AMS then destroy it */
620: PetscObjectDepublish(ksp);
622: if (ksp->ops->destroy) {
623: (*ksp->ops->destroy)(ksp);
624: }
625: PetscFree(ksp->res_hist_alloc);
626: KSPMonitorCancel(ksp);
627: PCDestroy(ksp->pc);
628: if (ksp->vec_rhs) {VecDestroy(ksp->vec_rhs);}
629: if (ksp->vec_sol) {VecDestroy(ksp->vec_sol);}
630: if (ksp->diagonal) {VecDestroy(ksp->diagonal);}
631: if (ksp->truediagonal) {VecDestroy(ksp->truediagonal);}
632: if (ksp->nullsp) {MatNullSpaceDestroy(ksp->nullsp);}
633: PetscHeaderDestroy(ksp);
634: return(0);
635: }
639: /*@
640: KSPSetPreconditionerSide - Sets the preconditioning side.
642: Collective on KSP
644: Input Parameter:
645: . ksp - iterative context obtained from KSPCreate()
647: Output Parameter:
648: . side - the preconditioning side, where side is one of
649: .vb
650: PC_LEFT - left preconditioning (default)
651: PC_RIGHT - right preconditioning
652: PC_SYMMETRIC - symmetric preconditioning
653: .ve
655: Options Database Keys:
656: + -ksp_left_pc - Sets left preconditioning
657: . -ksp_right_pc - Sets right preconditioning
658: - -ksp_symmetric_pc - Sets symmetric preconditioning
660: Notes:
661: Left preconditioning is used by default. Symmetric preconditioning is
662: currently available only for the KSPQCG method. Note, however, that
663: symmetric preconditioning can be emulated by using either right or left
664: preconditioning and a pre or post processing step.
666: Level: intermediate
668: .keywords: KSP, set, right, left, symmetric, side, preconditioner, flag
670: .seealso: KSPGetPreconditionerSide()
671: @*/
672: PetscErrorCode KSPSetPreconditionerSide(KSP ksp,PCSide side)
673: {
676: ksp->pc_side = side;
677: return(0);
678: }
682: /*@
683: KSPGetPreconditionerSide - Gets the preconditioning side.
685: Not Collective
687: Input Parameter:
688: . ksp - iterative context obtained from KSPCreate()
690: Output Parameter:
691: . side - the preconditioning side, where side is one of
692: .vb
693: PC_LEFT - left preconditioning (default)
694: PC_RIGHT - right preconditioning
695: PC_SYMMETRIC - symmetric preconditioning
696: .ve
698: Level: intermediate
700: .keywords: KSP, get, right, left, symmetric, side, preconditioner, flag
702: .seealso: KSPSetPreconditionerSide()
703: @*/
704: PetscErrorCode KSPGetPreconditionerSide(KSP ksp,PCSide *side)
705: {
709: *side = ksp->pc_side;
710: return(0);
711: }
715: /*@
716: KSPGetTolerances - Gets the relative, absolute, divergence, and maximum
717: iteration tolerances used by the default KSP convergence tests.
719: Not Collective
721: Input Parameter:
722: . ksp - the Krylov subspace context
723:
724: Output Parameters:
725: + rtol - the relative convergence tolerance
726: . abstol - the absolute convergence tolerance
727: . dtol - the divergence tolerance
728: - maxits - maximum number of iterations
730: Notes:
731: The user can specify PETSC_NULL for any parameter that is not needed.
733: Level: intermediate
735: .keywords: KSP, get, tolerance, absolute, relative, divergence, convergence,
736: maximum, iterations
738: .seealso: KSPSetTolerances()
739: @*/
740: PetscErrorCode KSPGetTolerances(KSP ksp,PetscReal *rtol,PetscReal *abstol,PetscReal *dtol,PetscInt *maxits)
741: {
744: if (abstol) *abstol = ksp->abstol;
745: if (rtol) *rtol = ksp->rtol;
746: if (dtol) *dtol = ksp->divtol;
747: if (maxits) *maxits = ksp->max_it;
748: return(0);
749: }
753: /*@
754: KSPSetTolerances - Sets the relative, absolute, divergence, and maximum
755: iteration tolerances used by the default KSP convergence testers.
757: Collective on KSP
759: Input Parameters:
760: + ksp - the Krylov subspace context
761: . rtol - the relative convergence tolerance
762: (relative decrease in the residual norm)
763: . abstol - the absolute convergence tolerance
764: (absolute size of the residual norm)
765: . dtol - the divergence tolerance
766: (amount residual can increase before KSPDefaultConverged()
767: concludes that the method is diverging)
768: - maxits - maximum number of iterations to use
770: Options Database Keys:
771: + -ksp_atol <abstol> - Sets abstol
772: . -ksp_rtol <rtol> - Sets rtol
773: . -ksp_divtol <dtol> - Sets dtol
774: - -ksp_max_it <maxits> - Sets maxits
776: Notes:
777: Use PETSC_DEFAULT to retain the default value of any of the tolerances.
779: See KSPDefaultConverged() for details on the use of these parameters
780: in the default convergence test. See also KSPSetConvergenceTest()
781: for setting user-defined stopping criteria.
783: Level: intermediate
785: .keywords: KSP, set, tolerance, absolute, relative, divergence,
786: convergence, maximum, iterations
788: .seealso: KSPGetTolerances(), KSPDefaultConverged(), KSPSetConvergenceTest()
789: @*/
790: PetscErrorCode KSPSetTolerances(KSP ksp,PetscReal rtol,PetscReal abstol,PetscReal dtol,PetscInt maxits)
791: {
794: if (abstol != PETSC_DEFAULT) ksp->abstol = abstol;
795: if (rtol != PETSC_DEFAULT) ksp->rtol = rtol;
796: if (dtol != PETSC_DEFAULT) ksp->divtol = dtol;
797: if (maxits != PETSC_DEFAULT) ksp->max_it = maxits;
798: return(0);
799: }
803: /*@
804: KSPSetInitialGuessNonzero - Tells the iterative solver that the
805: initial guess is nonzero; otherwise KSP assumes the initial guess
806: is to be zero (and thus zeros it out before solving).
808: Collective on KSP
810: Input Parameters:
811: + ksp - iterative context obtained from KSPCreate()
812: - flg - PETSC_TRUE indicates the guess is non-zero, PETSC_FALSE indicates the guess is zero
814: Level: beginner
816: Notes:
817: If this is not called the X vector is zeroed in the call to KSPSolve().
819: .keywords: KSP, set, initial guess, nonzero
821: .seealso: KSPGetInitialGuessNonzero(), KSPSetInitialGuessKnoll(), KSPGetInitialGuessKnoll()
822: @*/
823: PetscErrorCode KSPSetInitialGuessNonzero(KSP ksp,PetscTruth flg)
824: {
826: ksp->guess_zero = (PetscTruth)!(int)flg;
827: return(0);
828: }
832: /*@
833: KSPGetInitialGuessNonzero - Determines whether the KSP solver is using
834: a zero initial guess.
836: Not Collective
838: Input Parameter:
839: . ksp - iterative context obtained from KSPCreate()
841: Output Parameter:
842: . flag - PETSC_TRUE if guess is nonzero, else PETSC_FALSE
844: Level: intermediate
846: .keywords: KSP, set, initial guess, nonzero
848: .seealso: KSPSetInitialGuessNonzero(), KSPSetInitialGuessKnoll(), KSPGetInitialGuessKnoll()
849: @*/
850: PetscErrorCode KSPGetInitialGuessNonzero(KSP ksp,PetscTruth *flag)
851: {
853: if (ksp->guess_zero) *flag = PETSC_FALSE;
854: else *flag = PETSC_TRUE;
855: return(0);
856: }
860: /*@
861: KSPSetInitialGuessKnoll - Tells the iterative solver to use PCApply(pc,b,..) to compute the initial guess (The Knoll trick)
863: Collective on KSP
865: Input Parameters:
866: + ksp - iterative context obtained from KSPCreate()
867: - flg - PETSC_TRUE or PETSC_FALSE
869: Level: advanced
872: .keywords: KSP, set, initial guess, nonzero
874: .seealso: KSPGetInitialGuessKnoll(), KSPSetInitialGuessNonzero(), KSPGetInitialGuessNonzero()
875: @*/
876: PetscErrorCode KSPSetInitialGuessKnoll(KSP ksp,PetscTruth flg)
877: {
879: ksp->guess_knoll = flg;
880: return(0);
881: }
885: /*@
886: KSPGetInitialGuessKnoll - Determines whether the KSP solver is using the Knoll trick (using PCApply(pc,b,...) to compute
887: the initial guess
889: Not Collective
891: Input Parameter:
892: . ksp - iterative context obtained from KSPCreate()
894: Output Parameter:
895: . flag - PETSC_TRUE if using Knoll trick, else PETSC_FALSE
897: Level: advanced
899: .keywords: KSP, set, initial guess, nonzero
901: .seealso: KSPSetInitialGuessKnoll(), KSPSetInitialGuessNonzero(), KSPGetInitialGuessNonzero()
902: @*/
903: PetscErrorCode KSPGetInitialGuessKnoll(KSP ksp,PetscTruth *flag)
904: {
906: *flag = ksp->guess_knoll;
907: return(0);
908: }
912: /*@
913: KSPGetComputeSingularValues - Gets the flag indicating whether the extreme singular
914: values will be calculated via a Lanczos or Arnoldi process as the linear
915: system is solved.
917: Collective on KSP
919: Input Parameter:
920: . ksp - iterative context obtained from KSPCreate()
922: Output Parameter:
923: . flg - PETSC_TRUE or PETSC_FALSE
925: Options Database Key:
926: . -ksp_monitor_singular_value - Activates KSPSetComputeSingularValues()
928: Notes:
929: Currently this option is not valid for all iterative methods.
931: Many users may just want to use the monitoring routine
932: KSPMonitorSingularValue() (which can be set with option -ksp_monitor_singular_value)
933: to print the singular values at each iteration of the linear solve.
935: Level: advanced
937: .keywords: KSP, set, compute, singular values
939: .seealso: KSPComputeExtremeSingularValues(), KSPMonitorSingularValue()
940: @*/
941: PetscErrorCode KSPGetComputeSingularValues(KSP ksp,PetscTruth *flg)
942: {
946: *flg = ksp->calc_sings;
947: return(0);
948: }
952: /*@
953: KSPSetComputeSingularValues - Sets a flag so that the extreme singular
954: values will be calculated via a Lanczos or Arnoldi process as the linear
955: system is solved.
957: Collective on KSP
959: Input Parameters:
960: + ksp - iterative context obtained from KSPCreate()
961: - flg - PETSC_TRUE or PETSC_FALSE
963: Options Database Key:
964: . -ksp_monitor_singular_value - Activates KSPSetComputeSingularValues()
966: Notes:
967: Currently this option is not valid for all iterative methods.
969: Many users may just want to use the monitoring routine
970: KSPMonitorSingularValue() (which can be set with option -ksp_monitor_singular_value)
971: to print the singular values at each iteration of the linear solve.
973: Level: advanced
975: .keywords: KSP, set, compute, singular values
977: .seealso: KSPComputeExtremeSingularValues(), KSPMonitorSingularValue()
978: @*/
979: PetscErrorCode KSPSetComputeSingularValues(KSP ksp,PetscTruth flg)
980: {
983: ksp->calc_sings = flg;
984: return(0);
985: }
989: /*@
990: KSPGetComputeEigenvalues - Gets the flag indicating that the extreme eigenvalues
991: values will be calculated via a Lanczos or Arnoldi process as the linear
992: system is solved.
994: Collective on KSP
996: Input Parameter:
997: . ksp - iterative context obtained from KSPCreate()
999: Output Parameter:
1000: . flg - PETSC_TRUE or PETSC_FALSE
1002: Notes:
1003: Currently this option is not valid for all iterative methods.
1005: Level: advanced
1007: .keywords: KSP, set, compute, eigenvalues
1009: .seealso: KSPComputeEigenvalues(), KSPComputeEigenvaluesExplicitly()
1010: @*/
1011: PetscErrorCode KSPGetComputeEigenvalues(KSP ksp,PetscTruth *flg)
1012: {
1016: *flg = ksp->calc_sings;
1017: return(0);
1018: }
1022: /*@
1023: KSPSetComputeEigenvalues - Sets a flag so that the extreme eigenvalues
1024: values will be calculated via a Lanczos or Arnoldi process as the linear
1025: system is solved.
1027: Collective on KSP
1029: Input Parameters:
1030: + ksp - iterative context obtained from KSPCreate()
1031: - flg - PETSC_TRUE or PETSC_FALSE
1033: Notes:
1034: Currently this option is not valid for all iterative methods.
1036: Level: advanced
1038: .keywords: KSP, set, compute, eigenvalues
1040: .seealso: KSPComputeEigenvalues(), KSPComputeEigenvaluesExplicitly()
1041: @*/
1042: PetscErrorCode KSPSetComputeEigenvalues(KSP ksp,PetscTruth flg)
1043: {
1046: ksp->calc_sings = flg;
1047: return(0);
1048: }
1052: /*@
1053: KSPGetRhs - Gets the right-hand-side vector for the linear system to
1054: be solved.
1056: Not Collective
1058: Input Parameter:
1059: . ksp - iterative context obtained from KSPCreate()
1061: Output Parameter:
1062: . r - right-hand-side vector
1064: Level: developer
1066: .keywords: KSP, get, right-hand-side, rhs
1068: .seealso: KSPGetSolution(), KSPSolve()
1069: @*/
1070: PetscErrorCode KSPGetRhs(KSP ksp,Vec *r)
1071: {
1075: *r = ksp->vec_rhs;
1076: return(0);
1077: }
1081: /*@
1082: KSPGetSolution - Gets the location of the solution for the
1083: linear system to be solved. Note that this may not be where the solution
1084: is stored during the iterative process; see KSPBuildSolution().
1086: Not Collective
1088: Input Parameters:
1089: . ksp - iterative context obtained from KSPCreate()
1091: Output Parameters:
1092: . v - solution vector
1094: Level: developer
1096: .keywords: KSP, get, solution
1098: .seealso: KSPGetRhs(), KSPBuildSolution(), KSPSolve()
1099: @*/
1100: PetscErrorCode KSPGetSolution(KSP ksp,Vec *v)
1101: {
1105: *v = ksp->vec_sol;
1106: return(0);
1107: }
1111: /*@
1112: KSPSetPC - Sets the preconditioner to be used to calculate the
1113: application of the preconditioner on a vector.
1115: Collective on KSP
1117: Input Parameters:
1118: + ksp - iterative context obtained from KSPCreate()
1119: - pc - the preconditioner object
1121: Notes:
1122: Use KSPGetPC() to retrieve the preconditioner context (for example,
1123: to free it at the end of the computations).
1125: Level: developer
1127: .keywords: KSP, set, precondition, Binv
1129: .seealso: KSPGetPC()
1130: @*/
1131: PetscErrorCode KSPSetPC(KSP ksp,PC pc)
1132: {
1139: PetscObjectReference((PetscObject)pc);
1140: if (ksp->pc) {PCDestroy(ksp->pc);}
1141: ksp->pc = pc;
1142: return(0);
1143: }
1147: /*@
1148: KSPGetPC - Returns a pointer to the preconditioner context
1149: set with KSPSetPC().
1151: Not Collective
1153: Input Parameters:
1154: . ksp - iterative context obtained from KSPCreate()
1156: Output Parameter:
1157: . pc - preconditioner context
1159: Level: developer
1161: .keywords: KSP, get, preconditioner, Binv
1163: .seealso: KSPSetPC()
1164: @*/
1165: PetscErrorCode KSPGetPC(KSP ksp,PC *pc)
1166: {
1170: *pc = ksp->pc;
1171: return(0);
1172: }
1176: /*@C
1177: KSPMonitorSet - Sets an ADDITIONAL function to be called at every iteration to monitor
1178: the residual/error etc.
1179:
1180: Collective on KSP
1182: Input Parameters:
1183: + ksp - iterative context obtained from KSPCreate()
1184: . monitor - pointer to function (if this is PETSC_NULL, it turns off monitoring
1185: . mctx - [optional] context for private data for the
1186: monitor routine (use PETSC_NULL if no context is desired)
1187: - monitordestroy - [optional] routine that frees monitor context
1188: (may be PETSC_NULL)
1190: Calling Sequence of monitor:
1191: $ monitor (KSP ksp, int it, PetscReal rnorm, void *mctx)
1193: + ksp - iterative context obtained from KSPCreate()
1194: . it - iteration number
1195: . rnorm - (estimated) 2-norm of (preconditioned) residual
1196: - mctx - optional monitoring context, as set by KSPMonitorSet()
1198: Options Database Keys:
1199: + -ksp_monitor - sets KSPMonitorDefault()
1200: . -ksp_monitor_true_residual - sets KSPMonitorTrueResidualNorm()
1201: . -ksp_monitor_draw - sets line graph monitor,
1202: uses KSPMonitorLGCreate()
1203: . -ksp_monitor_draw_true_residual - sets line graph monitor,
1204: uses KSPMonitorLGCreate()
1205: . -ksp_monitor_singular_value - sets KSPMonitorSingularValue()
1206: - -ksp_monitor_cancel - cancels all monitors that have
1207: been hardwired into a code by
1208: calls to KSPMonitorSet(), but
1209: does not cancel those set via
1210: the options database.
1212: Notes:
1213: The default is to do nothing. To print the residual, or preconditioned
1214: residual if KSPSetNormType(ksp,KSP_NORM_PRECONDITIONED) was called, use
1215: KSPMonitorDefault() as the monitoring routine, with a null monitoring
1216: context.
1218: Several different monitoring routines may be set by calling
1219: KSPMonitorSet() multiple times; all will be called in the
1220: order in which they were set.
1222: Level: beginner
1224: .keywords: KSP, set, monitor
1226: .seealso: KSPMonitorDefault(), KSPMonitorLGCreate(), KSPMonitorCancel()
1227: @*/
1228: PetscErrorCode KSPMonitorSet(KSP ksp,PetscErrorCode (*monitor)(KSP,PetscInt,PetscReal,void*),void *mctx,PetscErrorCode (*monitordestroy)(void*))
1229: {
1230: PetscInt i;
1234: if (ksp->numbermonitors >= MAXKSPMONITORS) {
1235: SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Too many KSP monitors set");
1236: }
1237: for (i=0; i<ksp->numbermonitors;i++) {
1238: if (monitor == ksp->monitor[i] && monitordestroy == ksp->monitordestroy[i] && mctx == ksp->monitorcontext[i]) return(0);
1240: /* check if both default monitors that share common ASCII viewer */
1241: if (monitor == ksp->monitor[i] && monitor == KSPMonitorDefault) {
1242: if (mctx && ksp->monitorcontext[i]) {
1243: PetscErrorCode ierr;
1244: PetscViewerASCIIMonitor viewer1 = (PetscViewerASCIIMonitor) mctx;
1245: PetscViewerASCIIMonitor viewer2 = (PetscViewerASCIIMonitor) ksp->monitorcontext[i];
1246: if (viewer1->viewer == viewer2->viewer) {
1247: (*monitordestroy)(mctx);
1248: return(0);
1249: }
1250: }
1251: }
1252: }
1253: ksp->monitor[ksp->numbermonitors] = monitor;
1254: ksp->monitordestroy[ksp->numbermonitors] = monitordestroy;
1255: ksp->monitorcontext[ksp->numbermonitors++] = (void*)mctx;
1256: return(0);
1257: }
1261: /*@
1262: KSPMonitorCancel - Clears all monitors for a KSP object.
1264: Collective on KSP
1266: Input Parameters:
1267: . ksp - iterative context obtained from KSPCreate()
1269: Options Database Key:
1270: . -ksp_monitor_cancel - Cancels all monitors that have
1271: been hardwired into a code by calls to KSPMonitorSet(),
1272: but does not cancel those set via the options database.
1274: Level: intermediate
1276: .keywords: KSP, set, monitor
1278: .seealso: KSPMonitorDefault(), KSPMonitorLGCreate(), KSPMonitorSet()
1279: @*/
1280: PetscErrorCode KSPMonitorCancel(KSP ksp)
1281: {
1283: PetscInt i;
1287: for (i=0; i<ksp->numbermonitors; i++) {
1288: if (ksp->monitordestroy[i]) {
1289: (*ksp->monitordestroy[i])(ksp->monitorcontext[i]);
1290: }
1291: }
1292: ksp->numbermonitors = 0;
1293: return(0);
1294: }
1298: /*@C
1299: KSPGetMonitorContext - Gets the monitoring context, as set by
1300: KSPMonitorSet() for the FIRST monitor only.
1302: Not Collective
1304: Input Parameter:
1305: . ksp - iterative context obtained from KSPCreate()
1307: Output Parameter:
1308: . ctx - monitoring context
1310: Level: intermediate
1312: .keywords: KSP, get, monitor, context
1314: .seealso: KSPMonitorDefault(), KSPMonitorLGCreate()
1315: @*/
1316: PetscErrorCode KSPGetMonitorContext(KSP ksp,void **ctx)
1317: {
1320: *ctx = (ksp->monitorcontext[0]);
1321: return(0);
1322: }
1326: /*@
1327: KSPSetResidualHistory - Sets the array used to hold the residual history.
1328: If set, this array will contain the residual norms computed at each
1329: iteration of the solver.
1331: Not Collective
1333: Input Parameters:
1334: + ksp - iterative context obtained from KSPCreate()
1335: . a - array to hold history
1336: . na - size of a
1337: - reset - PETSC_TRUE indicates the history counter is reset to zero
1338: for each new linear solve
1340: Level: advanced
1342: Notes: The array is NOT freed by PETSc so the user needs to keep track of
1343: it and destroy once the KSP object is destroyed.
1345: If 'na' is PETSC_DECIDE or PETSC_DEFAULT, or 'a' is PETSC_NULL, then a
1346: default array of length 10000 is allocated.
1348: .keywords: KSP, set, residual, history, norm
1350: .seealso: KSPGetResidualHistory()
1352: @*/
1353: PetscErrorCode KSPSetResidualHistory(KSP ksp,PetscReal a[],PetscInt na,PetscTruth reset)
1354: {
1360: PetscFree(ksp->res_hist_alloc);
1361: if (na != PETSC_DECIDE && na != PETSC_DEFAULT && a) {
1362: ksp->res_hist = a;
1363: ksp->res_hist_max = na;
1364: } else {
1365: if (na != PETSC_DECIDE && na != PETSC_DEFAULT)
1366: ksp->res_hist_max = na;
1367: else
1368: ksp->res_hist_max = 10000; /* like default ksp->max_it */
1369: PetscMalloc(ksp->res_hist_max*sizeof(PetscReal),&ksp->res_hist_alloc);
1370: ksp->res_hist = ksp->res_hist_alloc;
1371: }
1372: ksp->res_hist_len = 0;
1373: ksp->res_hist_reset = reset;
1375: return(0);
1376: }
1380: /*@C
1381: KSPGetResidualHistory - Gets the array used to hold the residual history
1382: and the number of residuals it contains.
1384: Not Collective
1386: Input Parameter:
1387: . ksp - iterative context obtained from KSPCreate()
1389: Output Parameters:
1390: + a - pointer to array to hold history (or PETSC_NULL)
1391: - na - number of used entries in a (or PETSC_NULL)
1393: Level: advanced
1395: Notes:
1396: Can only be called after a KSPSetResidualHistory() otherwise a and na are set to zero
1398: The Fortran version of this routine has a calling sequence
1399: $ call KSPGetResidualHistory(KSP ksp, integer na, integer ierr)
1401: .keywords: KSP, get, residual, history, norm
1403: .seealso: KSPGetResidualHistory()
1405: @*/
1406: PetscErrorCode KSPGetResidualHistory(KSP ksp,PetscReal *a[],PetscInt *na)
1407: {
1410: if (a) *a = ksp->res_hist;
1411: if (na) *na = ksp->res_hist_len;
1412: return(0);
1413: }
1417: /*@C
1418: KSPSetConvergenceTest - Sets the function to be used to determine
1419: convergence.
1421: Collective on KSP
1423: Input Parameters:
1424: + ksp - iterative context obtained from KSPCreate()
1425: . converge - pointer to int function
1426: - cctx - context for private data for the convergence routine (may be null)
1428: Calling sequence of converge:
1429: $ converge (KSP ksp, int it, PetscReal rnorm, KSPConvergedReason *reason,void *mctx)
1431: + ksp - iterative context obtained from KSPCreate()
1432: . it - iteration number
1433: . rnorm - (estimated) 2-norm of (preconditioned) residual
1434: . reason - the reason why it has converged or diverged
1435: - cctx - optional convergence context, as set by KSPSetConvergenceTest()
1438: Notes:
1439: Must be called after the KSP type has been set so put this after
1440: a call to KSPSetType(), or KSPSetFromOptions().
1442: The default convergence test, KSPDefaultConverged(), aborts if the
1443: residual grows to more than 10000 times the initial residual.
1445: The default is a combination of relative and absolute tolerances.
1446: The residual value that is tested may be an approximation; routines
1447: that need exact values should compute them.
1449: In the default PETSc convergence test, the precise values of reason
1450: are macros such as KSP_CONVERGED_RTOL, which are defined in petscksp.h.
1452: Level: advanced
1454: .keywords: KSP, set, convergence, test, context
1456: .seealso: KSPDefaultConverged(), KSPGetConvergenceContext()
1457: @*/
1458: PetscErrorCode KSPSetConvergenceTest(KSP ksp,PetscErrorCode (*converge)(KSP,PetscInt,PetscReal,KSPConvergedReason*,void*),void *cctx)
1459: {
1462: ksp->converged = converge;
1463: ksp->cnvP = (void*)cctx;
1464: return(0);
1465: }
1469: /*@C
1470: KSPGetConvergenceContext - Gets the convergence context set with
1471: KSPSetConvergenceTest().
1473: Not Collective
1475: Input Parameter:
1476: . ksp - iterative context obtained from KSPCreate()
1478: Output Parameter:
1479: . ctx - monitoring context
1481: Level: advanced
1483: .keywords: KSP, get, convergence, test, context
1485: .seealso: KSPDefaultConverged(), KSPSetConvergenceTest()
1486: @*/
1487: PetscErrorCode KSPGetConvergenceContext(KSP ksp,void **ctx)
1488: {
1491: *ctx = ksp->cnvP;
1492: return(0);
1493: }
1497: /*@
1498: KSPBuildSolution - Builds the approximate solution in a vector provided.
1499: This routine is NOT commonly needed (see KSPSolve()).
1501: Collective on KSP
1503: Input Parameter:
1504: . ctx - iterative context obtained from KSPCreate()
1506: Output Parameter:
1507: Provide exactly one of
1508: + v - location to stash solution.
1509: - V - the solution is returned in this location. This vector is created
1510: internally. This vector should NOT be destroyed by the user with
1511: VecDestroy().
1513: Notes:
1514: This routine can be used in one of two ways
1515: .vb
1516: KSPBuildSolution(ksp,PETSC_NULL,&V);
1517: or
1518: KSPBuildSolution(ksp,v,PETSC_NULL);
1519: .ve
1520: In the first case an internal vector is allocated to store the solution
1521: (the user cannot destroy this vector). In the second case the solution
1522: is generated in the vector that the user provides. Note that for certain
1523: methods, such as KSPCG, the second case requires a copy of the solution,
1524: while in the first case the call is essentially free since it simply
1525: returns the vector where the solution already is stored.
1527: Level: advanced
1529: .keywords: KSP, build, solution
1531: .seealso: KSPGetSolution(), KSPBuildResidual()
1532: @*/
1533: PetscErrorCode KSPBuildSolution(KSP ksp,Vec v,Vec *V)
1534: {
1539: if (!V && !v) SETERRQ(PETSC_ERR_ARG_WRONG,"Must provide either v or V");
1540: if (!V) V = &v;
1541: (*ksp->ops->buildsolution)(ksp,v,V);
1542: return(0);
1543: }
1547: /*@
1548: KSPBuildResidual - Builds the residual in a vector provided.
1550: Collective on KSP
1552: Input Parameter:
1553: . ksp - iterative context obtained from KSPCreate()
1555: Output Parameters:
1556: + v - optional location to stash residual. If v is not provided,
1557: then a location is generated.
1558: . t - work vector. If not provided then one is generated.
1559: - V - the residual
1561: Notes:
1562: Regardless of whether or not v is provided, the residual is
1563: returned in V.
1565: Level: advanced
1567: .keywords: KSP, build, residual
1569: .seealso: KSPBuildSolution()
1570: @*/
1571: PetscErrorCode KSPBuildResidual(KSP ksp,Vec t,Vec v,Vec *V)
1572: {
1574: PetscTruth flag = PETSC_FALSE;
1575: Vec w = v,tt = t;
1579: if (!w) {
1580: VecDuplicate(ksp->vec_rhs,&w);
1581: PetscLogObjectParent((PetscObject)ksp,w);
1582: }
1583: if (!tt) {
1584: VecDuplicate(ksp->vec_sol,&tt); flag = PETSC_TRUE;
1585: PetscLogObjectParent((PetscObject)ksp,tt);
1586: }
1587: (*ksp->ops->buildresidual)(ksp,tt,w,V);
1588: if (flag) {VecDestroy(tt);}
1589: return(0);
1590: }
1594: /*@
1595: KSPSetDiagonalScale - Tells KSP to symmetrically diagonally scale the system
1596: before solving. This actually CHANGES the matrix (and right hand side).
1598: Collective on KSP
1600: Input Parameter:
1601: + ksp - the KSP context
1602: - scale - PETSC_TRUE or PETSC_FALSE
1604: Options Database Key:
1605: + -ksp_diagonal_scale -
1606: - -ksp_diagonal_scale_fix - scale the matrix back AFTER the solve
1609: BE CAREFUL with this routine: it actually scales the matrix and right
1610: hand side that define the system. After the system is solved the matrix
1611: and right hand side remain scaled.
1613: This routine is only used if the matrix and preconditioner matrix are
1614: the same thing.
1616: This should NOT be used within the SNES solves if you are using a line
1617: search.
1618:
1619: If you use this with the PCType Eisenstat preconditioner than you can
1620: use the PCEisenstatNoDiagonalScaling() option, or -pc_eisenstat_no_diagonal_scaling
1621: to save some unneeded, redundant flops.
1623: Level: intermediate
1625: .keywords: KSP, set, options, prefix, database
1627: .seealso: KSPGetDiagonalScale(), KSPSetDiagonalScaleFix()
1628: @*/
1629: PetscErrorCode KSPSetDiagonalScale(KSP ksp,PetscTruth scale)
1630: {
1633: ksp->dscale = scale;
1634: return(0);
1635: }
1639: /*@C
1640: KSPGetDiagonalScale - Checks if KSP solver scales the matrix and
1641: right hand side
1643: Not Collective
1645: Input Parameter:
1646: . ksp - the KSP context
1648: Output Parameter:
1649: . scale - PETSC_TRUE or PETSC_FALSE
1651: Notes:
1652: BE CAREFUL with this routine: it actually scales the matrix and right
1653: hand side that define the system. After the system is solved the matrix
1654: and right hand side remain scaled.
1656: This routine is only used if the matrix and preconditioner matrix are
1657: the same thing.
1659: Level: intermediate
1661: .keywords: KSP, set, options, prefix, database
1663: .seealso: KSPSetDiagonalScale(), KSPSetDiagonalScaleFix()
1664: @*/
1665: PetscErrorCode KSPGetDiagonalScale(KSP ksp,PetscTruth *scale)
1666: {
1670: *scale = ksp->dscale;
1671: return(0);
1672: }
1676: /*@
1677: KSPSetDiagonalScaleFix - Tells KSP to diagonally scale the system
1678: back after solving.
1680: Collective on KSP
1682: Input Parameter:
1683: + ksp - the KSP context
1684: - fix - PETSC_TRUE to scale back after the system solve, PETSC_FALSE to not
1685: rescale (default)
1687: Notes:
1688: Must be called after KSPSetDiagonalScale()
1690: Using this will slow things down, because it rescales the matrix before and
1691: after each linear solve. This is intended mainly for testing to allow one
1692: to easily get back the original system to make sure the solution computed is
1693: accurate enough.
1695: This routine is only used if the matrix and preconditioner matrix are
1696: the same thing.
1698: Level: intermediate
1700: .keywords: KSP, set, options, prefix, database
1702: .seealso: KSPGetDiagonalScale(), KSPSetDiagonalScale(), KSPGetDiagonalScaleFix()
1703: @*/
1704: PetscErrorCode KSPSetDiagonalScaleFix(KSP ksp,PetscTruth fix)
1705: {
1708: ksp->dscalefix = fix;
1709: return(0);
1710: }
1714: /*@
1715: KSPGetDiagonalScaleFix - Determines if KSP diagonally scales the system
1716: back after solving.
1718: Collective on KSP
1720: Input Parameter:
1721: . ksp - the KSP context
1723: Output Parameter:
1724: . fix - PETSC_TRUE to scale back after the system solve, PETSC_FALSE to not
1725: rescale (default)
1727: Notes:
1728: Must be called after KSPSetDiagonalScale()
1730: If PETSC_TRUE will slow things down, because it rescales the matrix before and
1731: after each linear solve. This is intended mainly for testing to allow one
1732: to easily get back the original system to make sure the solution computed is
1733: accurate enough.
1735: This routine is only used if the matrix and preconditioner matrix are
1736: the same thing.
1738: Level: intermediate
1740: .keywords: KSP, set, options, prefix, database
1742: .seealso: KSPGetDiagonalScale(), KSPSetDiagonalScale(), KSPSetDiagonalScaleFix()
1743: @*/
1744: PetscErrorCode KSPGetDiagonalScaleFix(KSP ksp,PetscTruth *fix)
1745: {
1749: *fix = ksp->dscalefix;
1750: return(0);
1751: }