Actual source code: itfunc.c
1: #define PETSCKSP_DLL
3: /*
4: Interface KSP routines that the user calls.
5: */
7: #include src/ksp/ksp/kspimpl.h
11: /*@
12: KSPComputeExtremeSingularValues - Computes the extreme singular values
13: for the preconditioned operator. Called after or during KSPSolve().
15: Not Collective
17: Input Parameter:
18: . ksp - iterative context obtained from KSPCreate()
20: Output Parameters:
21: . emin, emax - extreme singular values
23: Notes:
24: One must call KSPSetComputeSingularValues() before calling KSPSetUp()
25: (or use the option -ksp_compute_eigenvalues) in order for this routine to work correctly.
27: Many users may just want to use the monitoring routine
28: KSPSingularValueMonitor() (which can be set with option -ksp_singmonitor)
29: to print the extreme singular values at each iteration of the linear solve.
31: Level: advanced
33: .keywords: KSP, compute, extreme, singular, values
35: .seealso: KSPSetComputeSingularValues(), KSPSingularValueMonitor(), KSPComputeEigenvalues()
36: @*/
37: PetscErrorCode PETSCKSP_DLLEXPORT KSPComputeExtremeSingularValues(KSP ksp,PetscReal *emax,PetscReal *emin)
38: {
45: if (!ksp->calc_sings) {
46: SETERRQ(4,"Singular values not requested before KSPSetUp()");
47: }
49: if (ksp->ops->computeextremesingularvalues) {
50: (*ksp->ops->computeextremesingularvalues)(ksp,emax,emin);
51: } else {
52: *emin = -1.0;
53: *emax = -1.0;
54: }
55: return(0);
56: }
60: /*@
61: KSPComputeEigenvalues - Computes the extreme eigenvalues for the
62: preconditioned operator. Called after or during KSPSolve().
64: Not Collective
66: Input Parameter:
67: + ksp - iterative context obtained from KSPCreate()
68: - n - size of arrays r and c. The number of eigenvalues computed (neig) will, in
69: general, be less than this.
71: Output Parameters:
72: + r - real part of computed eigenvalues
73: . c - complex part of computed eigenvalues
74: - neig - number of eigenvalues computed (will be less than or equal to n)
76: Options Database Keys:
77: + -ksp_compute_eigenvalues - Prints eigenvalues to stdout
78: - -ksp_plot_eigenvalues - Plots eigenvalues in an x-window display
80: Notes:
81: The number of eigenvalues estimated depends on the size of the Krylov space
82: generated during the KSPSolve() ; for example, with
83: CG it corresponds to the number of CG iterations, for GMRES it is the number
84: of GMRES iterations SINCE the last restart. Any extra space in r[] and c[]
85: will be ignored.
87: KSPComputeEigenvalues() does not usually provide accurate estimates; it is
88: intended only for assistance in understanding the convergence of iterative
89: methods, not for eigenanalysis.
91: One must call KSPSetComputeEigenvalues() before calling KSPSetUp()
92: in order for this routine to work correctly.
94: Many users may just want to use the monitoring routine
95: KSPSingularValueMonitor() (which can be set with option -ksp_singmonitor)
96: to print the singular values at each iteration of the linear solve.
98: Level: advanced
100: .keywords: KSP, compute, extreme, singular, values
102: .seealso: KSPSetComputeSingularValues(), KSPSingularValueMonitor(), KSPComputeExtremeSingularValues()
103: @*/
104: PetscErrorCode PETSCKSP_DLLEXPORT KSPComputeEigenvalues(KSP ksp,PetscInt n,PetscReal *r,PetscReal *c,PetscInt *neig)
105: {
113: if (!ksp->calc_sings) {
114: SETERRQ(4,"Eigenvalues not requested before KSPSetUp()");
115: }
117: if (ksp->ops->computeeigenvalues) {
118: (*ksp->ops->computeeigenvalues)(ksp,n,r,c,neig);
119: } else {
120: *neig = 0;
121: }
122: return(0);
123: }
127: /*@
128: KSPSetUpOnBlocks - Sets up the preconditioner for each block in
129: the block Jacobi, block Gauss-Seidel, and overlapping Schwarz
130: methods.
132: Collective on KSP
134: Input Parameter:
135: . ksp - the KSP context
137: Notes:
138: KSPSetUpOnBlocks() is a routine that the user can optinally call for
139: more precise profiling (via -log_summary) of the setup phase for these
140: block preconditioners. If the user does not call KSPSetUpOnBlocks(),
141: it will automatically be called from within KSPSolve().
142:
143: Calling KSPSetUpOnBlocks() is the same as calling PCSetUpOnBlocks()
144: on the PC context within the KSP context.
146: Level: advanced
148: .keywords: KSP, setup, blocks
150: .seealso: PCSetUpOnBlocks(), KSPSetUp(), PCSetUp()
151: @*/
152: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetUpOnBlocks(KSP ksp)
153: {
158: PCSetUpOnBlocks(ksp->pc);
159: return(0);
160: }
164: /*@
165: KSPSetUp - Sets up the internal data structures for the
166: later use of an iterative solver.
168: Collective on KSP
170: Input Parameter:
171: . ksp - iterative context obtained from KSPCreate()
173: Level: developer
175: .keywords: KSP, setup
177: .seealso: KSPCreate(), KSPSolve(), KSPDestroy()
178: @*/
179: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetUp(KSP ksp)
180: {
186: /* reset the convergence flag from the previous solves */
187: ksp->reason = KSP_CONVERGED_ITERATING;
189: if (!ksp->type_name){
190: KSPSetType(ksp,KSPGMRES);
191: }
193: if (ksp->setupcalled == 2) return(0);
195: PetscLogEventBegin(KSP_SetUp,ksp,ksp->vec_rhs,ksp->vec_sol,0);
197: if (!ksp->setupcalled) {
198: (*ksp->ops->setup)(ksp);
199: }
201: /* scale the matrix if requested */
202: if (ksp->dscale) {
203: Mat mat,pmat;
204: PCGetOperators(ksp->pc,&mat,&pmat,PETSC_NULL);
205: if (mat == pmat) {
206: PetscScalar *xx;
207: PetscInt i,n;
208: PetscTruth zeroflag = PETSC_FALSE;
210: if (!ksp->diagonal) { /* allocate vector to hold diagonal */
211: MatGetVecs(pmat,&ksp->diagonal,0);
212: }
213: MatGetDiagonal(mat,ksp->diagonal);
214: VecGetLocalSize(ksp->diagonal,&n);
215: VecGetArray(ksp->diagonal,&xx);
216: for (i=0; i<n; i++) {
217: if (xx[i] != 0.0) xx[i] = 1.0/sqrt(PetscAbsScalar(xx[i]));
218: else {
219: xx[i] = 1.0;
220: zeroflag = PETSC_TRUE;
221: }
222: }
223: VecRestoreArray(ksp->diagonal,&xx);
224: if (zeroflag) {
225: PetscInfo(ksp,"Zero detected in diagonal of matrix, using 1 at those locations\n");
226: }
227: MatDiagonalScale(mat,ksp->diagonal,ksp->diagonal);
228: ksp->dscalefix2 = PETSC_FALSE;
229: } else {
230: SETERRQ(PETSC_ERR_SUP,"No support for diagonal scaling of linear system if preconditioner matrix not actual matrix");
231: }
232: }
233: PetscLogEventEnd(KSP_SetUp,ksp,ksp->vec_rhs,ksp->vec_sol,0);
234: PCSetUp(ksp->pc);
235: if (ksp->nullsp) {
236: PetscTruth test;
237: PetscOptionsHasName(ksp->prefix,"-ksp_test_null_space",&test);
238: if (test) {
239: Mat mat;
240: PCGetOperators(ksp->pc,&mat,PETSC_NULL,PETSC_NULL);
241: MatNullSpaceTest(ksp->nullsp,mat);
242: }
243: }
244: ksp->setupcalled = 2;
245: return(0);
246: }
250: /*@
251: KSPSolve - Solves linear system.
253: Collective on KSP
255: Parameter:
256: + ksp - iterative context obtained from KSPCreate()
257: . b - the right hand side vector
258: - x - the solution
260: Options Database Keys:
261: + -ksp_compute_eigenvalues - compute preconditioned operators eigenvalues
262: . -ksp_plot_eigenvalues - plot the computed eigenvalues in an X-window
263: . -ksp_compute_eigenvalues_explicitly - compute the eigenvalues by forming the dense operator and useing LAPACK
264: . -ksp_plot_eigenvalues_explicitly - plot the explicitly computing eigenvalues
265: . -ksp_view_binary - save matrix and right hand side that define linear system to the default binary viewer (can be
266: read later with src/ksp/examples/tutorials/ex10.c for testing solvers)
267: . -ksp_converged_reason - print reason for converged or diverged
268: . -ksp_final_residual - print 2-norm of true linear system residual at the end of the solution process
269: - -ksp_view - print the ksp data structure at the end of the system solution
271: Notes:
273: The operator is specified with PCSetOperators().
275: Call KSPGetConvergedReason() to determine if the solver converged or failed and
276: why. The number of iterations can be obtained from KSPGetIterationNumber().
277:
278: If using a direct method (e.g., via the KSP solver
279: KSPPREONLY and a preconditioner such as PCLU/PCILU),
280: then its=1. See KSPSetTolerances() and KSPDefaultConverged()
281: for more details.
283: Understanding Convergence:
284: The routines KSPSetMonitor(), KSPComputeEigenvalues(), and
285: KSPComputeEigenvaluesExplicitly() provide information on additional
286: options to monitor convergence and print eigenvalue information.
288: Level: beginner
290: .keywords: KSP, solve, linear system
292: .seealso: KSPCreate(), KSPSetUp(), KSPDestroy(), KSPSetTolerances(), KSPDefaultConverged(),
293: KSPSolveTranspose(), KSPGetIterationNumber()
294: @*/
295: PetscErrorCode PETSCKSP_DLLEXPORT KSPSolve(KSP ksp,Vec b,Vec x)
296: {
298: PetscMPIInt rank;
299: PetscTruth flag1,flag2,viewed=PETSC_FALSE,flg;
300: char view[10];
301: char filename[PETSC_MAX_PATH_LEN];
302: PetscViewer viewer;
309:
310: ksp->vec_rhs = b;
311: ksp->vec_sol = x;
312: PetscOptionsHasName(ksp->prefix,"-ksp_view_binary",&flg);
313: if (flg) {
314: Mat mat;
315: PCGetOperators(ksp->pc,&mat,PETSC_NULL,PETSC_NULL);
316: MatView(mat,PETSC_VIEWER_BINARY_(ksp->comm));
317: VecView(ksp->vec_rhs,PETSC_VIEWER_BINARY_(ksp->comm));
318: }
320: PetscLogEventBegin(KSP_Solve,ksp,ksp->vec_rhs,ksp->vec_sol,0);
322: /* reset the residual history list if requested */
323: if (ksp->res_hist_reset) ksp->res_hist_len = 0;
325: PetscOptionsGetString(ksp->prefix,"-ksp_view",view,10,&flg);
326: if (flg) {
327: PetscStrcmp(view,"before",&viewed);
328: if (viewed){
329: KSPView(ksp,PETSC_VIEWER_STDOUT_(ksp->comm));
330: }
331: }
333: /* KSPSetUp() scales the matrix if needed */
334: KSPSetUp(ksp);
335: KSPSetUpOnBlocks(ksp);
337: ksp->transpose_solve = PETSC_FALSE;
339: /* diagonal scale RHS if called for */
340: if (ksp->dscale) {
341: VecPointwiseMult(ksp->vec_rhs,ksp->vec_rhs,ksp->diagonal);
342: /* second time in, but matrix was scaled back to original */
343: if (ksp->dscalefix && ksp->dscalefix2) {
344: Mat mat;
346: PCGetOperators(ksp->pc,&mat,PETSC_NULL,PETSC_NULL);
347: MatDiagonalScale(mat,ksp->diagonal,ksp->diagonal);
348: }
350: /* scale initial guess */
351: if (!ksp->guess_zero) {
352: if (!ksp->truediagonal) {
353: VecDuplicate(ksp->diagonal,&ksp->truediagonal);
354: VecCopy(ksp->diagonal,ksp->truediagonal);
355: VecReciprocal(ksp->truediagonal);
356: }
357: VecPointwiseMult(ksp->vec_sol,ksp->vec_sol,ksp->truediagonal);
358: }
359: }
360: PCPreSolve(ksp->pc,ksp);
362: if (ksp->guess_zero) { VecSet(ksp->vec_sol,0.0);}
363: if (ksp->guess_knoll) {
364: PCApply(ksp->pc,ksp->vec_rhs,ksp->vec_sol);
365: KSP_RemoveNullSpace(ksp,ksp->vec_sol);
366: ksp->guess_zero = PETSC_FALSE;
367: }
368: (*ksp->ops->solve)(ksp);
369: if (!ksp->reason) {
370: SETERRQ(PETSC_ERR_PLIB,"Internal error, solver returned without setting converged reason");
371: }
372: if (ksp->printreason) {
373: if (ksp->reason > 0) {
374: PetscPrintf(ksp->comm,"Linear solve converged due to %s\n",KSPConvergedReasons[ksp->reason]);
375: } else {
376: PetscPrintf(ksp->comm,"Linear solve did not converge due to %s\n",KSPConvergedReasons[ksp->reason]);
377: }
378: }
380: /* diagonal scale solution if called for */
381: PCPostSolve(ksp->pc,ksp);
382: if (ksp->dscale) {
383: VecPointwiseMult(ksp->vec_sol,ksp->vec_sol,ksp->diagonal);
384: /* unscale right hand side and matrix */
385: if (ksp->dscalefix) {
386: Mat mat;
388: VecReciprocal(ksp->diagonal);
389: VecPointwiseMult(ksp->vec_rhs,ksp->vec_rhs,ksp->diagonal);
390: PCGetOperators(ksp->pc,&mat,PETSC_NULL,PETSC_NULL);
391: MatDiagonalScale(mat,ksp->diagonal,ksp->diagonal);
392: VecReciprocal(ksp->diagonal);
393: ksp->dscalefix2 = PETSC_TRUE;
394: }
395: }
396: PetscLogEventEnd(KSP_Solve,ksp,ksp->vec_rhs,ksp->vec_sol,0);
398: MPI_Comm_rank(ksp->comm,&rank);
400: PetscOptionsHasName(ksp->prefix,"-ksp_compute_eigenvalues",&flag1);
401: PetscOptionsHasName(ksp->prefix,"-ksp_plot_eigenvalues",&flag2);
402: if (flag1 || flag2) {
403: PetscInt nits,n,i,neig;
404: PetscReal *r,*c;
405:
406: KSPGetIterationNumber(ksp,&nits);
407: n = nits+2;
409: if (!n) {
410: PetscPrintf(ksp->comm,"Zero iterations in solver, cannot approximate any eigenvalues\n");
411: } else {
412: PetscMalloc(2*n*sizeof(PetscReal),&r);
413: c = r + n;
414: KSPComputeEigenvalues(ksp,n,r,c,&neig);
415: if (flag1) {
416: PetscPrintf(ksp->comm,"Iteratively computed eigenvalues\n");
417: for (i=0; i<neig; i++) {
418: if (c[i] >= 0.0) {PetscPrintf(ksp->comm,"%G + %Gi\n",r[i],c[i]);}
419: else {PetscPrintf(ksp->comm,"%G - %Gi\n",r[i],-c[i]);}
420: }
421: }
422: if (flag2 && !rank) {
423: PetscDraw draw;
424: PetscDrawSP drawsp;
426: PetscViewerDrawOpen(PETSC_COMM_SELF,0,"Iteratively Computed Eigenvalues",PETSC_DECIDE,PETSC_DECIDE,300,300,&viewer);
427: PetscViewerDrawGetDraw(viewer,0,&draw);
428: PetscDrawSPCreate(draw,1,&drawsp);
429: for (i=0; i<neig; i++) {
430: PetscDrawSPAddPoint(drawsp,r+i,c+i);
431: }
432: PetscDrawSPDraw(drawsp);
433: PetscDrawSPDestroy(drawsp);
434: PetscViewerDestroy(viewer);
435: }
436: PetscFree(r);
437: }
438: }
440: PetscOptionsHasName(ksp->prefix,"-ksp_compute_eigenvalues_explicitly",&flag1);
441: PetscOptionsHasName(ksp->prefix,"-ksp_plot_eigenvalues_explicitly",&flag2);
442: if (flag1 || flag2) {
443: PetscInt n,i;
444: PetscReal *r,*c;
445: VecGetSize(ksp->vec_sol,&n);
446: PetscMalloc(2*n*sizeof(PetscReal),&r);
447: c = r + n;
448: KSPComputeEigenvaluesExplicitly(ksp,n,r,c);
449: if (flag1) {
450: PetscPrintf(ksp->comm,"Explicitly computed eigenvalues\n");
451: for (i=0; i<n; i++) {
452: if (c[i] >= 0.0) {PetscPrintf(ksp->comm,"%G + %Gi\n",r[i],c[i]);}
453: else {PetscPrintf(ksp->comm,"%G - %Gi\n",r[i],-c[i]);}
454: }
455: }
456: if (flag2 && !rank) {
457: PetscDraw draw;
458: PetscDrawSP drawsp;
460: PetscViewerDrawOpen(PETSC_COMM_SELF,0,"Explicitly Computed Eigenvalues",0,320,300,300,&viewer);
461: PetscViewerDrawGetDraw(viewer,0,&draw);
462: PetscDrawSPCreate(draw,1,&drawsp);
463: for (i=0; i<n; i++) {
464: PetscDrawSPAddPoint(drawsp,r+i,c+i);
465: }
466: PetscDrawSPDraw(drawsp);
467: PetscDrawSPDestroy(drawsp);
468: PetscViewerDestroy(viewer);
469: }
470: PetscFree(r);
471: }
473: PetscOptionsHasName(ksp->prefix,"-ksp_view_operator",&flag2);
474: if (flag2) {
475: Mat A,B;
476: PCGetOperators(ksp->pc,&A,PETSC_NULL,PETSC_NULL);
477: MatComputeExplicitOperator(A,&B);
478: PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(ksp->comm),PETSC_VIEWER_ASCII_MATLAB);
479: MatView(B,PETSC_VIEWER_STDOUT_(ksp->comm));
480: PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(ksp->comm));
481: MatDestroy(B);
482: }
483: PetscOptionsHasName(ksp->prefix,"-ksp_view_operator_binary",&flag2);
484: if (flag2) {
485: Mat A,B;
486: PCGetOperators(ksp->pc,&A,PETSC_NULL,PETSC_NULL);
487: MatComputeExplicitOperator(A,&B);
488: MatView(B,PETSC_VIEWER_BINARY_(ksp->comm));
489: MatDestroy(B);
490: }
491: PetscOptionsHasName(ksp->prefix,"-ksp_view_preconditioned_operator_binary",&flag2);
492: if (flag2) {
493: Mat B;
494: KSPComputeExplicitOperator(ksp,&B);
495: MatView(B,PETSC_VIEWER_BINARY_(ksp->comm));
496: MatDestroy(B);
497: }
498: if (!viewed) {
499: PetscOptionsGetString(ksp->prefix,"-ksp_view",filename,PETSC_MAX_PATH_LEN,&flg);
500: if (flg && !PetscPreLoadingOn) {
501: PetscViewerASCIIOpen(ksp->comm,filename,&viewer);
502: KSPView(ksp,viewer);
503: PetscViewerDestroy(viewer);
504: }
505: }
506: PetscOptionsHasName(ksp->prefix,"-ksp_final_residual",&flg);
507: if (flg) {
508: Mat A;
509: Vec t;
510: PetscReal norm;
511: if (ksp->dscale && !ksp->dscalefix) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot compute final scale with -ksp_diagonal_scale except also with -ksp_diagonal_scale_fix");
512: PCGetOperators(ksp->pc,&A,0,0);
513: VecDuplicate(ksp->vec_sol,&t);
514: KSP_MatMult(ksp,A,ksp->vec_sol,t);
515: VecWAXPY(t,-1.0,t,ksp->vec_rhs);
516: VecNorm(t,NORM_2,&norm);
517: VecDestroy(t);
518: PetscPrintf(ksp->comm,"KSP final norm of residual %G\n",norm);
519: }
520: return(0);
521: }
525: /*@
526: KSPSolveTranspose - Solves the transpose of a linear system. Usually
527: accessed through KSPSolveTranspose().
529: Collective on KSP
531: Input Parameter:
532: + ksp - iterative context obtained from KSPCreate()
533: . b - right hand side vector
534: - x - solution vector
536: Note:
537: Currently only supported by KSPType of KSPPREONLY. This routine is usally
538: only used internally by the BiCG solver on the subblocks in BJacobi and ASM.
540: Level: developer
542: .keywords: KSP, solve, linear system
544: .seealso: KSPCreate(), KSPSetUp(), KSPDestroy(), KSPSetTolerances(), KSPDefaultConverged(),
545: KSPSolve()
546: @*/
547: PetscErrorCode PETSCKSP_DLLEXPORT KSPSolveTranspose(KSP ksp,Vec b,Vec x)
548: {
550: PetscScalar zero = 0.0;
557: ksp->vec_rhs = b;
558: ksp->vec_sol = x;
559: KSPSetUp(ksp);
560: if (ksp->guess_zero) { VecSet(ksp->vec_sol,zero);}
561: ksp->transpose_solve = PETSC_TRUE;
562: (*ksp->ops->solve)(ksp);
563: return(0);
564: }
568: /*@
569: KSPDestroy - Destroys KSP context.
571: Collective on KSP
573: Input Parameter:
574: . ksp - iterative context obtained from KSPCreate()
576: Level: beginner
578: .keywords: KSP, destroy
580: .seealso: KSPCreate(), KSPSetUp(), KSPSolve()
581: @*/
582: PetscErrorCode PETSCKSP_DLLEXPORT KSPDestroy(KSP ksp)
583: {
588: if (--ksp->refct > 0) return(0);
590: /* if memory was published with AMS then destroy it */
591: PetscObjectDepublish(ksp);
593: if (ksp->ops->destroy) {
594: (*ksp->ops->destroy)(ksp);
595: }
596: KSPClearMonitor(ksp);
597: PCDestroy(ksp->pc);
598: if (ksp->diagonal) {VecDestroy(ksp->diagonal);}
599: if (ksp->truediagonal) {VecDestroy(ksp->truediagonal);}
600: if (ksp->nullsp) {MatNullSpaceDestroy(ksp->nullsp);}
601: PetscHeaderDestroy(ksp);
602: return(0);
603: }
607: /*@
608: KSPSetPreconditionerSide - Sets the preconditioning side.
610: Collective on KSP
612: Input Parameter:
613: . ksp - iterative context obtained from KSPCreate()
615: Output Parameter:
616: . side - the preconditioning side, where side is one of
617: .vb
618: PC_LEFT - left preconditioning (default)
619: PC_RIGHT - right preconditioning
620: PC_SYMMETRIC - symmetric preconditioning
621: .ve
623: Options Database Keys:
624: + -ksp_left_pc - Sets left preconditioning
625: . -ksp_right_pc - Sets right preconditioning
626: - -ksp_symmetric_pc - Sets symmetric preconditioning
628: Notes:
629: Left preconditioning is used by default. Symmetric preconditioning is
630: currently available only for the KSPQCG method. Note, however, that
631: symmetric preconditioning can be emulated by using either right or left
632: preconditioning and a pre or post processing step.
634: Level: intermediate
636: .keywords: KSP, set, right, left, symmetric, side, preconditioner, flag
638: .seealso: KSPGetPreconditionerSide()
639: @*/
640: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetPreconditionerSide(KSP ksp,PCSide side)
641: {
644: ksp->pc_side = side;
645: return(0);
646: }
650: /*@
651: KSPGetPreconditionerSide - Gets the preconditioning side.
653: Not Collective
655: Input Parameter:
656: . ksp - iterative context obtained from KSPCreate()
658: Output Parameter:
659: . side - the preconditioning side, where side is one of
660: .vb
661: PC_LEFT - left preconditioning (default)
662: PC_RIGHT - right preconditioning
663: PC_SYMMETRIC - symmetric preconditioning
664: .ve
666: Level: intermediate
668: .keywords: KSP, get, right, left, symmetric, side, preconditioner, flag
670: .seealso: KSPSetPreconditionerSide()
671: @*/
672: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetPreconditionerSide(KSP ksp,PCSide *side)
673: {
677: *side = ksp->pc_side;
678: return(0);
679: }
683: /*@
684: KSPGetTolerances - Gets the relative, absolute, divergence, and maximum
685: iteration tolerances used by the default KSP convergence tests.
687: Not Collective
689: Input Parameter:
690: . ksp - the Krylov subspace context
691:
692: Output Parameters:
693: + rtol - the relative convergence tolerance
694: . abstol - the absolute convergence tolerance
695: . dtol - the divergence tolerance
696: - maxits - maximum number of iterations
698: Notes:
699: The user can specify PETSC_NULL for any parameter that is not needed.
701: Level: intermediate
703: .keywords: KSP, get, tolerance, absolute, relative, divergence, convergence,
704: maximum, iterations
706: .seealso: KSPSetTolerances()
707: @*/
708: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetTolerances(KSP ksp,PetscReal *rtol,PetscReal *abstol,PetscReal *dtol,PetscInt *maxits)
709: {
712: if (abstol) *abstol = ksp->abstol;
713: if (rtol) *rtol = ksp->rtol;
714: if (dtol) *dtol = ksp->divtol;
715: if (maxits) *maxits = ksp->max_it;
716: return(0);
717: }
721: /*@
722: KSPSetTolerances - Sets the relative, absolute, divergence, and maximum
723: iteration tolerances used by the default KSP convergence testers.
725: Collective on KSP
727: Input Parameters:
728: + ksp - the Krylov subspace context
729: . rtol - the relative convergence tolerance
730: (relative decrease in the residual norm)
731: . abstol - the absolute convergence tolerance
732: (absolute size of the residual norm)
733: . dtol - the divergence tolerance
734: (amount residual can increase before KSPDefaultConverged()
735: concludes that the method is diverging)
736: - maxits - maximum number of iterations to use
738: Options Database Keys:
739: + -ksp_atol <abstol> - Sets abstol
740: . -ksp_rtol <rtol> - Sets rtol
741: . -ksp_divtol <dtol> - Sets dtol
742: - -ksp_max_it <maxits> - Sets maxits
744: Notes:
745: Use PETSC_DEFAULT to retain the default value of any of the tolerances.
747: See KSPDefaultConverged() for details on the use of these parameters
748: in the default convergence test. See also KSPSetConvergenceTest()
749: for setting user-defined stopping criteria.
751: Level: intermediate
753: .keywords: KSP, set, tolerance, absolute, relative, divergence,
754: convergence, maximum, iterations
756: .seealso: KSPGetTolerances(), KSPDefaultConverged(), KSPSetConvergenceTest()
757: @*/
758: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetTolerances(KSP ksp,PetscReal rtol,PetscReal abstol,PetscReal dtol,PetscInt maxits)
759: {
762: if (abstol != PETSC_DEFAULT) ksp->abstol = abstol;
763: if (rtol != PETSC_DEFAULT) ksp->rtol = rtol;
764: if (dtol != PETSC_DEFAULT) ksp->divtol = dtol;
765: if (maxits != PETSC_DEFAULT) ksp->max_it = maxits;
766: return(0);
767: }
771: /*@
772: KSPSetInitialGuessNonzero - Tells the iterative solver that the
773: initial guess is nonzero; otherwise KSP assumes the initial guess
774: is to be zero (and thus zeros it out before solving).
776: Collective on KSP
778: Input Parameters:
779: + ksp - iterative context obtained from KSPCreate()
780: - flg - PETSC_TRUE indicates the guess is non-zero, PETSC_FALSE indicates the guess is zero
782: Level: beginner
784: Notes:
785: If this is not called the X vector is zeroed in the call to KSPSolve().
787: .keywords: KSP, set, initial guess, nonzero
789: .seealso: KSPGetInitialGuessNonzero(), KSPSetInitialGuessKnoll(), KSPGetInitialGuessKnoll()
790: @*/
791: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetInitialGuessNonzero(KSP ksp,PetscTruth flg)
792: {
794: ksp->guess_zero = (PetscTruth)!(int)flg;
795: return(0);
796: }
800: /*@
801: KSPGetInitialGuessNonzero - Determines whether the KSP solver is using
802: a zero initial guess.
804: Not Collective
806: Input Parameter:
807: . ksp - iterative context obtained from KSPCreate()
809: Output Parameter:
810: . flag - PETSC_TRUE if guess is nonzero, else PETSC_FALSE
812: Level: intermediate
814: .keywords: KSP, set, initial guess, nonzero
816: .seealso: KSPSetInitialGuessNonzero(), KSPSetInitialGuessKnoll(), KSPGetInitialGuessKnoll()
817: @*/
818: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetInitialGuessNonzero(KSP ksp,PetscTruth *flag)
819: {
821: if (ksp->guess_zero) *flag = PETSC_FALSE;
822: else *flag = PETSC_TRUE;
823: return(0);
824: }
828: /*@
829: KSPSetInitialGuessKnoll - Tells the iterative solver to use PCApply(pc,b,..) to compute the initial guess (The Knoll trick)
831: Collective on KSP
833: Input Parameters:
834: + ksp - iterative context obtained from KSPCreate()
835: - flg - PETSC_TRUE or PETSC_FALSE
837: Level: advanced
840: .keywords: KSP, set, initial guess, nonzero
842: .seealso: KSPGetInitialGuessKnoll(), KSPSetInitialGuessNonzero(), KSPGetInitialGuessNonzero()
843: @*/
844: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetInitialGuessKnoll(KSP ksp,PetscTruth flg)
845: {
847: ksp->guess_knoll = flg;
848: return(0);
849: }
853: /*@
854: KSPGetInitialGuessKnoll - Determines whether the KSP solver is using the Knoll trick (using PCApply(pc,b,...) to compute
855: the initial guess
857: Not Collective
859: Input Parameter:
860: . ksp - iterative context obtained from KSPCreate()
862: Output Parameter:
863: . flag - PETSC_TRUE if using Knoll trick, else PETSC_FALSE
865: Level: advanced
867: .keywords: KSP, set, initial guess, nonzero
869: .seealso: KSPSetInitialGuessKnoll(), KSPSetInitialGuessNonzero(), KSPGetInitialGuessNonzero()
870: @*/
871: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetInitialGuessKnoll(KSP ksp,PetscTruth *flag)
872: {
874: *flag = ksp->guess_knoll;
875: return(0);
876: }
880: /*@
881: KSPGetComputeSingularValues - Gets the flag indicating whether the extreme singular
882: values will be calculated via a Lanczos or Arnoldi process as the linear
883: system is solved.
885: Collective on KSP
887: Input Parameter:
888: . ksp - iterative context obtained from KSPCreate()
890: Output Parameter:
891: . flg - PETSC_TRUE or PETSC_FALSE
893: Options Database Key:
894: . -ksp_singmonitor - Activates KSPSetComputeSingularValues()
896: Notes:
897: Currently this option is not valid for all iterative methods.
899: Many users may just want to use the monitoring routine
900: KSPSingularValueMonitor() (which can be set with option -ksp_singmonitor)
901: to print the singular values at each iteration of the linear solve.
903: Level: advanced
905: .keywords: KSP, set, compute, singular values
907: .seealso: KSPComputeExtremeSingularValues(), KSPSingularValueMonitor()
908: @*/
909: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetComputeSingularValues(KSP ksp,PetscTruth *flg)
910: {
914: *flg = ksp->calc_sings;
915: return(0);
916: }
920: /*@
921: KSPSetComputeSingularValues - Sets a flag so that the extreme singular
922: values will be calculated via a Lanczos or Arnoldi process as the linear
923: system is solved.
925: Collective on KSP
927: Input Parameters:
928: + ksp - iterative context obtained from KSPCreate()
929: - flg - PETSC_TRUE or PETSC_FALSE
931: Options Database Key:
932: . -ksp_singmonitor - Activates KSPSetComputeSingularValues()
934: Notes:
935: Currently this option is not valid for all iterative methods.
937: Many users may just want to use the monitoring routine
938: KSPSingularValueMonitor() (which can be set with option -ksp_singmonitor)
939: to print the singular values at each iteration of the linear solve.
941: Level: advanced
943: .keywords: KSP, set, compute, singular values
945: .seealso: KSPComputeExtremeSingularValues(), KSPSingularValueMonitor()
946: @*/
947: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetComputeSingularValues(KSP ksp,PetscTruth flg)
948: {
951: ksp->calc_sings = flg;
952: return(0);
953: }
957: /*@
958: KSPGetComputeEigenvalues - Gets the flag indicating that the extreme eigenvalues
959: values will be calculated via a Lanczos or Arnoldi process as the linear
960: system is solved.
962: Collective on KSP
964: Input Parameter:
965: . ksp - iterative context obtained from KSPCreate()
967: Output Parameter:
968: . flg - PETSC_TRUE or PETSC_FALSE
970: Notes:
971: Currently this option is not valid for all iterative methods.
973: Level: advanced
975: .keywords: KSP, set, compute, eigenvalues
977: .seealso: KSPComputeEigenvalues(), KSPComputeEigenvaluesExplicitly()
978: @*/
979: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetComputeEigenvalues(KSP ksp,PetscTruth *flg)
980: {
984: *flg = ksp->calc_sings;
985: return(0);
986: }
990: /*@
991: KSPSetComputeEigenvalues - Sets a flag so that the extreme eigenvalues
992: values will be calculated via a Lanczos or Arnoldi process as the linear
993: system is solved.
995: Collective on KSP
997: Input Parameters:
998: + ksp - iterative context obtained from KSPCreate()
999: - flg - PETSC_TRUE or PETSC_FALSE
1001: Notes:
1002: Currently this option is not valid for all iterative methods.
1004: Level: advanced
1006: .keywords: KSP, set, compute, eigenvalues
1008: .seealso: KSPComputeEigenvalues(), KSPComputeEigenvaluesExplicitly()
1009: @*/
1010: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetComputeEigenvalues(KSP ksp,PetscTruth flg)
1011: {
1014: ksp->calc_sings = flg;
1015: return(0);
1016: }
1020: /*@
1021: KSPGetRhs - Gets the right-hand-side vector for the linear system to
1022: be solved.
1024: Not Collective
1026: Input Parameter:
1027: . ksp - iterative context obtained from KSPCreate()
1029: Output Parameter:
1030: . r - right-hand-side vector
1032: Level: developer
1034: .keywords: KSP, get, right-hand-side, rhs
1036: .seealso: KSPGetSolution(), KSPSolve()
1037: @*/
1038: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetRhs(KSP ksp,Vec *r)
1039: {
1042: *r = ksp->vec_rhs;
1043: return(0);
1044: }
1048: /*@
1049: KSPGetSolution - Gets the location of the solution for the
1050: linear system to be solved. Note that this may not be where the solution
1051: is stored during the iterative process; see KSPBuildSolution().
1053: Not Collective
1055: Input Parameters:
1056: . ksp - iterative context obtained from KSPCreate()
1058: Output Parameters:
1059: . v - solution vector
1061: Level: developer
1063: .keywords: KSP, get, solution
1065: .seealso: KSPGetRhs(), KSPBuildSolution(), KSPSolve()
1066: @*/
1067: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetSolution(KSP ksp,Vec *v)
1068: {
1072: *v = ksp->vec_sol;
1073: return(0);
1074: }
1078: /*@
1079: KSPSetPC - Sets the preconditioner to be used to calculate the
1080: application of the preconditioner on a vector.
1082: Collective on KSP
1084: Input Parameters:
1085: + ksp - iterative context obtained from KSPCreate()
1086: - pc - the preconditioner object
1088: Notes:
1089: Use KSPGetPC() to retrieve the preconditioner context (for example,
1090: to free it at the end of the computations).
1092: Level: developer
1094: .keywords: KSP, set, precondition, Binv
1096: .seealso: KSPGetPC()
1097: @*/
1098: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetPC(KSP ksp,PC pc)
1099: {
1106: if (ksp->pc) {PCDestroy(ksp->pc);}
1107: ksp->pc = pc;
1108: PetscObjectReference((PetscObject)ksp->pc);
1109: return(0);
1110: }
1114: /*@
1115: KSPGetPC - Returns a pointer to the preconditioner context
1116: set with KSPSetPC().
1118: Not Collective
1120: Input Parameters:
1121: . ksp - iterative context obtained from KSPCreate()
1123: Output Parameter:
1124: . pc - preconditioner context
1126: Level: developer
1128: .keywords: KSP, get, preconditioner, Binv
1130: .seealso: KSPSetPC()
1131: @*/
1132: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetPC(KSP ksp,PC *pc)
1133: {
1137: *pc = ksp->pc;
1138: return(0);
1139: }
1143: /*@C
1144: KSPSetMonitor - Sets an ADDITIONAL function to be called at every iteration to monitor
1145: the residual/error etc.
1146:
1147: Collective on KSP
1149: Input Parameters:
1150: + ksp - iterative context obtained from KSPCreate()
1151: . monitor - pointer to function (if this is PETSC_NULL, it turns off monitoring
1152: . mctx - [optional] context for private data for the
1153: monitor routine (use PETSC_NULL if no context is desired)
1154: - monitordestroy - [optional] routine that frees monitor context
1155: (may be PETSC_NULL)
1157: Calling Sequence of monitor:
1158: $ monitor (KSP ksp, int it, PetscReal rnorm, void *mctx)
1160: + ksp - iterative context obtained from KSPCreate()
1161: . it - iteration number
1162: . rnorm - (estimated) 2-norm of (preconditioned) residual
1163: - mctx - optional monitoring context, as set by KSPSetMonitor()
1165: Options Database Keys:
1166: + -ksp_monitor - sets KSPDefaultMonitor()
1167: . -ksp_truemonitor - sets KSPTrueMonitor()
1168: . -ksp_xmonitor - sets line graph monitor,
1169: uses KSPLGMonitorCreate()
1170: . -ksp_xtruemonitor - sets line graph monitor,
1171: uses KSPLGMonitorCreate()
1172: . -ksp_singmonitor - sets KSPSingularValueMonitor()
1173: - -ksp_cancelmonitors - cancels all monitors that have
1174: been hardwired into a code by
1175: calls to KSPSetMonitor(), but
1176: does not cancel those set via
1177: the options database.
1179: Notes:
1180: The default is to do nothing. To print the residual, or preconditioned
1181: residual if KSPSetNormType(ksp,KSP_PRECONDITIONED_NORM) was called, use
1182: KSPDefaultMonitor() as the monitoring routine, with a null monitoring
1183: context.
1185: Several different monitoring routines may be set by calling
1186: KSPSetMonitor() multiple times; all will be called in the
1187: order in which they were set.
1189: Level: beginner
1191: .keywords: KSP, set, monitor
1193: .seealso: KSPDefaultMonitor(), KSPLGMonitorCreate(), KSPClearMonitor()
1194: @*/
1195: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetMonitor(KSP ksp,PetscErrorCode (*monitor)(KSP,PetscInt,PetscReal,void*),void *mctx,PetscErrorCode (*monitordestroy)(void*))
1196: {
1199: if (ksp->numbermonitors >= MAXKSPMONITORS) {
1200: SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Too many KSP monitors set");
1201: }
1202: ksp->monitor[ksp->numbermonitors] = monitor;
1203: ksp->monitordestroy[ksp->numbermonitors] = monitordestroy;
1204: ksp->monitorcontext[ksp->numbermonitors++] = (void*)mctx;
1205: return(0);
1206: }
1210: /*@
1211: KSPClearMonitor - Clears all monitors for a KSP object.
1213: Collective on KSP
1215: Input Parameters:
1216: . ksp - iterative context obtained from KSPCreate()
1218: Options Database Key:
1219: . -ksp_cancelmonitors - Cancels all monitors that have
1220: been hardwired into a code by calls to KSPSetMonitor(),
1221: but does not cancel those set via the options database.
1223: Level: intermediate
1225: .keywords: KSP, set, monitor
1227: .seealso: KSPDefaultMonitor(), KSPLGMonitorCreate(), KSPSetMonitor()
1228: @*/
1229: PetscErrorCode PETSCKSP_DLLEXPORT KSPClearMonitor(KSP ksp)
1230: {
1232: PetscInt i;
1236: for (i=0; i<ksp->numbermonitors; i++) {
1237: if (ksp->monitordestroy[i]) {
1238: (*ksp->monitordestroy[i])(ksp->monitorcontext[i]);
1239: }
1240: }
1241: ksp->numbermonitors = 0;
1242: return(0);
1243: }
1247: /*@C
1248: KSPGetMonitorContext - Gets the monitoring context, as set by
1249: KSPSetMonitor() for the FIRST monitor only.
1251: Not Collective
1253: Input Parameter:
1254: . ksp - iterative context obtained from KSPCreate()
1256: Output Parameter:
1257: . ctx - monitoring context
1259: Level: intermediate
1261: .keywords: KSP, get, monitor, context
1263: .seealso: KSPDefaultMonitor(), KSPLGMonitorCreate()
1264: @*/
1265: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetMonitorContext(KSP ksp,void **ctx)
1266: {
1269: *ctx = (ksp->monitorcontext[0]);
1270: return(0);
1271: }
1275: /*@
1276: KSPSetResidualHistory - Sets the array used to hold the residual history.
1277: If set, this array will contain the residual norms computed at each
1278: iteration of the solver.
1280: Not Collective
1282: Input Parameters:
1283: + ksp - iterative context obtained from KSPCreate()
1284: . a - array to hold history
1285: . na - size of a
1286: - reset - PETSC_TRUE indicates the history counter is reset to zero
1287: for each new linear solve
1289: Level: advanced
1291: Notes: The array is NOT freed by PETSc so the user needs to keep track of
1292: it and destroy once the KSP object is destroyed.
1294: If 'na' is PETSC_DECIDE or 'a' is PETSC_NULL, then a default array of
1295: length 1000 is allocated.
1297: .keywords: KSP, set, residual, history, norm
1299: .seealso: KSPGetResidualHistory()
1301: @*/
1302: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetResidualHistory(KSP ksp,PetscReal a[],PetscInt na,PetscTruth reset)
1303: {
1308: if (na != PETSC_DECIDE && a) {
1309: ksp->res_hist = a;
1310: ksp->res_hist_max = na;
1311: } else {
1312: ksp->res_hist_max = 1000;
1313: PetscMalloc(ksp->res_hist_max*sizeof(PetscReal),&ksp->res_hist);
1314: }
1315: ksp->res_hist_len = 0;
1316: ksp->res_hist_reset = reset;
1319: return(0);
1320: }
1324: /*@C
1325: KSPGetResidualHistory - Gets the array used to hold the residual history
1326: and the number of residuals it contains.
1328: Not Collective
1330: Input Parameter:
1331: . ksp - iterative context obtained from KSPCreate()
1333: Output Parameters:
1334: + a - pointer to array to hold history (or PETSC_NULL)
1335: - na - number of used entries in a (or PETSC_NULL)
1337: Level: advanced
1339: Notes:
1340: Can only be called after a KSPSetResidualHistory() otherwise a and na are set to zero
1342: The Fortran version of this routine has a calling sequence
1343: $ call KSPGetResidualHistory(KSP ksp, integer na, integer ierr)
1345: .keywords: KSP, get, residual, history, norm
1347: .seealso: KSPGetResidualHistory()
1349: @*/
1350: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetResidualHistory(KSP ksp,PetscReal *a[],PetscInt *na)
1351: {
1354: if (a) *a = ksp->res_hist;
1355: if (na) *na = ksp->res_hist_len;
1356: return(0);
1357: }
1361: /*@C
1362: KSPSetConvergenceTest - Sets the function to be used to determine
1363: convergence.
1365: Collective on KSP
1367: Input Parameters:
1368: + ksp - iterative context obtained from KSPCreate()
1369: . converge - pointer to int function
1370: - cctx - context for private data for the convergence routine (may be null)
1372: Calling sequence of converge:
1373: $ converge (KSP ksp, int it, PetscReal rnorm, KSPConvergedReason *reason,void *mctx)
1375: + ksp - iterative context obtained from KSPCreate()
1376: . it - iteration number
1377: . rnorm - (estimated) 2-norm of (preconditioned) residual
1378: . reason - the reason why it has converged or diverged
1379: - cctx - optional convergence context, as set by KSPSetConvergenceTest()
1382: Notes:
1383: Must be called after the KSP type has been set so put this after
1384: a call to KSPSetType(), or KSPSetFromOptions().
1386: The default convergence test, KSPDefaultConverged(), aborts if the
1387: residual grows to more than 10000 times the initial residual.
1389: The default is a combination of relative and absolute tolerances.
1390: The residual value that is tested may be an approximation; routines
1391: that need exact values should compute them.
1393: In the default PETSc convergence test, the precise values of reason
1394: are macros such as KSP_CONVERGED_RTOL, which are defined in petscksp.h.
1396: Level: advanced
1398: .keywords: KSP, set, convergence, test, context
1400: .seealso: KSPDefaultConverged(), KSPGetConvergenceContext()
1401: @*/
1402: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetConvergenceTest(KSP ksp,PetscErrorCode (*converge)(KSP,PetscInt,PetscReal,KSPConvergedReason*,void*),void *cctx)
1403: {
1406: ksp->converged = converge;
1407: ksp->cnvP = (void*)cctx;
1408: return(0);
1409: }
1413: /*@C
1414: KSPGetConvergenceContext - Gets the convergence context set with
1415: KSPSetConvergenceTest().
1417: Not Collective
1419: Input Parameter:
1420: . ksp - iterative context obtained from KSPCreate()
1422: Output Parameter:
1423: . ctx - monitoring context
1425: Level: advanced
1427: .keywords: KSP, get, convergence, test, context
1429: .seealso: KSPDefaultConverged(), KSPSetConvergenceTest()
1430: @*/
1431: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetConvergenceContext(KSP ksp,void **ctx)
1432: {
1435: *ctx = ksp->cnvP;
1436: return(0);
1437: }
1441: /*@
1442: KSPBuildSolution - Builds the approximate solution in a vector provided.
1443: This routine is NOT commonly needed (see KSPSolve()).
1445: Collective on KSP
1447: Input Parameter:
1448: . ctx - iterative context obtained from KSPCreate()
1450: Output Parameter:
1451: Provide exactly one of
1452: + v - location to stash solution.
1453: - V - the solution is returned in this location. This vector is created
1454: internally. This vector should NOT be destroyed by the user with
1455: VecDestroy().
1457: Notes:
1458: This routine can be used in one of two ways
1459: .vb
1460: KSPBuildSolution(ksp,PETSC_NULL,&V);
1461: or
1462: KSPBuildSolution(ksp,v,PETSC_NULL);
1463: .ve
1464: In the first case an internal vector is allocated to store the solution
1465: (the user cannot destroy this vector). In the second case the solution
1466: is generated in the vector that the user provides. Note that for certain
1467: methods, such as KSPCG, the second case requires a copy of the solution,
1468: while in the first case the call is essentially free since it simply
1469: returns the vector where the solution already is stored.
1471: Level: advanced
1473: .keywords: KSP, build, solution
1475: .seealso: KSPGetSolution(), KSPBuildResidual()
1476: @*/
1477: PetscErrorCode PETSCKSP_DLLEXPORT KSPBuildSolution(KSP ksp,Vec v,Vec *V)
1478: {
1483: if (!V && !v) SETERRQ(PETSC_ERR_ARG_WRONG,"Must provide either v or V");
1484: if (!V) V = &v;
1485: (*ksp->ops->buildsolution)(ksp,v,V);
1486: return(0);
1487: }
1491: /*@
1492: KSPBuildResidual - Builds the residual in a vector provided.
1494: Collective on KSP
1496: Input Parameter:
1497: . ksp - iterative context obtained from KSPCreate()
1499: Output Parameters:
1500: + v - optional location to stash residual. If v is not provided,
1501: then a location is generated.
1502: . t - work vector. If not provided then one is generated.
1503: - V - the residual
1505: Notes:
1506: Regardless of whether or not v is provided, the residual is
1507: returned in V.
1509: Level: advanced
1511: .keywords: KSP, build, residual
1513: .seealso: KSPBuildSolution()
1514: @*/
1515: PetscErrorCode PETSCKSP_DLLEXPORT KSPBuildResidual(KSP ksp,Vec t,Vec v,Vec *V)
1516: {
1518: PetscTruth flag = PETSC_FALSE;
1519: Vec w = v,tt = t;
1523: if (!w) {
1524: VecDuplicate(ksp->vec_rhs,&w);
1525: PetscLogObjectParent((PetscObject)ksp,w);
1526: }
1527: if (!tt) {
1528: VecDuplicate(ksp->vec_sol,&tt); flag = PETSC_TRUE;
1529: PetscLogObjectParent((PetscObject)ksp,tt);
1530: }
1531: (*ksp->ops->buildresidual)(ksp,tt,w,V);
1532: if (flag) {VecDestroy(tt);}
1533: return(0);
1534: }
1538: /*@
1539: KSPSetDiagonalScale - Tells KSP to symmetrically diagonally scale the system
1540: before solving. This actually CHANGES the matrix (and right hand side).
1542: Collective on KSP
1544: Input Parameter:
1545: + ksp - the KSP context
1546: - scale - PETSC_TRUE or PETSC_FALSE
1548: Options Database Key:
1549: + -ksp_diagonal_scale -
1550: - -ksp_diagonal_scale_fix - scale the matrix back AFTER the solve
1553: BE CAREFUL with this routine: it actually scales the matrix and right
1554: hand side that define the system. After the system is solved the matrix
1555: and right hand side remain scaled.
1557: This routine is only used if the matrix and preconditioner matrix are
1558: the same thing.
1560: This should NOT be used within the SNES solves if you are using a line
1561: search.
1562:
1563: If you use this with the PCType Eisenstat preconditioner than you can
1564: use the PCEisenstatNoDiagonalScaling() option, or -pc_eisenstat_no_diagonal_scaling
1565: to save some unneeded, redundant flops.
1567: Level: intermediate
1569: .keywords: KSP, set, options, prefix, database
1571: .seealso: KSPGetDiagonalScale(), KSPSetDiagonalScaleFix()
1572: @*/
1573: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetDiagonalScale(KSP ksp,PetscTruth scale)
1574: {
1577: ksp->dscale = scale;
1578: return(0);
1579: }
1583: /*@C
1584: KSPGetDiagonalScale - Checks if KSP solver scales the matrix and
1585: right hand side
1587: Not Collective
1589: Input Parameter:
1590: . ksp - the KSP context
1592: Output Parameter:
1593: . scale - PETSC_TRUE or PETSC_FALSE
1595: Notes:
1596: BE CAREFUL with this routine: it actually scales the matrix and right
1597: hand side that define the system. After the system is solved the matrix
1598: and right hand side remain scaled.
1600: This routine is only used if the matrix and preconditioner matrix are
1601: the same thing.
1603: Level: intermediate
1605: .keywords: KSP, set, options, prefix, database
1607: .seealso: KSPSetDiagonalScale(), KSPSetDiagonalScaleFix()
1608: @*/
1609: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetDiagonalScale(KSP ksp,PetscTruth *scale)
1610: {
1614: *scale = ksp->dscale;
1615: return(0);
1616: }
1620: /*@
1621: KSPSetDiagonalScaleFix - Tells KSP to diagonally scale the system
1622: back after solving.
1624: Collective on KSP
1626: Input Parameter:
1627: + ksp - the KSP context
1628: - fix - PETSC_TRUE to scale back after the system solve, PETSC_FALSE to not
1629: rescale (default)
1631: Notes:
1632: Must be called after KSPSetDiagonalScale()
1634: Using this will slow things down, because it rescales the matrix before and
1635: after each linear solve. This is intended mainly for testing to allow one
1636: to easily get back the original system to make sure the solution computed is
1637: accurate enough.
1639: This routine is only used if the matrix and preconditioner matrix are
1640: the same thing.
1642: Level: intermediate
1644: .keywords: KSP, set, options, prefix, database
1646: .seealso: KSPGetDiagonalScale(), KSPSetDiagonalScale(), KSPGetDiagonalScaleFix()
1647: @*/
1648: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetDiagonalScaleFix(KSP ksp,PetscTruth fix)
1649: {
1652: ksp->dscalefix = fix;
1653: return(0);
1654: }
1658: /*@
1659: KSPGetDiagonalScaleFix - Determines if KSP diagonally scales the system
1660: back after solving.
1662: Collective on KSP
1664: Input Parameter:
1665: . ksp - the KSP context
1667: Output Parameter:
1668: . fix - PETSC_TRUE to scale back after the system solve, PETSC_FALSE to not
1669: rescale (default)
1671: Notes:
1672: Must be called after KSPSetDiagonalScale()
1674: If PETSC_TRUE will slow things down, because it rescales the matrix before and
1675: after each linear solve. This is intended mainly for testing to allow one
1676: to easily get back the original system to make sure the solution computed is
1677: accurate enough.
1679: This routine is only used if the matrix and preconditioner matrix are
1680: the same thing.
1682: Level: intermediate
1684: .keywords: KSP, set, options, prefix, database
1686: .seealso: KSPGetDiagonalScale(), KSPSetDiagonalScale(), KSPSetDiagonalScaleFix()
1687: @*/
1688: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetDiagonalScaleFix(KSP ksp,PetscTruth *fix)
1689: {
1693: *fix = ksp->dscalefix;
1694: return(0);
1695: }