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_(((PetscObject)ksp)->comm);
59: PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_ASCII,&iascii);
60: if (iascii) {
61: KSPGetType(ksp,&type);
62: if (((PetscObject)ksp)->prefix) {
63: PetscViewerASCIIPrintf(viewer,"KSP Object:(%s)\n",((PetscObject)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: $ Implicitly sets KSPSkipConverged as KSP convergence test.
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: KSPSetConvergenceTest(ksp,KSPSkipConverged,0,0);
141: PetscInfo(ksp,"Warning: setting KSPNormType to skip computing the norm\n\
142: KSP convergence test is implicitly set to KSPSkipConverged\n");
143: }
144: return(0);
145: }
149: /*@
150: KSPSetCheckNormIteration - Sets the first iteration at which the norm of the residual will be
151: computed and used in the convergence test.
153: Collective on KSP
155: Input Parameter:
156: + ksp - Krylov solver context
157: - it - use -1 to check at all iterations
159: Notes:
160: Currently only works with Bi-CG-stab
162: Use KSPSetNormType(ksp,KSP_NORM_NO) to never check the norm
164: Level: advanced
166: .keywords: KSP, create, context, norms
168: .seealso: KSPSetUp(), KSPSolve(), KSPDestroy(), KSPSkipConverged(), KSPSetNormType()
169: @*/
170: PetscErrorCode KSPSetCheckNormIteration(KSP ksp,PetscInt it)
171: {
174: ksp->chknorm = it;
175: return(0);
176: }
180: /*@
181: KSPGetNormType - Sets the norm that is used for convergence testing.
183: Not Collective
185: Input Parameter:
186: . ksp - Krylov solver context
188: Output Parameter:
189: . normtype - norm that is used for convergence testing
191: Level: advanced
193: .keywords: KSP, create, context, norms
195: .seealso: KSPNormType, KSPSetNormType(), KSPSkipConverged()
196: @*/
197: PetscErrorCode KSPGetNormType(KSP ksp, KSPNormType *normtype) {
201: *normtype = ksp->normtype;
202: return(0);
203: }
205: #if 0
208: static PetscErrorCode KSPPublish_Petsc(PetscObject obj)
209: {
211: return(0);
212: }
213: #endif
217: /*@
218: KSPSetOperators - Sets the matrix associated with the linear system
219: and a (possibly) different one associated with the preconditioner.
221: Collective on KSP and Mat
223: Input Parameters:
224: + ksp - the KSP context
225: . Amat - the matrix associated with the linear system
226: . Pmat - the matrix to be used in constructing the preconditioner, usually the
227: same as Amat.
228: - flag - flag indicating information about the preconditioner matrix structure
229: during successive linear solves. This flag is ignored the first time a
230: linear system is solved, and thus is irrelevant when solving just one linear
231: system.
233: Notes:
234: The flag can be used to eliminate unnecessary work in the preconditioner
235: during the repeated solution of linear systems of the same size. The
236: available options are
237: $ SAME_PRECONDITIONER -
238: $ Pmat is identical during successive linear solves.
239: $ This option is intended for folks who are using
240: $ different Amat and Pmat matrices and want to reuse the
241: $ same preconditioner matrix. For example, this option
242: $ saves work by not recomputing incomplete factorization
243: $ for ILU/ICC preconditioners.
244: $ SAME_NONZERO_PATTERN -
245: $ Pmat has the same nonzero structure during
246: $ successive linear solves.
247: $ DIFFERENT_NONZERO_PATTERN -
248: $ Pmat does not have the same nonzero structure.
250: Caution:
251: If you specify SAME_NONZERO_PATTERN, PETSc believes your assertion
252: and does not check the structure of the matrix. If you erroneously
253: claim that the structure is the same when it actually is not, the new
254: preconditioner will not function correctly. Thus, use this optimization
255: feature carefully!
257: If in doubt about whether your preconditioner matrix has changed
258: structure or not, use the flag DIFFERENT_NONZERO_PATTERN.
260: Level: beginner
262: Alternative usage: If the operators have NOT been set with KSP/PCSetOperators() then the operators
263: are created in PC and returned to the user. In this case, if both operators
264: mat and pmat are requested, two DIFFERENT operators will be returned. If
265: only one is requested both operators in the PC will be the same (i.e. as
266: if one had called KSP/PCSetOperators() with the same argument for both Mats).
267: The user must set the sizes of the returned matrices and their type etc just
268: as if the user created them with MatCreate(). For example,
270: $ KSP/PCGetOperators(ksp/pc,&mat,PETSC_NULL,PETSC_NULL); is equivalent to
271: $ set size, type, etc of mat
273: $ MatCreate(comm,&mat);
274: $ KSP/PCSetOperators(ksp/pc,mat,mat,SAME_NONZERO_PATTERN);
275: $ PetscObjectDereference((PetscObject)mat);
276: $ set size, type, etc of mat
278: and
280: $ KSP/PCGetOperators(ksp/pc,&mat,&pmat,PETSC_NULL); is equivalent to
281: $ set size, type, etc of mat and pmat
283: $ MatCreate(comm,&mat);
284: $ MatCreate(comm,&pmat);
285: $ KSP/PCSetOperators(ksp/pc,mat,pmat,SAME_NONZERO_PATTERN);
286: $ PetscObjectDereference((PetscObject)mat);
287: $ PetscObjectDereference((PetscObject)pmat);
288: $ set size, type, etc of mat and pmat
290: The rational for this support is so that when creating a TS, SNES, or KSP the hierarchy
291: of underlying objects (i.e. SNES, KSP, PC, Mat) and their livespans can be completely
292: managed by the top most level object (i.e. the TS, SNES, or KSP). Another way to look
293: at this is when you create a SNES you do not NEED to create a KSP and attach it to
294: the SNES object (the SNES object manages it for you). Similarly when you create a KSP
295: you do not need to attach a PC to it (the KSP object manages the PC object for you).
296: Thus, why should YOU have to create the Mat and attach it to the SNES/KSP/PC, when
297: it can be created for you?
299: .keywords: KSP, set, operators, matrix, preconditioner, linear system
301: .seealso: KSPSolve(), KSPGetPC(), PCGetOperators(), PCSetOperators(), KSPGetOperators()
302: @*/
303: PetscErrorCode KSPSetOperators(KSP ksp,Mat Amat,Mat Pmat,MatStructure flag)
304: {
313: PCSetOperators(ksp->pc,Amat,Pmat,flag);
314: if (ksp->setupcalled > 1) ksp->setupcalled = 1; /* so that next solve call will call setup */
315: return(0);
316: }
320: /*@
321: KSPGetOperators - Gets the matrix associated with the linear system
322: and a (possibly) different one associated with the preconditioner.
324: Collective on KSP and Mat
326: Input Parameter:
327: . ksp - the KSP context
329: Output Parameters:
330: + Amat - the matrix associated with the linear system
331: . Pmat - the matrix to be used in constructing the preconditioner, usually the
332: same as Amat.
333: - flag - flag indicating information about the preconditioner matrix structure
334: during successive linear solves. This flag is ignored the first time a
335: linear system is solved, and thus is irrelevant when solving just one linear
336: system.
338: Level: intermediate
340: .keywords: KSP, set, get, operators, matrix, preconditioner, linear system
342: .seealso: KSPSolve(), KSPGetPC(), PCGetOperators(), PCSetOperators(), KSPSetOperators(), KSPGetOperatorsSet()
343: @*/
344: PetscErrorCode KSPGetOperators(KSP ksp,Mat *Amat,Mat *Pmat,MatStructure *flag)
345: {
350: PCGetOperators(ksp->pc,Amat,Pmat,flag);
351: return(0);
352: }
356: /*@C
357: KSPGetOperatorsSet - Determines if the matrix associated with the linear system and
358: possibly a different one associated with the preconditioner have been set in the KSP.
360: Not collective, though the results on all processes should be the same
362: Input Parameter:
363: . pc - the preconditioner context
365: Output Parameters:
366: + mat - the matrix associated with the linear system was set
367: - pmat - matrix associated with the preconditioner was set, usually the same
369: Level: intermediate
371: .keywords: KSP, get, operators, matrix, linear system
373: .seealso: PCSetOperators(), KSPGetOperators(), KSPSetOperators(), PCGetOperators(), PCGetOperatorsSet()
374: @*/
375: PetscErrorCode KSPGetOperatorsSet(KSP ksp,PetscTruth *mat,PetscTruth *pmat)
376: {
381: PCGetOperatorsSet(ksp->pc,mat,pmat);
382: return(0);
383: }
387: /*@
388: KSPCreate - Creates the default KSP context.
390: Collective on MPI_Comm
392: Input Parameter:
393: . comm - MPI communicator
395: Output Parameter:
396: . ksp - location to put the KSP context
398: Notes:
399: The default KSP type is GMRES with a restart of 30, using modified Gram-Schmidt
400: orthogonalization.
402: Level: beginner
404: .keywords: KSP, create, context
406: .seealso: KSPSetUp(), KSPSolve(), KSPDestroy(), KSP
407: @*/
408: PetscErrorCode KSPCreate(MPI_Comm comm,KSP *inksp)
409: {
410: KSP ksp;
412: void *ctx;
416: *inksp = 0;
417: #ifndef PETSC_USE_DYNAMIC_LIBRARIES
418: KSPInitializePackage(PETSC_NULL);
419: #endif
421: PetscHeaderCreate(ksp,_p_KSP,struct _KSPOps,KSP_COOKIE,-1,"KSP",comm,KSPDestroy,KSPView);
423: ksp->max_it = 10000;
424: ksp->pc_side = PC_LEFT;
425: ksp->rtol = 1.e-5;
426: ksp->abstol = 1.e-50;
427: ksp->divtol = 1.e4;
428:
429: ksp->chknorm = -1;
430: ksp->normtype = KSP_NORM_PRECONDITIONED;
431: ksp->rnorm = 0.0;
432: ksp->its = 0;
433: ksp->guess_zero = PETSC_TRUE;
434: ksp->calc_sings = PETSC_FALSE;
435: ksp->res_hist = PETSC_NULL;
436: ksp->res_hist_alloc = PETSC_NULL;
437: ksp->res_hist_len = 0;
438: ksp->res_hist_max = 0;
439: ksp->res_hist_reset = PETSC_TRUE;
440: ksp->numbermonitors = 0;
442: KSPDefaultConvergedCreate(&ctx);
443: KSPSetConvergenceTest(ksp,KSPDefaultConverged,ctx,KSPDefaultConvergedDestroy);
444: ksp->ops->buildsolution = KSPDefaultBuildSolution;
445: ksp->ops->buildresidual = KSPDefaultBuildResidual;
447: ksp->vec_sol = 0;
448: ksp->vec_rhs = 0;
449: ksp->pc = 0;
450: ksp->data = 0;
451: ksp->nwork = 0;
452: ksp->work = 0;
453: ksp->reason = KSP_CONVERGED_ITERATING;
454: ksp->setupcalled = 0;
456: PetscPublishAll(ksp);
457: PCCreate(comm,&ksp->pc);
458: *inksp = ksp;
459: return(0);
460: }
461:
464: /*@C
465: KSPSetType - Builds KSP for a particular solver.
467: Collective on KSP
469: Input Parameters:
470: + ksp - the Krylov space context
471: - type - a known method
473: Options Database Key:
474: . -ksp_type <method> - Sets the method; use -help for a list
475: of available methods (for instance, cg or gmres)
477: Notes:
478: See "petsc/include/petscksp.h" for available methods (for instance,
479: KSPCG or KSPGMRES).
481: Normally, it is best to use the KSPSetFromOptions() command and
482: then set the KSP type from the options database rather than by using
483: this routine. Using the options database provides the user with
484: maximum flexibility in evaluating the many different Krylov methods.
485: The KSPSetType() routine is provided for those situations where it
486: is necessary to set the iterative solver independently of the command
487: line or options database. This might be the case, for example, when
488: the choice of iterative solver changes during the execution of the
489: program, and the user's application is taking responsibility for
490: choosing the appropriate method. In other words, this routine is
491: not for beginners.
493: Level: intermediate
495: .keywords: KSP, set, method
497: .seealso: PCSetType(), KSPType
499: @*/
500: PetscErrorCode KSPSetType(KSP ksp, KSPType type)
501: {
502: PetscErrorCode ierr,(*r)(KSP);
503: PetscTruth match;
509: PetscTypeCompare((PetscObject)ksp,type,&match);
510: if (match) return(0);
512: PetscFListFind(KSPList,((PetscObject)ksp)->comm,type,(void (**)(void)) &r);
513: if (!r) SETERRQ1(PETSC_ERR_ARG_UNKNOWN_TYPE,"Unable to find requested KSP type %s",type);
514: /* Destroy the previous private KSP context */
515: if (ksp->ops->destroy) { (*ksp->ops->destroy)(ksp); }
516: /* Reinitialize function pointers in KSPOps structure */
517: PetscMemzero(ksp->ops,sizeof(struct _KSPOps));
518: ksp->ops->buildsolution = KSPDefaultBuildSolution;
519: ksp->ops->buildresidual = KSPDefaultBuildResidual;
520: /* Call the KSPCreate_XXX routine for this particular Krylov solver */
521: ksp->setupcalled = 0;
522: (*r)(ksp);
523: PetscObjectChangeTypeName((PetscObject)ksp,type);
524: return(0);
525: }
529: /*@
530: KSPRegisterDestroy - Frees the list of KSP methods that were
531: registered by KSPRegisterDynamic().
533: Not Collective
535: Level: advanced
537: .keywords: KSP, register, destroy
539: .seealso: KSPRegisterDynamic(), KSPRegisterAll()
540: @*/
541: PetscErrorCode KSPRegisterDestroy(void)
542: {
546: PetscFListDestroy(&KSPList);
547: KSPRegisterAllCalled = PETSC_FALSE;
548: return(0);
549: }
553: /*@C
554: KSPGetType - Gets the KSP type as a string from the KSP object.
556: Not Collective
558: Input Parameter:
559: . ksp - Krylov context
561: Output Parameter:
562: . name - name of KSP method
564: Level: intermediate
566: .keywords: KSP, get, method, name
568: .seealso: KSPSetType()
569: @*/
570: PetscErrorCode KSPGetType(KSP ksp,KSPType *type)
571: {
575: *type = ((PetscObject)ksp)->type_name;
576: return(0);
577: }
581: /*@C
582: KSPRegister - See KSPRegisterDynamic()
584: Level: advanced
585: @*/
586: PetscErrorCode KSPRegister(const char sname[],const char path[],const char name[],PetscErrorCode (*function)(KSP))
587: {
589: char fullname[PETSC_MAX_PATH_LEN];
592: PetscFListConcat(path,name,fullname);
593: PetscFListAdd(&KSPList,sname,fullname,(void (*)(void))function);
594: return(0);
595: }
599: /*@
600: KSPSetNullSpace - Sets the null space of the operator
602: Collective on KSP
604: Input Parameters:
605: + ksp - the Krylov space object
606: - nullsp - the null space of the operator
608: Level: advanced
610: .seealso: KSPSetOperators(), MatNullSpaceCreate(), KSPGetNullSpace()
611: @*/
612: PetscErrorCode KSPSetNullSpace(KSP ksp,MatNullSpace nullsp)
613: {
619: PetscObjectReference((PetscObject)nullsp);
620: if (ksp->nullsp) { MatNullSpaceDestroy(ksp->nullsp); }
621: ksp->nullsp = nullsp;
622: return(0);
623: }
627: /*@
628: KSPGetNullSpace - Gets the null space of the operator
630: Collective on KSP
632: Input Parameters:
633: + ksp - the Krylov space object
634: - nullsp - the null space of the operator
636: Level: advanced
638: .seealso: KSPSetOperators(), MatNullSpaceCreate(), KSPSetNullSpace()
639: @*/
640: PetscErrorCode KSPGetNullSpace(KSP ksp,MatNullSpace *nullsp)
641: {
645: *nullsp = ksp->nullsp;
646: return(0);
647: }