Actual source code: itfunc.c
1: #define PETSCKSP_DLL
3: /*
4: Interface KSP routines that the user calls.
5: */
7: #include src/ksp/ksp/kspimpl.h
11: /*@
12: KSPComputeExtremeSingularValues - Computes the extreme singular values
13: for the preconditioned operator. Called after or during KSPSolve().
15: Not Collective
17: Input Parameter:
18: . ksp - iterative context obtained from KSPCreate()
20: Output Parameters:
21: . emin, emax - extreme singular values
23: Notes:
24: One must call KSPSetComputeSingularValues() before calling KSPSetUp()
25: (or use the option -ksp_compute_eigenvalues) in order for this routine to work correctly.
27: Many users may just want to use the monitoring routine
28: KSPSingularValueMonitor() (which can be set with option -ksp_singmonitor)
29: to print the extreme singular values at each iteration of the linear solve.
31: Level: advanced
33: .keywords: KSP, compute, extreme, singular, values
35: .seealso: KSPSetComputeSingularValues(), KSPSingularValueMonitor(), KSPComputeEigenvalues()
36: @*/
37: PetscErrorCode KSPComputeExtremeSingularValues(KSP ksp,PetscReal *emax,PetscReal *emin)
38: {
45: if (!ksp->calc_sings) {
46: SETERRQ(4,"Singular values not requested before KSPSetUp()");
47: }
49: if (ksp->ops->computeextremesingularvalues) {
50: (*ksp->ops->computeextremesingularvalues)(ksp,emax,emin);
51: } else {
52: *emin = -1.0;
53: *emax = -1.0;
54: }
55: return(0);
56: }
60: /*@
61: KSPComputeEigenvalues - Computes the extreme eigenvalues for the
62: preconditioned operator. Called after or during KSPSolve().
64: Not Collective
66: Input Parameter:
67: + ksp - iterative context obtained from KSPCreate()
68: - n - size of arrays r and c. The number of eigenvalues computed (neig) will, in
69: general, be less than this.
71: Output Parameters:
72: + r - real part of computed eigenvalues
73: . c - complex part of computed eigenvalues
74: - neig - number of eigenvalues computed (will be less than or equal to n)
76: Options Database Keys:
77: + -ksp_compute_eigenvalues - Prints eigenvalues to stdout
78: - -ksp_plot_eigenvalues - Plots eigenvalues in an x-window display
80: Notes:
81: The number of eigenvalues estimated depends on the size of the Krylov space
82: generated during the KSPSolve() ; for example, with
83: CG it corresponds to the number of CG iterations, for GMRES it is the number
84: of GMRES iterations SINCE the last restart. Any extra space in r[] and c[]
85: will be ignored.
87: KSPComputeEigenvalues() does not usually provide accurate estimates; it is
88: intended only for assistance in understanding the convergence of iterative
89: methods, not for eigenanalysis.
91: One must call KSPSetComputeEigenvalues() before calling KSPSetUp()
92: in order for this routine to work correctly.
94: Many users may just want to use the monitoring routine
95: KSPSingularValueMonitor() (which can be set with option -ksp_singmonitor)
96: to print the singular values at each iteration of the linear solve.
98: Level: advanced
100: .keywords: KSP, compute, extreme, singular, values
102: .seealso: KSPSetComputeSingularValues(), KSPSingularValueMonitor(), KSPComputeExtremeSingularValues()
103: @*/
104: PetscErrorCode 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
268: . -ksp_final_residual - print 2-norm of true linear system residual at the end of the solution process
269: - -ksp_view - print the ksp data structure at the end of the system solution
271: Notes:
273: The operator is specified with PCSetOperators().
275: Call KSPGetConvergedReason() to determine if the solver converged or failed and
276: why. The number of iterations can be obtained from KSPGetIterationNumber().
277:
278: If using a direct method (e.g., via the KSP solver
279: KSPPREONLY and a preconditioner such as PCLU/PCILU),
280: then its=1. See KSPSetTolerances() and KSPDefaultConverged()
281: for more details.
283: Understanding Convergence:
284: The routines KSPSetMonitor(), KSPComputeEigenvalues(), and
285: KSPComputeEigenvaluesExplicitly() provide information on additional
286: options to monitor convergence and print eigenvalue information.
288: Level: beginner
290: .keywords: KSP, solve, linear system
292: .seealso: KSPCreate(), KSPSetUp(), KSPDestroy(), KSPSetTolerances(), KSPDefaultConverged(),
293: KSPSolveTranspose(), KSPGetIterationNumber()
294: @*/
295: PetscErrorCode 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: ksp->vec_rhs = b;
315: ksp->vec_sol = x;
316: PetscOptionsHasName(ksp->prefix,"-ksp_view_binary",&flg);
317: if (flg) {
318: Mat mat;
319: PCGetOperators(ksp->pc,&mat,PETSC_NULL,PETSC_NULL);
320: MatView(mat,PETSC_VIEWER_BINARY_(ksp->comm));
321: VecView(ksp->vec_rhs,PETSC_VIEWER_BINARY_(ksp->comm));
322: }
326: /* reset the residual history list if requested */
327: if (ksp->res_hist_reset) ksp->res_hist_len = 0;
329: PetscOptionsGetString(ksp->prefix,"-ksp_view",view,10,&flg);
330: if (flg) {
331: PetscStrcmp(view,"before",&viewed);
332: if (viewed){
333: KSPView(ksp,PETSC_VIEWER_STDOUT_(ksp->comm));
334: }
335: }
337: /* KSPSetUp() scales the matrix if needed */
338: KSPSetUp(ksp);
339: KSPSetUpOnBlocks(ksp);
341: ksp->transpose_solve = PETSC_FALSE;
343: /* diagonal scale RHS if called for */
344: if (ksp->dscale) {
345: VecPointwiseMult(ksp->vec_rhs,ksp->vec_rhs,ksp->diagonal);
346: /* second time in, but matrix was scaled back to original */
347: if (ksp->dscalefix && ksp->dscalefix2) {
348: Mat mat;
350: PCGetOperators(ksp->pc,&mat,PETSC_NULL,PETSC_NULL);
351: MatDiagonalScale(mat,ksp->diagonal,ksp->diagonal);
352: }
354: /* scale initial guess */
355: if (!ksp->guess_zero) {
356: if (!ksp->truediagonal) {
357: VecDuplicate(ksp->diagonal,&ksp->truediagonal);
358: VecCopy(ksp->diagonal,ksp->truediagonal);
359: VecReciprocal(ksp->truediagonal);
360: }
361: VecPointwiseMult(ksp->vec_sol,ksp->vec_sol,ksp->truediagonal);
362: }
363: }
364: PCPreSolve(ksp->pc,ksp);
366: if (ksp->guess_zero) { VecSet(ksp->vec_sol,0.0);}
367: if (ksp->guess_knoll) {
368: PCApply(ksp->pc,ksp->vec_rhs,ksp->vec_sol);
369: KSP_RemoveNullSpace(ksp,ksp->vec_sol);
370: ksp->guess_zero = PETSC_FALSE;
371: }
372: (*ksp->ops->solve)(ksp);
373: if (!ksp->reason) {
374: SETERRQ(PETSC_ERR_PLIB,"Internal error, solver returned without setting converged reason");
375: }
376: if (ksp->printreason) {
377: if (ksp->reason > 0) {
378: PetscPrintf(ksp->comm,"Linear solve converged due to %s\n",KSPConvergedReasons[ksp->reason]);
379: } else {
380: PetscPrintf(ksp->comm,"Linear solve did not converge due to %s\n",KSPConvergedReasons[ksp->reason]);
381: }
382: }
384: /* diagonal scale solution if called for */
385: PCPostSolve(ksp->pc,ksp);
386: if (ksp->dscale) {
387: VecPointwiseMult(ksp->vec_sol,ksp->vec_sol,ksp->diagonal);
388: /* unscale right hand side and matrix */
389: if (ksp->dscalefix) {
390: Mat mat;
392: VecReciprocal(ksp->diagonal);
393: VecPointwiseMult(ksp->vec_rhs,ksp->vec_rhs,ksp->diagonal);
394: PCGetOperators(ksp->pc,&mat,PETSC_NULL,PETSC_NULL);
395: MatDiagonalScale(mat,ksp->diagonal,ksp->diagonal);
396: VecReciprocal(ksp->diagonal);
397: ksp->dscalefix2 = PETSC_TRUE;
398: }
399: }
402: MPI_Comm_rank(ksp->comm,&rank);
404: PetscOptionsHasName(ksp->prefix,"-ksp_compute_eigenvalues",&flag1);
405: PetscOptionsHasName(ksp->prefix,"-ksp_plot_eigenvalues",&flag2);
406: if (flag1 || flag2) {
407: PetscInt nits,n,i,neig;
408: PetscReal *r,*c;
409:
410: KSPGetIterationNumber(ksp,&nits);
411: n = nits+2;
413: if (!n) {
414: PetscPrintf(ksp->comm,"Zero iterations in solver, cannot approximate any eigenvalues\n");
415: } else {
416: PetscMalloc(2*n*sizeof(PetscReal),&r);
417: c = r + n;
418: KSPComputeEigenvalues(ksp,n,r,c,&neig);
419: if (flag1) {
420: PetscPrintf(ksp->comm,"Iteratively computed eigenvalues\n");
421: for (i=0; i<neig; i++) {
422: if (c[i] >= 0.0) {PetscPrintf(ksp->comm,"%G + %Gi\n",r[i],c[i]);}
423: else {PetscPrintf(ksp->comm,"%G - %Gi\n",r[i],-c[i]);}
424: }
425: }
426: if (flag2 && !rank) {
427: PetscDraw draw;
428: PetscDrawSP drawsp;
430: PetscViewerDrawOpen(PETSC_COMM_SELF,0,"Iteratively Computed Eigenvalues",PETSC_DECIDE,PETSC_DECIDE,300,300,&viewer);
431: PetscViewerDrawGetDraw(viewer,0,&draw);
432: PetscDrawSPCreate(draw,1,&drawsp);
433: for (i=0; i<neig; i++) {
434: PetscDrawSPAddPoint(drawsp,r+i,c+i);
435: }
436: PetscDrawSPDraw(drawsp);
437: PetscDrawSPDestroy(drawsp);
438: PetscViewerDestroy(viewer);
439: }
440: PetscFree(r);
441: }
442: }
444: PetscOptionsHasName(ksp->prefix,"-ksp_compute_eigenvalues_explicitly",&flag1);
445: PetscOptionsHasName(ksp->prefix,"-ksp_plot_eigenvalues_explicitly",&flag2);
446: if (flag1 || flag2) {
447: PetscInt n,i;
448: PetscReal *r,*c;
449: VecGetSize(ksp->vec_sol,&n);
450: PetscMalloc(2*n*sizeof(PetscReal),&r);
451: c = r + n;
452: KSPComputeEigenvaluesExplicitly(ksp,n,r,c);
453: if (flag1) {
454: PetscPrintf(ksp->comm,"Explicitly computed eigenvalues\n");
455: for (i=0; i<n; i++) {
456: if (c[i] >= 0.0) {PetscPrintf(ksp->comm,"%G + %Gi\n",r[i],c[i]);}
457: else {PetscPrintf(ksp->comm,"%G - %Gi\n",r[i],-c[i]);}
458: }
459: }
460: if (flag2 && !rank) {
461: PetscDraw draw;
462: PetscDrawSP drawsp;
464: PetscViewerDrawOpen(PETSC_COMM_SELF,0,"Explicitly Computed Eigenvalues",0,320,300,300,&viewer);
465: PetscViewerDrawGetDraw(viewer,0,&draw);
466: PetscDrawSPCreate(draw,1,&drawsp);
467: for (i=0; i<n; i++) {
468: PetscDrawSPAddPoint(drawsp,r+i,c+i);
469: }
470: PetscDrawSPDraw(drawsp);
471: PetscDrawSPDestroy(drawsp);
472: PetscViewerDestroy(viewer);
473: }
474: PetscFree(r);
475: }
477: PetscOptionsHasName(ksp->prefix,"-ksp_view_operator",&flag2);
478: if (flag2) {
479: Mat A,B;
480: PCGetOperators(ksp->pc,&A,PETSC_NULL,PETSC_NULL);
481: MatComputeExplicitOperator(A,&B);
482: PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(ksp->comm),PETSC_VIEWER_ASCII_MATLAB);
483: MatView(B,PETSC_VIEWER_STDOUT_(ksp->comm));
484: PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(ksp->comm));
485: MatDestroy(B);
486: }
487: PetscOptionsHasName(ksp->prefix,"-ksp_view_operator_binary",&flag2);
488: if (flag2) {
489: Mat A,B;
490: PCGetOperators(ksp->pc,&A,PETSC_NULL,PETSC_NULL);
491: MatComputeExplicitOperator(A,&B);
492: MatView(B,PETSC_VIEWER_BINARY_(ksp->comm));
493: MatDestroy(B);
494: }
495: PetscOptionsHasName(ksp->prefix,"-ksp_view_preconditioned_operator_binary",&flag2);
496: if (flag2) {
497: Mat B;
498: KSPComputeExplicitOperator(ksp,&B);
499: MatView(B,PETSC_VIEWER_BINARY_(ksp->comm));
500: MatDestroy(B);
501: }
502: if (!viewed) {
503: PetscOptionsGetString(ksp->prefix,"-ksp_view",filename,PETSC_MAX_PATH_LEN,&flg);
504: if (flg && !PetscPreLoadingOn) {
505: PetscViewerASCIIOpen(ksp->comm,filename,&viewer);
506: KSPView(ksp,viewer);
507: PetscViewerDestroy(viewer);
508: }
509: }
510: PetscOptionsHasName(ksp->prefix,"-ksp_final_residual",&flg);
511: if (flg) {
512: Mat A;
513: Vec t;
514: PetscReal norm;
515: 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");
516: PCGetOperators(ksp->pc,&A,0,0);
517: VecDuplicate(ksp->vec_sol,&t);
518: KSP_MatMult(ksp,A,ksp->vec_sol,t);
519: VecWAXPY(t,-1.0,t,ksp->vec_rhs);
520: VecNorm(t,NORM_2,&norm);
521: VecDestroy(t);
522: PetscPrintf(ksp->comm,"KSP final norm of residual %G\n",norm);
523: }
525: if (inXisinB) {
526: VecCopy(x,b);
527: VecDestroy(x);
528: }
529: return(0);
530: }
534: /*@
535: KSPSolveTranspose - Solves the transpose of a linear system. Usually
536: accessed through KSPSolveTranspose().
538: Collective on KSP
540: Input Parameter:
541: + ksp - iterative context obtained from KSPCreate()
542: . b - right hand side vector
543: - x - solution vector
545: Note:
546: Currently only supported by KSPType of KSPPREONLY. This routine is usally
547: only used internally by the BiCG solver on the subblocks in BJacobi and ASM.
549: Level: developer
551: .keywords: KSP, solve, linear system
553: .seealso: KSPCreate(), KSPSetUp(), KSPDestroy(), KSPSetTolerances(), KSPDefaultConverged(),
554: KSPSolve()
555: @*/
556: PetscErrorCode KSPSolveTranspose(KSP ksp,Vec b,Vec x)
557: {
559: PetscScalar zero = 0.0;
566: ksp->vec_rhs = b;
567: ksp->vec_sol = x;
568: KSPSetUp(ksp);
569: if (ksp->guess_zero) { VecSet(ksp->vec_sol,zero);}
570: ksp->transpose_solve = PETSC_TRUE;
571: (*ksp->ops->solve)(ksp);
572: return(0);
573: }
577: /*@
578: KSPDestroy - Destroys KSP context.
580: Collective on KSP
582: Input Parameter:
583: . ksp - iterative context obtained from KSPCreate()
585: Level: beginner
587: .keywords: KSP, destroy
589: .seealso: KSPCreate(), KSPSetUp(), KSPSolve()
590: @*/
591: PetscErrorCode KSPDestroy(KSP ksp)
592: {
597: if (--ksp->refct > 0) return(0);
599: /* if memory was published with AMS then destroy it */
600: PetscObjectDepublish(ksp);
602: if (ksp->ops->destroy) {
603: (*ksp->ops->destroy)(ksp);
604: }
605: KSPClearMonitor(ksp);
606: PCDestroy(ksp->pc);
607: if (ksp->diagonal) {VecDestroy(ksp->diagonal);}
608: if (ksp->truediagonal) {VecDestroy(ksp->truediagonal);}
609: if (ksp->nullsp) {MatNullSpaceDestroy(ksp->nullsp);}
610: PetscHeaderDestroy(ksp);
611: return(0);
612: }
616: /*@
617: KSPSetPreconditionerSide - Sets the preconditioning side.
619: Collective on KSP
621: Input Parameter:
622: . ksp - iterative context obtained from KSPCreate()
624: Output Parameter:
625: . side - the preconditioning side, where side is one of
626: .vb
627: PC_LEFT - left preconditioning (default)
628: PC_RIGHT - right preconditioning
629: PC_SYMMETRIC - symmetric preconditioning
630: .ve
632: Options Database Keys:
633: + -ksp_left_pc - Sets left preconditioning
634: . -ksp_right_pc - Sets right preconditioning
635: - -ksp_symmetric_pc - Sets symmetric preconditioning
637: Notes:
638: Left preconditioning is used by default. Symmetric preconditioning is
639: currently available only for the KSPQCG method. Note, however, that
640: symmetric preconditioning can be emulated by using either right or left
641: preconditioning and a pre or post processing step.
643: Level: intermediate
645: .keywords: KSP, set, right, left, symmetric, side, preconditioner, flag
647: .seealso: KSPGetPreconditionerSide()
648: @*/
649: PetscErrorCode KSPSetPreconditionerSide(KSP ksp,PCSide side)
650: {
653: ksp->pc_side = side;
654: return(0);
655: }
659: /*@
660: KSPGetPreconditionerSide - Gets the preconditioning side.
662: Not Collective
664: Input Parameter:
665: . ksp - iterative context obtained from KSPCreate()
667: Output Parameter:
668: . side - the preconditioning side, where side is one of
669: .vb
670: PC_LEFT - left preconditioning (default)
671: PC_RIGHT - right preconditioning
672: PC_SYMMETRIC - symmetric preconditioning
673: .ve
675: Level: intermediate
677: .keywords: KSP, get, right, left, symmetric, side, preconditioner, flag
679: .seealso: KSPSetPreconditionerSide()
680: @*/
681: PetscErrorCode KSPGetPreconditionerSide(KSP ksp,PCSide *side)
682: {
686: *side = ksp->pc_side;
687: return(0);
688: }
692: /*@
693: KSPGetTolerances - Gets the relative, absolute, divergence, and maximum
694: iteration tolerances used by the default KSP convergence tests.
696: Not Collective
698: Input Parameter:
699: . ksp - the Krylov subspace context
700:
701: Output Parameters:
702: + rtol - the relative convergence tolerance
703: . abstol - the absolute convergence tolerance
704: . dtol - the divergence tolerance
705: - maxits - maximum number of iterations
707: Notes:
708: The user can specify PETSC_NULL for any parameter that is not needed.
710: Level: intermediate
712: .keywords: KSP, get, tolerance, absolute, relative, divergence, convergence,
713: maximum, iterations
715: .seealso: KSPSetTolerances()
716: @*/
717: PetscErrorCode KSPGetTolerances(KSP ksp,PetscReal *rtol,PetscReal *abstol,PetscReal *dtol,PetscInt *maxits)
718: {
721: if (abstol) *abstol = ksp->abstol;
722: if (rtol) *rtol = ksp->rtol;
723: if (dtol) *dtol = ksp->divtol;
724: if (maxits) *maxits = ksp->max_it;
725: return(0);
726: }
730: /*@
731: KSPSetTolerances - Sets the relative, absolute, divergence, and maximum
732: iteration tolerances used by the default KSP convergence testers.
734: Collective on KSP
736: Input Parameters:
737: + ksp - the Krylov subspace context
738: . rtol - the relative convergence tolerance
739: (relative decrease in the residual norm)
740: . abstol - the absolute convergence tolerance
741: (absolute size of the residual norm)
742: . dtol - the divergence tolerance
743: (amount residual can increase before KSPDefaultConverged()
744: concludes that the method is diverging)
745: - maxits - maximum number of iterations to use
747: Options Database Keys:
748: + -ksp_atol <abstol> - Sets abstol
749: . -ksp_rtol <rtol> - Sets rtol
750: . -ksp_divtol <dtol> - Sets dtol
751: - -ksp_max_it <maxits> - Sets maxits
753: Notes:
754: Use PETSC_DEFAULT to retain the default value of any of the tolerances.
756: See KSPDefaultConverged() for details on the use of these parameters
757: in the default convergence test. See also KSPSetConvergenceTest()
758: for setting user-defined stopping criteria.
760: Level: intermediate
762: .keywords: KSP, set, tolerance, absolute, relative, divergence,
763: convergence, maximum, iterations
765: .seealso: KSPGetTolerances(), KSPDefaultConverged(), KSPSetConvergenceTest()
766: @*/
767: PetscErrorCode KSPSetTolerances(KSP ksp,PetscReal rtol,PetscReal abstol,PetscReal dtol,PetscInt maxits)
768: {
771: if (abstol != PETSC_DEFAULT) ksp->abstol = abstol;
772: if (rtol != PETSC_DEFAULT) ksp->rtol = rtol;
773: if (dtol != PETSC_DEFAULT) ksp->divtol = dtol;
774: if (maxits != PETSC_DEFAULT) ksp->max_it = maxits;
775: return(0);
776: }
780: /*@
781: KSPSetInitialGuessNonzero - Tells the iterative solver that the
782: initial guess is nonzero; otherwise KSP assumes the initial guess
783: is to be zero (and thus zeros it out before solving).
785: Collective on KSP
787: Input Parameters:
788: + ksp - iterative context obtained from KSPCreate()
789: - flg - PETSC_TRUE indicates the guess is non-zero, PETSC_FALSE indicates the guess is zero
791: Level: beginner
793: Notes:
794: If this is not called the X vector is zeroed in the call to KSPSolve().
796: .keywords: KSP, set, initial guess, nonzero
798: .seealso: KSPGetInitialGuessNonzero(), KSPSetInitialGuessKnoll(), KSPGetInitialGuessKnoll()
799: @*/
800: PetscErrorCode KSPSetInitialGuessNonzero(KSP ksp,PetscTruth flg)
801: {
803: ksp->guess_zero = (PetscTruth)!(int)flg;
804: return(0);
805: }
809: /*@
810: KSPGetInitialGuessNonzero - Determines whether the KSP solver is using
811: a zero initial guess.
813: Not Collective
815: Input Parameter:
816: . ksp - iterative context obtained from KSPCreate()
818: Output Parameter:
819: . flag - PETSC_TRUE if guess is nonzero, else PETSC_FALSE
821: Level: intermediate
823: .keywords: KSP, set, initial guess, nonzero
825: .seealso: KSPSetInitialGuessNonzero(), KSPSetInitialGuessKnoll(), KSPGetInitialGuessKnoll()
826: @*/
827: PetscErrorCode KSPGetInitialGuessNonzero(KSP ksp,PetscTruth *flag)
828: {
830: if (ksp->guess_zero) *flag = PETSC_FALSE;
831: else *flag = PETSC_TRUE;
832: return(0);
833: }
837: /*@
838: KSPSetInitialGuessKnoll - Tells the iterative solver to use PCApply(pc,b,..) to compute the initial guess (The Knoll trick)
840: Collective on KSP
842: Input Parameters:
843: + ksp - iterative context obtained from KSPCreate()
844: - flg - PETSC_TRUE or PETSC_FALSE
846: Level: advanced
849: .keywords: KSP, set, initial guess, nonzero
851: .seealso: KSPGetInitialGuessKnoll(), KSPSetInitialGuessNonzero(), KSPGetInitialGuessNonzero()
852: @*/
853: PetscErrorCode KSPSetInitialGuessKnoll(KSP ksp,PetscTruth flg)
854: {
856: ksp->guess_knoll = flg;
857: return(0);
858: }
862: /*@
863: KSPGetInitialGuessKnoll - Determines whether the KSP solver is using the Knoll trick (using PCApply(pc,b,...) to compute
864: the initial guess
866: Not Collective
868: Input Parameter:
869: . ksp - iterative context obtained from KSPCreate()
871: Output Parameter:
872: . flag - PETSC_TRUE if using Knoll trick, else PETSC_FALSE
874: Level: advanced
876: .keywords: KSP, set, initial guess, nonzero
878: .seealso: KSPSetInitialGuessKnoll(), KSPSetInitialGuessNonzero(), KSPGetInitialGuessNonzero()
879: @*/
880: PetscErrorCode KSPGetInitialGuessKnoll(KSP ksp,PetscTruth *flag)
881: {
883: *flag = ksp->guess_knoll;
884: return(0);
885: }
889: /*@
890: KSPGetComputeSingularValues - Gets the flag indicating whether the extreme singular
891: values will be calculated via a Lanczos or Arnoldi process as the linear
892: system is solved.
894: Collective on KSP
896: Input Parameter:
897: . ksp - iterative context obtained from KSPCreate()
899: Output Parameter:
900: . flg - PETSC_TRUE or PETSC_FALSE
902: Options Database Key:
903: . -ksp_singmonitor - Activates KSPSetComputeSingularValues()
905: Notes:
906: Currently this option is not valid for all iterative methods.
908: Many users may just want to use the monitoring routine
909: KSPSingularValueMonitor() (which can be set with option -ksp_singmonitor)
910: to print the singular values at each iteration of the linear solve.
912: Level: advanced
914: .keywords: KSP, set, compute, singular values
916: .seealso: KSPComputeExtremeSingularValues(), KSPSingularValueMonitor()
917: @*/
918: PetscErrorCode KSPGetComputeSingularValues(KSP ksp,PetscTruth *flg)
919: {
923: *flg = ksp->calc_sings;
924: return(0);
925: }
929: /*@
930: KSPSetComputeSingularValues - Sets a flag so that the extreme singular
931: values will be calculated via a Lanczos or Arnoldi process as the linear
932: system is solved.
934: Collective on KSP
936: Input Parameters:
937: + ksp - iterative context obtained from KSPCreate()
938: - flg - PETSC_TRUE or PETSC_FALSE
940: Options Database Key:
941: . -ksp_singmonitor - Activates KSPSetComputeSingularValues()
943: Notes:
944: Currently this option is not valid for all iterative methods.
946: Many users may just want to use the monitoring routine
947: KSPSingularValueMonitor() (which can be set with option -ksp_singmonitor)
948: to print the singular values at each iteration of the linear solve.
950: Level: advanced
952: .keywords: KSP, set, compute, singular values
954: .seealso: KSPComputeExtremeSingularValues(), KSPSingularValueMonitor()
955: @*/
956: PetscErrorCode KSPSetComputeSingularValues(KSP ksp,PetscTruth flg)
957: {
960: ksp->calc_sings = flg;
961: return(0);
962: }
966: /*@
967: KSPGetComputeEigenvalues - Gets the flag indicating that the extreme eigenvalues
968: values will be calculated via a Lanczos or Arnoldi process as the linear
969: system is solved.
971: Collective on KSP
973: Input Parameter:
974: . ksp - iterative context obtained from KSPCreate()
976: Output Parameter:
977: . flg - PETSC_TRUE or PETSC_FALSE
979: Notes:
980: Currently this option is not valid for all iterative methods.
982: Level: advanced
984: .keywords: KSP, set, compute, eigenvalues
986: .seealso: KSPComputeEigenvalues(), KSPComputeEigenvaluesExplicitly()
987: @*/
988: PetscErrorCode KSPGetComputeEigenvalues(KSP ksp,PetscTruth *flg)
989: {
993: *flg = ksp->calc_sings;
994: return(0);
995: }
999: /*@
1000: KSPSetComputeEigenvalues - Sets a flag so that the extreme eigenvalues
1001: values will be calculated via a Lanczos or Arnoldi process as the linear
1002: system is solved.
1004: Collective on KSP
1006: Input Parameters:
1007: + ksp - iterative context obtained from KSPCreate()
1008: - flg - PETSC_TRUE or PETSC_FALSE
1010: Notes:
1011: Currently this option is not valid for all iterative methods.
1013: Level: advanced
1015: .keywords: KSP, set, compute, eigenvalues
1017: .seealso: KSPComputeEigenvalues(), KSPComputeEigenvaluesExplicitly()
1018: @*/
1019: PetscErrorCode KSPSetComputeEigenvalues(KSP ksp,PetscTruth flg)
1020: {
1023: ksp->calc_sings = flg;
1024: return(0);
1025: }
1029: /*@
1030: KSPGetRhs - Gets the right-hand-side vector for the linear system to
1031: be solved.
1033: Not Collective
1035: Input Parameter:
1036: . ksp - iterative context obtained from KSPCreate()
1038: Output Parameter:
1039: . r - right-hand-side vector
1041: Level: developer
1043: .keywords: KSP, get, right-hand-side, rhs
1045: .seealso: KSPGetSolution(), KSPSolve()
1046: @*/
1047: PetscErrorCode KSPGetRhs(KSP ksp,Vec *r)
1048: {
1051: *r = ksp->vec_rhs;
1052: return(0);
1053: }
1057: /*@
1058: KSPGetSolution - Gets the location of the solution for the
1059: linear system to be solved. Note that this may not be where the solution
1060: is stored during the iterative process; see KSPBuildSolution().
1062: Not Collective
1064: Input Parameters:
1065: . ksp - iterative context obtained from KSPCreate()
1067: Output Parameters:
1068: . v - solution vector
1070: Level: developer
1072: .keywords: KSP, get, solution
1074: .seealso: KSPGetRhs(), KSPBuildSolution(), KSPSolve()
1075: @*/
1076: PetscErrorCode KSPGetSolution(KSP ksp,Vec *v)
1077: {
1081: *v = ksp->vec_sol;
1082: return(0);
1083: }
1087: /*@
1088: KSPSetPC - Sets the preconditioner to be used to calculate the
1089: application of the preconditioner on a vector.
1091: Collective on KSP
1093: Input Parameters:
1094: + ksp - iterative context obtained from KSPCreate()
1095: - pc - the preconditioner object
1097: Notes:
1098: Use KSPGetPC() to retrieve the preconditioner context (for example,
1099: to free it at the end of the computations).
1101: Level: developer
1103: .keywords: KSP, set, precondition, Binv
1105: .seealso: KSPGetPC()
1106: @*/
1107: PetscErrorCode KSPSetPC(KSP ksp,PC pc)
1108: {
1115: if (ksp->pc) {PCDestroy(ksp->pc);}
1116: ksp->pc = pc;
1117: PetscObjectReference((PetscObject)ksp->pc);
1118: return(0);
1119: }
1123: /*@
1124: KSPGetPC - Returns a pointer to the preconditioner context
1125: set with KSPSetPC().
1127: Not Collective
1129: Input Parameters:
1130: . ksp - iterative context obtained from KSPCreate()
1132: Output Parameter:
1133: . pc - preconditioner context
1135: Level: developer
1137: .keywords: KSP, get, preconditioner, Binv
1139: .seealso: KSPSetPC()
1140: @*/
1141: PetscErrorCode KSPGetPC(KSP ksp,PC *pc)
1142: {
1146: *pc = ksp->pc;
1147: return(0);
1148: }
1152: /*@C
1153: KSPSetMonitor - Sets an ADDITIONAL function to be called at every iteration to monitor
1154: the residual/error etc.
1155:
1156: Collective on KSP
1158: Input Parameters:
1159: + ksp - iterative context obtained from KSPCreate()
1160: . monitor - pointer to function (if this is PETSC_NULL, it turns off monitoring
1161: . mctx - [optional] context for private data for the
1162: monitor routine (use PETSC_NULL if no context is desired)
1163: - monitordestroy - [optional] routine that frees monitor context
1164: (may be PETSC_NULL)
1166: Calling Sequence of monitor:
1167: $ monitor (KSP ksp, int it, PetscReal rnorm, void *mctx)
1169: + ksp - iterative context obtained from KSPCreate()
1170: . it - iteration number
1171: . rnorm - (estimated) 2-norm of (preconditioned) residual
1172: - mctx - optional monitoring context, as set by KSPSetMonitor()
1174: Options Database Keys:
1175: + -ksp_monitor - sets KSPDefaultMonitor()
1176: . -ksp_truemonitor - sets KSPTrueMonitor()
1177: . -ksp_xmonitor - sets line graph monitor,
1178: uses KSPLGMonitorCreate()
1179: . -ksp_xtruemonitor - sets line graph monitor,
1180: uses KSPLGMonitorCreate()
1181: . -ksp_singmonitor - sets KSPSingularValueMonitor()
1182: - -ksp_cancelmonitors - cancels all monitors that have
1183: been hardwired into a code by
1184: calls to KSPSetMonitor(), but
1185: does not cancel those set via
1186: the options database.
1188: Notes:
1189: The default is to do nothing. To print the residual, or preconditioned
1190: residual if KSPSetNormType(ksp,KSP_PRECONDITIONED_NORM) was called, use
1191: KSPDefaultMonitor() as the monitoring routine, with a null monitoring
1192: context.
1194: Several different monitoring routines may be set by calling
1195: KSPSetMonitor() multiple times; all will be called in the
1196: order in which they were set.
1198: Level: beginner
1200: .keywords: KSP, set, monitor
1202: .seealso: KSPDefaultMonitor(), KSPLGMonitorCreate(), KSPClearMonitor()
1203: @*/
1204: PetscErrorCode KSPSetMonitor(KSP ksp,PetscErrorCode (*monitor)(KSP,PetscInt,PetscReal,void*),void *mctx,PetscErrorCode (*monitordestroy)(void*))
1205: {
1208: if (ksp->numbermonitors >= MAXKSPMONITORS) {
1209: SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Too many KSP monitors set");
1210: }
1211: ksp->monitor[ksp->numbermonitors] = monitor;
1212: ksp->monitordestroy[ksp->numbermonitors] = monitordestroy;
1213: ksp->monitorcontext[ksp->numbermonitors++] = (void*)mctx;
1214: return(0);
1215: }
1219: /*@
1220: KSPClearMonitor - Clears all monitors for a KSP object.
1222: Collective on KSP
1224: Input Parameters:
1225: . ksp - iterative context obtained from KSPCreate()
1227: Options Database Key:
1228: . -ksp_cancelmonitors - Cancels all monitors that have
1229: been hardwired into a code by calls to KSPSetMonitor(),
1230: but does not cancel those set via the options database.
1232: Level: intermediate
1234: .keywords: KSP, set, monitor
1236: .seealso: KSPDefaultMonitor(), KSPLGMonitorCreate(), KSPSetMonitor()
1237: @*/
1238: PetscErrorCode KSPClearMonitor(KSP ksp)
1239: {
1241: PetscInt i;
1245: for (i=0; i<ksp->numbermonitors; i++) {
1246: if (ksp->monitordestroy[i]) {
1247: (*ksp->monitordestroy[i])(ksp->monitorcontext[i]);
1248: }
1249: }
1250: ksp->numbermonitors = 0;
1251: return(0);
1252: }
1256: /*@C
1257: KSPGetMonitorContext - Gets the monitoring context, as set by
1258: KSPSetMonitor() for the FIRST monitor only.
1260: Not Collective
1262: Input Parameter:
1263: . ksp - iterative context obtained from KSPCreate()
1265: Output Parameter:
1266: . ctx - monitoring context
1268: Level: intermediate
1270: .keywords: KSP, get, monitor, context
1272: .seealso: KSPDefaultMonitor(), KSPLGMonitorCreate()
1273: @*/
1274: PetscErrorCode KSPGetMonitorContext(KSP ksp,void **ctx)
1275: {
1278: *ctx = (ksp->monitorcontext[0]);
1279: return(0);
1280: }
1284: /*@
1285: KSPSetResidualHistory - Sets the array used to hold the residual history.
1286: If set, this array will contain the residual norms computed at each
1287: iteration of the solver.
1289: Not Collective
1291: Input Parameters:
1292: + ksp - iterative context obtained from KSPCreate()
1293: . a - array to hold history
1294: . na - size of a
1295: - reset - PETSC_TRUE indicates the history counter is reset to zero
1296: for each new linear solve
1298: Level: advanced
1300: Notes: The array is NOT freed by PETSc so the user needs to keep track of
1301: it and destroy once the KSP object is destroyed.
1303: If 'na' is PETSC_DECIDE or 'a' is PETSC_NULL, then a default array of
1304: length 1000 is allocated.
1306: .keywords: KSP, set, residual, history, norm
1308: .seealso: KSPGetResidualHistory()
1310: @*/
1311: PetscErrorCode KSPSetResidualHistory(KSP ksp,PetscReal a[],PetscInt na,PetscTruth reset)
1312: {
1317: if (na != PETSC_DECIDE && a) {
1318: ksp->res_hist = a;
1319: ksp->res_hist_max = na;
1320: } else {
1321: ksp->res_hist_max = 1000;
1322: PetscMalloc(ksp->res_hist_max*sizeof(PetscReal),&ksp->res_hist);
1323: }
1324: ksp->res_hist_len = 0;
1325: ksp->res_hist_reset = reset;
1328: return(0);
1329: }
1333: /*@C
1334: KSPGetResidualHistory - Gets the array used to hold the residual history
1335: and the number of residuals it contains.
1337: Not Collective
1339: Input Parameter:
1340: . ksp - iterative context obtained from KSPCreate()
1342: Output Parameters:
1343: + a - pointer to array to hold history (or PETSC_NULL)
1344: - na - number of used entries in a (or PETSC_NULL)
1346: Level: advanced
1348: Notes:
1349: Can only be called after a KSPSetResidualHistory() otherwise a and na are set to zero
1351: The Fortran version of this routine has a calling sequence
1352: $ call KSPGetResidualHistory(KSP ksp, integer na, integer ierr)
1354: .keywords: KSP, get, residual, history, norm
1356: .seealso: KSPGetResidualHistory()
1358: @*/
1359: PetscErrorCode KSPGetResidualHistory(KSP ksp,PetscReal *a[],PetscInt *na)
1360: {
1363: if (a) *a = ksp->res_hist;
1364: if (na) *na = ksp->res_hist_len;
1365: return(0);
1366: }
1370: /*@C
1371: KSPSetConvergenceTest - Sets the function to be used to determine
1372: convergence.
1374: Collective on KSP
1376: Input Parameters:
1377: + ksp - iterative context obtained from KSPCreate()
1378: . converge - pointer to int function
1379: - cctx - context for private data for the convergence routine (may be null)
1381: Calling sequence of converge:
1382: $ converge (KSP ksp, int it, PetscReal rnorm, KSPConvergedReason *reason,void *mctx)
1384: + ksp - iterative context obtained from KSPCreate()
1385: . it - iteration number
1386: . rnorm - (estimated) 2-norm of (preconditioned) residual
1387: . reason - the reason why it has converged or diverged
1388: - cctx - optional convergence context, as set by KSPSetConvergenceTest()
1391: Notes:
1392: Must be called after the KSP type has been set so put this after
1393: a call to KSPSetType(), or KSPSetFromOptions().
1395: The default convergence test, KSPDefaultConverged(), aborts if the
1396: residual grows to more than 10000 times the initial residual.
1398: The default is a combination of relative and absolute tolerances.
1399: The residual value that is tested may be an approximation; routines
1400: that need exact values should compute them.
1402: In the default PETSc convergence test, the precise values of reason
1403: are macros such as KSP_CONVERGED_RTOL, which are defined in petscksp.h.
1405: Level: advanced
1407: .keywords: KSP, set, convergence, test, context
1409: .seealso: KSPDefaultConverged(), KSPGetConvergenceContext()
1410: @*/
1411: PetscErrorCode KSPSetConvergenceTest(KSP ksp,PetscErrorCode (*converge)(KSP,PetscInt,PetscReal,KSPConvergedReason*,void*),void *cctx)
1412: {
1415: ksp->converged = converge;
1416: ksp->cnvP = (void*)cctx;
1417: return(0);
1418: }
1422: /*@C
1423: KSPGetConvergenceContext - Gets the convergence context set with
1424: KSPSetConvergenceTest().
1426: Not Collective
1428: Input Parameter:
1429: . ksp - iterative context obtained from KSPCreate()
1431: Output Parameter:
1432: . ctx - monitoring context
1434: Level: advanced
1436: .keywords: KSP, get, convergence, test, context
1438: .seealso: KSPDefaultConverged(), KSPSetConvergenceTest()
1439: @*/
1440: PetscErrorCode KSPGetConvergenceContext(KSP ksp,void **ctx)
1441: {
1444: *ctx = ksp->cnvP;
1445: return(0);
1446: }
1450: /*@
1451: KSPBuildSolution - Builds the approximate solution in a vector provided.
1452: This routine is NOT commonly needed (see KSPSolve()).
1454: Collective on KSP
1456: Input Parameter:
1457: . ctx - iterative context obtained from KSPCreate()
1459: Output Parameter:
1460: Provide exactly one of
1461: + v - location to stash solution.
1462: - V - the solution is returned in this location. This vector is created
1463: internally. This vector should NOT be destroyed by the user with
1464: VecDestroy().
1466: Notes:
1467: This routine can be used in one of two ways
1468: .vb
1469: KSPBuildSolution(ksp,PETSC_NULL,&V);
1470: or
1471: KSPBuildSolution(ksp,v,PETSC_NULL);
1472: .ve
1473: In the first case an internal vector is allocated to store the solution
1474: (the user cannot destroy this vector). In the second case the solution
1475: is generated in the vector that the user provides. Note that for certain
1476: methods, such as KSPCG, the second case requires a copy of the solution,
1477: while in the first case the call is essentially free since it simply
1478: returns the vector where the solution already is stored.
1480: Level: advanced
1482: .keywords: KSP, build, solution
1484: .seealso: KSPGetSolution(), KSPBuildResidual()
1485: @*/
1486: PetscErrorCode KSPBuildSolution(KSP ksp,Vec v,Vec *V)
1487: {
1492: if (!V && !v) SETERRQ(PETSC_ERR_ARG_WRONG,"Must provide either v or V");
1493: if (!V) V = &v;
1494: (*ksp->ops->buildsolution)(ksp,v,V);
1495: return(0);
1496: }
1500: /*@
1501: KSPBuildResidual - Builds the residual in a vector provided.
1503: Collective on KSP
1505: Input Parameter:
1506: . ksp - iterative context obtained from KSPCreate()
1508: Output Parameters:
1509: + v - optional location to stash residual. If v is not provided,
1510: then a location is generated.
1511: . t - work vector. If not provided then one is generated.
1512: - V - the residual
1514: Notes:
1515: Regardless of whether or not v is provided, the residual is
1516: returned in V.
1518: Level: advanced
1520: .keywords: KSP, build, residual
1522: .seealso: KSPBuildSolution()
1523: @*/
1524: PetscErrorCode KSPBuildResidual(KSP ksp,Vec t,Vec v,Vec *V)
1525: {
1527: PetscTruth flag = PETSC_FALSE;
1528: Vec w = v,tt = t;
1532: if (!w) {
1533: VecDuplicate(ksp->vec_rhs,&w);
1534: PetscLogObjectParent((PetscObject)ksp,w);
1535: }
1536: if (!tt) {
1537: VecDuplicate(ksp->vec_sol,&tt); flag = PETSC_TRUE;
1538: PetscLogObjectParent((PetscObject)ksp,tt);
1539: }
1540: (*ksp->ops->buildresidual)(ksp,tt,w,V);
1541: if (flag) {VecDestroy(tt);}
1542: return(0);
1543: }
1547: /*@
1548: KSPSetDiagonalScale - Tells KSP to symmetrically diagonally scale the system
1549: before solving. This actually CHANGES the matrix (and right hand side).
1551: Collective on KSP
1553: Input Parameter:
1554: + ksp - the KSP context
1555: - scale - PETSC_TRUE or PETSC_FALSE
1557: Options Database Key:
1558: + -ksp_diagonal_scale -
1559: - -ksp_diagonal_scale_fix - scale the matrix back AFTER the solve
1562: BE CAREFUL with this routine: it actually scales the matrix and right
1563: hand side that define the system. After the system is solved the matrix
1564: and right hand side remain scaled.
1566: This routine is only used if the matrix and preconditioner matrix are
1567: the same thing.
1569: This should NOT be used within the SNES solves if you are using a line
1570: search.
1571:
1572: If you use this with the PCType Eisenstat preconditioner than you can
1573: use the PCEisenstatNoDiagonalScaling() option, or -pc_eisenstat_no_diagonal_scaling
1574: to save some unneeded, redundant flops.
1576: Level: intermediate
1578: .keywords: KSP, set, options, prefix, database
1580: .seealso: KSPGetDiagonalScale(), KSPSetDiagonalScaleFix()
1581: @*/
1582: PetscErrorCode KSPSetDiagonalScale(KSP ksp,PetscTruth scale)
1583: {
1586: ksp->dscale = scale;
1587: return(0);
1588: }
1592: /*@C
1593: KSPGetDiagonalScale - Checks if KSP solver scales the matrix and
1594: right hand side
1596: Not Collective
1598: Input Parameter:
1599: . ksp - the KSP context
1601: Output Parameter:
1602: . scale - PETSC_TRUE or PETSC_FALSE
1604: Notes:
1605: BE CAREFUL with this routine: it actually scales the matrix and right
1606: hand side that define the system. After the system is solved the matrix
1607: and right hand side remain scaled.
1609: This routine is only used if the matrix and preconditioner matrix are
1610: the same thing.
1612: Level: intermediate
1614: .keywords: KSP, set, options, prefix, database
1616: .seealso: KSPSetDiagonalScale(), KSPSetDiagonalScaleFix()
1617: @*/
1618: PetscErrorCode KSPGetDiagonalScale(KSP ksp,PetscTruth *scale)
1619: {
1623: *scale = ksp->dscale;
1624: return(0);
1625: }
1629: /*@
1630: KSPSetDiagonalScaleFix - Tells KSP to diagonally scale the system
1631: back after solving.
1633: Collective on KSP
1635: Input Parameter:
1636: + ksp - the KSP context
1637: - fix - PETSC_TRUE to scale back after the system solve, PETSC_FALSE to not
1638: rescale (default)
1640: Notes:
1641: Must be called after KSPSetDiagonalScale()
1643: Using this will slow things down, because it rescales the matrix before and
1644: after each linear solve. This is intended mainly for testing to allow one
1645: to easily get back the original system to make sure the solution computed is
1646: accurate enough.
1648: This routine is only used if the matrix and preconditioner matrix are
1649: the same thing.
1651: Level: intermediate
1653: .keywords: KSP, set, options, prefix, database
1655: .seealso: KSPGetDiagonalScale(), KSPSetDiagonalScale(), KSPGetDiagonalScaleFix()
1656: @*/
1657: PetscErrorCode KSPSetDiagonalScaleFix(KSP ksp,PetscTruth fix)
1658: {
1661: ksp->dscalefix = fix;
1662: return(0);
1663: }
1667: /*@
1668: KSPGetDiagonalScaleFix - Determines if KSP diagonally scales the system
1669: back after solving.
1671: Collective on KSP
1673: Input Parameter:
1674: . ksp - the KSP context
1676: Output Parameter:
1677: . fix - PETSC_TRUE to scale back after the system solve, PETSC_FALSE to not
1678: rescale (default)
1680: Notes:
1681: Must be called after KSPSetDiagonalScale()
1683: If PETSC_TRUE will slow things down, because it rescales the matrix before and
1684: after each linear solve. This is intended mainly for testing to allow one
1685: to easily get back the original system to make sure the solution computed is
1686: accurate enough.
1688: This routine is only used if the matrix and preconditioner matrix are
1689: the same thing.
1691: Level: intermediate
1693: .keywords: KSP, set, options, prefix, database
1695: .seealso: KSPGetDiagonalScale(), KSPSetDiagonalScale(), KSPSetDiagonalScaleFix()
1696: @*/
1697: PetscErrorCode KSPGetDiagonalScaleFix(KSP ksp,PetscTruth *fix)
1698: {
1702: *fix = ksp->dscalefix;
1703: return(0);
1704: }