Actual source code: itcreate.c
1: #define PETSCKSP_DLL
3: /*
4: The basic KSP routines, Create, View etc. are here.
5: */
6: #include include/private/kspimpl.h
7: #include petscsys.h
9: /* Logging support */
10: PetscCookie KSP_COOKIE = 0;
11: PetscEvent KSP_GMRESOrthogonalization = 0, KSP_SetUp = 0, KSP_Solve = 0;
14: PetscTruth KSPRegisterAllCalled = PETSC_FALSE;
18: /*@C
19: KSPView - Prints the KSP data structure.
21: Collective on KSP
23: Input Parameters:
24: + ksp - the Krylov space context
25: - viewer - visualization context
27: Options Database Keys:
28: . -ksp_view - print the ksp data structure at the end of a KSPSolve call
30: Note:
31: The available visualization contexts include
32: + PETSC_VIEWER_STDOUT_SELF - standard output (default)
33: - PETSC_VIEWER_STDOUT_WORLD - synchronized standard
34: output where only the first processor opens
35: the file. All other processors send their
36: data to the first processor to print.
38: The user can open an alternative visualization context with
39: PetscViewerASCIIOpen() - output to a specified file.
41: Level: beginner
43: .keywords: KSP, view
45: .seealso: PCView(), PetscViewerASCIIOpen()
46: @*/
47: PetscErrorCode KSPView(KSP ksp,PetscViewer viewer)
48: {
49: const char *type;
51: PetscTruth iascii;
55: if (!viewer) viewer = PETSC_VIEWER_STDOUT_(ksp->comm);
59: PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_ASCII,&iascii);
60: if (iascii) {
61: KSPGetType(ksp,&type);
62: if (ksp->prefix) {
63: PetscViewerASCIIPrintf(viewer,"KSP Object:(%s)\n",ksp->prefix);
64: } else {
65: PetscViewerASCIIPrintf(viewer,"KSP Object:\n");
66: }
67: if (type) {
68: PetscViewerASCIIPrintf(viewer," type: %s\n",type);
69: } else {
70: PetscViewerASCIIPrintf(viewer," type: not yet set\n");
71: }
72: if (ksp->ops->view) {
73: PetscViewerASCIIPushTab(viewer);
74: (*ksp->ops->view)(ksp,viewer);
75: PetscViewerASCIIPopTab(viewer);
76: }
77: if (ksp->guess_zero) {PetscViewerASCIIPrintf(viewer," maximum iterations=%D, initial guess is zero\n",ksp->max_it);}
78: else {PetscViewerASCIIPrintf(viewer," maximum iterations=%D\n", ksp->max_it);}
79: if (ksp->guess_knoll) {PetscViewerASCIIPrintf(viewer," using preconditioner applied to right hand side for initial guess\n");}
80: PetscViewerASCIIPrintf(viewer," tolerances: relative=%G, absolute=%G, divergence=%G\n",ksp->rtol,ksp->abstol,ksp->divtol);
81: if (ksp->pc_side == PC_RIGHT) {PetscViewerASCIIPrintf(viewer," right preconditioning\n");}
82: else if (ksp->pc_side == PC_SYMMETRIC) {PetscViewerASCIIPrintf(viewer," symmetric preconditioning\n");}
83: else {PetscViewerASCIIPrintf(viewer," left preconditioning\n");}
84: } else {
85: if (ksp->ops->view) {
86: (*ksp->ops->view)(ksp,viewer);
87: }
88: }
89: PCView(ksp->pc,viewer);
90: return(0);
91: }
93: /*
94: Contains the list of registered KSP routines
95: */
96: PetscFList KSPList = 0;
100: /*@
101: KSPSetNormType - Sets the norm that is used for convergence testing.
103: Collective on KSP
105: Input Parameter:
106: + ksp - Krylov solver context
107: - normtype - one of
108: $ KSP_NORM_NO - skips computing the norm, this should only be used if you are using
109: $ the Krylov method as a smoother with a fixed small number of iterations.
110: $ You must also call KSPSetConvergenceTest(ksp,KSPSkipConverged,PETSC_NULL);
111: $ supported only by CG, Richardson, Bi-CG-stab, CR, and CGS methods.
112: $ KSP_NORM_PRECONDITIONED - the default for left preconditioned solves, uses the l2 norm
113: $ of the preconditioned residual
114: $ KSP_NORM_UNPRECONDITIONED - uses the l2 norm of the true b - Ax residual, supported only by
115: $ CG, CHEBYCHEV, and RICHARDSON, automatically true for right (see KSPSetPreconditioningSide())
116: $ preconditioning..
117: $ KSP_NORM_NATURAL - supported by cg, cr, and cgs
120: Options Database Key:
121: . -ksp_norm_type <none,preconditioned,unpreconditioned,natural>
123: Notes:
124: Currently only works with the CG, Richardson, Bi-CG-stab, CR, and CGS methods.
126: Level: advanced
128: .keywords: KSP, create, context, norms
130: .seealso: KSPSetUp(), KSPSolve(), KSPDestroy(), KSPSkipConverged()
131: @*/
132: PetscErrorCode KSPSetNormType(KSP ksp,KSPNormType normtype)
133: {
138: ksp->normtype = normtype;
139: if (normtype == KSP_NORM_NO) {
140: PetscInfo(ksp,"Warning seting KSPNormType to skip computing the norm\n\
141: make sure you set the KSP convergence test to KSPSkipConvergence\n");
142: }
143: return(0);
144: }
148: /*@
149: KSPGetNormType - Sets the norm that is used for convergence testing.
151: Not Collective
153: Input Parameter:
154: . ksp - Krylov solver context
156: Output Parameter:
157: . normtype - norm that is used for convergence testing
159: Level: advanced
161: .keywords: KSP, create, context, norms
163: .seealso: KSPNormType, KSPSetNormType(), KSPSkipConverged()
164: @*/
165: PetscErrorCode KSPGetNormType(KSP ksp, KSPNormType *normtype) {
169: *normtype = ksp->normtype;
170: return(0);
171: }
175: static PetscErrorCode KSPPublish_Petsc(PetscObject obj)
176: {
178: return(0);
179: }
183: /*@
184: KSPSetOperators - Sets the matrix associated with the linear system
185: and a (possibly) different one associated with the preconditioner.
187: Collective on KSP and Mat
189: Input Parameters:
190: + ksp - the KSP context
191: . Amat - the matrix associated with the linear system
192: . Pmat - the matrix to be used in constructing the preconditioner, usually the
193: same as Amat.
194: - flag - flag indicating information about the preconditioner matrix structure
195: during successive linear solves. This flag is ignored the first time a
196: linear system is solved, and thus is irrelevant when solving just one linear
197: system.
199: Notes:
200: The flag can be used to eliminate unnecessary work in the preconditioner
201: during the repeated solution of linear systems of the same size. The
202: available options are
203: $ SAME_PRECONDITIONER -
204: $ Pmat is identical during successive linear solves.
205: $ This option is intended for folks who are using
206: $ different Amat and Pmat matrices and want to reuse the
207: $ same preconditioner matrix. For example, this option
208: $ saves work by not recomputing incomplete factorization
209: $ for ILU/ICC preconditioners.
210: $ SAME_NONZERO_PATTERN -
211: $ Pmat has the same nonzero structure during
212: $ successive linear solves.
213: $ DIFFERENT_NONZERO_PATTERN -
214: $ Pmat does not have the same nonzero structure.
216: Caution:
217: If you specify SAME_NONZERO_PATTERN, PETSc believes your assertion
218: and does not check the structure of the matrix. If you erroneously
219: claim that the structure is the same when it actually is not, the new
220: preconditioner will not function correctly. Thus, use this optimization
221: feature carefully!
223: If in doubt about whether your preconditioner matrix has changed
224: structure or not, use the flag DIFFERENT_NONZERO_PATTERN.
226: Level: beginner
228: Alternative usage: If the operators have NOT been set with KSP/PCSetOperators() then the operators
229: are created in PC and returned to the user. In this case, if both operators
230: mat and pmat are requested, two DIFFERENT operators will be returned. If
231: only one is requested both operators in the PC will be the same (i.e. as
232: if one had called KSP/PCSetOperators() with the same argument for both Mats).
233: The user must set the sizes of the returned matrices and their type etc just
234: as if the user created them with MatCreate(). For example,
236: $ KSP/PCGetOperators(ksp/pc,&mat,PETSC_NULL,PETSC_NULL); is equivalent to
237: $ set size, type, etc of mat
239: $ MatCreate(comm,&mat);
240: $ KSP/PCSetOperators(ksp/pc,mat,mat,SAME_NONZERO_PATTERN);
241: $ PetscObjectDereference((PetscObject)mat);
242: $ set size, type, etc of mat
244: and
246: $ KSP/PCGetOperators(ksp/pc,&mat,&pmat,PETSC_NULL); is equivalent to
247: $ set size, type, etc of mat and pmat
249: $ MatCreate(comm,&mat);
250: $ MatCreate(comm,&pmat);
251: $ KSP/PCSetOperators(ksp/pc,mat,pmat,SAME_NONZERO_PATTERN);
252: $ PetscObjectDereference((PetscObject)mat);
253: $ PetscObjectDereference((PetscObject)pmat);
254: $ set size, type, etc of mat and pmat
256: The rational for this support is so that when creating a TS, SNES, or KSP the hierarchy
257: of underlying objects (i.e. SNES, KSP, PC, Mat) and their livespans can be completely
258: managed by the top most level object (i.e. the TS, SNES, or KSP). Another way to look
259: at this is when you create a SNES you do not NEED to create a KSP and attach it to
260: the SNES object (the SNES object manages it for you). Similarly when you create a KSP
261: you do not need to attach a PC to it (the KSP object manages the PC object for you).
262: Thus, why should YOU have to create the Mat and attach it to the SNES/KSP/PC, when
263: it can be created for you?
265: .keywords: KSP, set, operators, matrix, preconditioner, linear system
267: .seealso: KSPSolve(), KSPGetPC(), PCGetOperators(), PCSetOperators(), KSPGetOperators()
268: @*/
269: PetscErrorCode KSPSetOperators(KSP ksp,Mat Amat,Mat Pmat,MatStructure flag)
270: {
279: PCSetOperators(ksp->pc,Amat,Pmat,flag);
280: if (ksp->setupcalled > 1) ksp->setupcalled = 1; /* so that next solve call will call setup */
281: return(0);
282: }
286: /*@
287: KSPGetOperators - Gets the matrix associated with the linear system
288: and a (possibly) different one associated with the preconditioner.
290: Collective on KSP and Mat
292: Input Parameter:
293: . ksp - the KSP context
295: Output Parameters:
296: + Amat - the matrix associated with the linear system
297: . Pmat - the matrix to be used in constructing the preconditioner, usually the
298: same as Amat.
299: - flag - flag indicating information about the preconditioner matrix structure
300: during successive linear solves. This flag is ignored the first time a
301: linear system is solved, and thus is irrelevant when solving just one linear
302: system.
304: Level: intermediate
306: .keywords: KSP, set, get, operators, matrix, preconditioner, linear system
308: .seealso: KSPSolve(), KSPGetPC(), PCGetOperators(), PCSetOperators(), KSPSetOperators(), KSPGetOperatorsSet()
309: @*/
310: PetscErrorCode KSPGetOperators(KSP ksp,Mat *Amat,Mat *Pmat,MatStructure *flag)
311: {
316: PCGetOperators(ksp->pc,Amat,Pmat,flag);
317: return(0);
318: }
322: /*@C
323: KSPGetOperatorsSet - Determines if the matrix associated with the linear system and
324: possibly a different one associated with the preconditioner have been set in the KSP.
326: Not collective, though the results on all processes should be the same
328: Input Parameter:
329: . pc - the preconditioner context
331: Output Parameters:
332: + mat - the matrix associated with the linear system was set
333: - pmat - matrix associated with the preconditioner was set, usually the same
335: Level: intermediate
337: .keywords: KSP, get, operators, matrix, linear system
339: .seealso: PCSetOperators(), KSPGetOperators(), KSPSetOperators(), PCGetOperators(), PCGetOperatorsSet()
340: @*/
341: PetscErrorCode KSPGetOperatorsSet(KSP ksp,PetscTruth *mat,PetscTruth *pmat)
342: {
347: PCGetOperatorsSet(ksp->pc,mat,pmat);
348: return(0);
349: }
353: /*@
354: KSPCreate - Creates the default KSP context.
356: Collective on MPI_Comm
358: Input Parameter:
359: . comm - MPI communicator
361: Output Parameter:
362: . ksp - location to put the KSP context
364: Notes:
365: The default KSP type is GMRES with a restart of 30, using modified Gram-Schmidt
366: orthogonalization.
368: Level: beginner
370: .keywords: KSP, create, context
372: .seealso: KSPSetUp(), KSPSolve(), KSPDestroy(), KSP
373: @*/
374: PetscErrorCode KSPCreate(MPI_Comm comm,KSP *inksp)
375: {
376: KSP ksp;
381: *inksp = 0;
382: #ifndef PETSC_USE_DYNAMIC_LIBRARIES
383: KSPInitializePackage(PETSC_NULL);
384: #endif
386: PetscHeaderCreate(ksp,_p_KSP,struct _KSPOps,KSP_COOKIE,-1,"KSP",comm,KSPDestroy,KSPView);
387: ksp->bops->publish = KSPPublish_Petsc;
389: ksp->type = -1;
390: ksp->max_it = 10000;
391: ksp->pc_side = PC_LEFT;
392: ksp->rtol = 1.e-5;
393: ksp->abstol = 1.e-50;
394: ksp->divtol = 1.e4;
396: ksp->normtype = KSP_NORM_PRECONDITIONED;
397: ksp->rnorm = 0.0;
398: ksp->its = 0;
399: ksp->guess_zero = PETSC_TRUE;
400: ksp->calc_sings = PETSC_FALSE;
401: ksp->res_hist = PETSC_NULL;
402: ksp->res_hist_alloc = PETSC_NULL;
403: ksp->res_hist_len = 0;
404: ksp->res_hist_max = 0;
405: ksp->res_hist_reset = PETSC_TRUE;
406: ksp->numbermonitors = 0;
408: ksp->converged = KSPDefaultConverged;
409: ksp->ops->buildsolution = KSPDefaultBuildSolution;
410: ksp->ops->buildresidual = KSPDefaultBuildResidual;
412: ksp->vec_sol = 0;
413: ksp->vec_rhs = 0;
414: ksp->pc = 0;
415: ksp->data = 0;
416: ksp->nwork = 0;
417: ksp->work = 0;
418: ksp->cnvP = 0;
419: ksp->reason = KSP_CONVERGED_ITERATING;
420: ksp->setupcalled = 0;
422: PetscPublishAll(ksp);
423: PCCreate(comm,&ksp->pc);
424: *inksp = ksp;
425: return(0);
426: }
427:
430: /*@C
431: KSPSetType - Builds KSP for a particular solver.
433: Collective on KSP
435: Input Parameters:
436: + ksp - the Krylov space context
437: - type - a known method
439: Options Database Key:
440: . -ksp_type <method> - Sets the method; use -help for a list
441: of available methods (for instance, cg or gmres)
443: Notes:
444: See "petsc/include/petscksp.h" for available methods (for instance,
445: KSPCG or KSPGMRES).
447: Normally, it is best to use the KSPSetFromOptions() command and
448: then set the KSP type from the options database rather than by using
449: this routine. Using the options database provides the user with
450: maximum flexibility in evaluating the many different Krylov methods.
451: The KSPSetType() routine is provided for those situations where it
452: is necessary to set the iterative solver independently of the command
453: line or options database. This might be the case, for example, when
454: the choice of iterative solver changes during the execution of the
455: program, and the user's application is taking responsibility for
456: choosing the appropriate method. In other words, this routine is
457: not for beginners.
459: Level: intermediate
461: .keywords: KSP, set, method
463: .seealso: PCSetType(), KSPType
465: @*/
466: PetscErrorCode KSPSetType(KSP ksp, KSPType type)
467: {
468: PetscErrorCode ierr,(*r)(KSP);
469: PetscTruth match;
475: PetscTypeCompare((PetscObject)ksp,type,&match);
476: if (match) return(0);
478: PetscFListFind(KSPList,ksp->comm,type,(void (**)(void)) &r);
479: if (!r) SETERRQ1(PETSC_ERR_ARG_UNKNOWN_TYPE,"Unable to find requested KSP type %s",type);
480: /* Destroy the previous private KSP context */
481: if (ksp->ops->destroy) { (*ksp->ops->destroy)(ksp); }
482: /* Reinitialize function pointers in KSPOps structure */
483: PetscMemzero(ksp->ops,sizeof(struct _KSPOps));
484: ksp->ops->buildsolution = KSPDefaultBuildSolution;
485: ksp->ops->buildresidual = KSPDefaultBuildResidual;
486: /* Call the KSPCreate_XXX routine for this particular Krylov solver */
487: ksp->setupcalled = 0;
488: (*r)(ksp);
489: PetscObjectChangeTypeName((PetscObject)ksp,type);
490: return(0);
491: }
495: /*@
496: KSPRegisterDestroy - Frees the list of KSP methods that were
497: registered by KSPRegisterDynamic().
499: Not Collective
501: Level: advanced
503: .keywords: KSP, register, destroy
505: .seealso: KSPRegisterDynamic(), KSPRegisterAll()
506: @*/
507: PetscErrorCode KSPRegisterDestroy(void)
508: {
512: PetscFListDestroy(&KSPList);
513: KSPRegisterAllCalled = PETSC_FALSE;
514: return(0);
515: }
519: /*@C
520: KSPGetType - Gets the KSP type as a string from the KSP object.
522: Not Collective
524: Input Parameter:
525: . ksp - Krylov context
527: Output Parameter:
528: . name - name of KSP method
530: Level: intermediate
532: .keywords: KSP, get, method, name
534: .seealso: KSPSetType()
535: @*/
536: PetscErrorCode KSPGetType(KSP ksp,KSPType *type)
537: {
541: *type = ksp->type_name;
542: return(0);
543: }
547: /*@C
548: KSPRegister - See KSPRegisterDynamic()
550: Level: advanced
551: @*/
552: PetscErrorCode KSPRegister(const char sname[],const char path[],const char name[],PetscErrorCode (*function)(KSP))
553: {
555: char fullname[PETSC_MAX_PATH_LEN];
558: PetscFListConcat(path,name,fullname);
559: PetscFListAdd(&KSPList,sname,fullname,(void (*)(void))function);
560: return(0);
561: }
565: /*@
566: KSPSetNullSpace - Sets the null space of the operator
568: Collective on KSP
570: Input Parameters:
571: + ksp - the Krylov space object
572: - nullsp - the null space of the operator
574: Level: advanced
576: .seealso: KSPSetOperators(), MatNullSpaceCreate(), KSPGetNullSpace()
577: @*/
578: PetscErrorCode KSPSetNullSpace(KSP ksp,MatNullSpace nullsp)
579: {
585: PetscObjectReference((PetscObject)nullsp);
586: if (ksp->nullsp) { MatNullSpaceDestroy(ksp->nullsp); }
587: ksp->nullsp = nullsp;
588: return(0);
589: }
593: /*@
594: KSPGetNullSpace - Gets the null space of the operator
596: Collective on KSP
598: Input Parameters:
599: + ksp - the Krylov space object
600: - nullsp - the null space of the operator
602: Level: advanced
604: .seealso: KSPSetOperators(), MatNullSpaceCreate(), KSPSetNullSpace()
605: @*/
606: PetscErrorCode KSPGetNullSpace(KSP ksp,MatNullSpace *nullsp)
607: {
611: *nullsp = ksp->nullsp;
612: return(0);
613: }