Actual source code: fieldsplit.c

petsc-3.12.0 2019-09-29
Report Typos and Errors

  2:  #include <petsc/private/pcimpl.h>
  3: #include <petsc/private/kspimpl.h>    /*  This is needed to provide the appropriate PETSC_EXTERN for KSP_Solve_FS ....*/
  4:  #include <petscdm.h>

  6: const char *const PCFieldSplitSchurPreTypes[] = {"SELF","SELFP","A11","USER","FULL","PCFieldSplitSchurPreType","PC_FIELDSPLIT_SCHUR_PRE_",0};
  7: const char *const PCFieldSplitSchurFactTypes[] = {"DIAG","LOWER","UPPER","FULL","PCFieldSplitSchurFactType","PC_FIELDSPLIT_SCHUR_FACT_",0};

  9: PetscLogEvent KSP_Solve_FS_0,KSP_Solve_FS_1,KSP_Solve_FS_S,KSP_Solve_FS_U,KSP_Solve_FS_L,KSP_Solve_FS_2,KSP_Solve_FS_3,KSP_Solve_FS_4;

 11: typedef struct _PC_FieldSplitLink *PC_FieldSplitLink;
 12: struct _PC_FieldSplitLink {
 13:   KSP               ksp;
 14:   Vec               x,y,z;
 15:   char              *splitname;
 16:   PetscInt          nfields;
 17:   PetscInt          *fields,*fields_col;
 18:   VecScatter        sctx;
 19:   IS                is,is_col;
 20:   PC_FieldSplitLink next,previous;
 21:   PetscLogEvent     event;
 22: };

 24: typedef struct {
 25:   PCCompositeType type;
 26:   PetscBool       defaultsplit;                    /* Flag for a system with a set of 'k' scalar fields with the same layout (and bs = k) */
 27:   PetscBool       splitdefined;                    /* Flag is set after the splits have been defined, to prevent more splits from being added */
 28:   PetscInt        bs;                              /* Block size for IS and Mat structures */
 29:   PetscInt        nsplits;                         /* Number of field divisions defined */
 30:   Vec             *x,*y,w1,w2;
 31:   Mat             *mat;                            /* The diagonal block for each split */
 32:   Mat             *pmat;                           /* The preconditioning diagonal block for each split */
 33:   Mat             *Afield;                         /* The rows of the matrix associated with each split */
 34:   PetscBool       issetup;

 36:   /* Only used when Schur complement preconditioning is used */
 37:   Mat                       B;                     /* The (0,1) block */
 38:   Mat                       C;                     /* The (1,0) block */
 39:   Mat                       schur;                 /* The Schur complement S = A11 - A10 A00^{-1} A01, the KSP here, kspinner, is H_1 in [El08] */
 40:   Mat                       schurp;                /* Assembled approximation to S built by MatSchurComplement to be used as a preconditioning matrix when solving with S */
 41:   Mat                       schur_user;            /* User-provided preconditioning matrix for the Schur complement */
 42:   PCFieldSplitSchurPreType  schurpre;              /* Determines which preconditioning matrix is used for the Schur complement */
 43:   PCFieldSplitSchurFactType schurfactorization;
 44:   KSP                       kspschur;              /* The solver for S */
 45:   KSP                       kspupper;              /* The solver for A in the upper diagonal part of the factorization (H_2 in [El08]) */
 46:   PetscScalar               schurscale;            /* Scaling factor for the Schur complement solution with DIAG factorization */

 48:   /* Only used when Golub-Kahan bidiagonalization preconditioning is used */
 49:   Mat                       H;                     /* The modified matrix H = A00 + nu*A01*A01'              */
 50:   PetscReal                 gkbtol;                /* Stopping tolerance for lower bound estimate            */
 51:   PetscInt                  gkbdelay;              /* The delay window for the stopping criterion            */
 52:   PetscReal                 gkbnu;                 /* Parameter for augmented Lagrangian H = A + nu*A01*A01' */
 53:   PetscInt                  gkbmaxit;              /* Maximum number of iterations for outer loop            */
 54:   PetscBool                 gkbmonitor;            /* Monitor for gkb iterations and the lower bound error   */
 55:   PetscViewer               gkbviewer;             /* Viewer context for gkbmonitor                          */
 56:   Vec                       u,v,d,Hu;              /* Work vectors for the GKB algorithm                     */
 57:   PetscScalar               *vecz;                 /* Contains intermediate values, eg for lower bound       */

 59:   PC_FieldSplitLink         head;
 60:   PetscBool                 isrestrict;             /* indicates PCFieldSplitRestrictIS() has been last called on this object, hack */
 61:   PetscBool                 suboptionsset;          /* Indicates that the KSPSetFromOptions() has been called on the sub-KSPs */
 62:   PetscBool                 dm_splits;              /* Whether to use DMCreateFieldDecomposition() whenever possible */
 63:   PetscBool                 diag_use_amat;          /* Whether to extract diagonal matrix blocks from Amat, rather than Pmat (weaker than -pc_use_amat) */
 64:   PetscBool                 offdiag_use_amat;       /* Whether to extract off-diagonal matrix blocks from Amat, rather than Pmat (weaker than -pc_use_amat) */
 65:   PetscBool                 detect;                 /* Whether to form 2-way split by finding zero diagonal entries */
 66: } PC_FieldSplit;

 68: /*
 69:     Notes:
 70:     there is no particular reason that pmat, x, and y are stored as arrays in PC_FieldSplit instead of
 71:    inside PC_FieldSplitLink, just historical. If you want to be able to add new fields after already using the
 72:    PC you could change this.
 73: */

 75: /* This helper is so that setting a user-provided preconditioning matrix is orthogonal to choosing to use it.  This way the
 76: * application-provided FormJacobian can provide this matrix without interfering with the user's (command-line) choices. */
 77: static Mat FieldSplitSchurPre(PC_FieldSplit *jac)
 78: {
 79:   switch (jac->schurpre) {
 80:   case PC_FIELDSPLIT_SCHUR_PRE_SELF: return jac->schur;
 81:   case PC_FIELDSPLIT_SCHUR_PRE_SELFP: return jac->schurp;
 82:   case PC_FIELDSPLIT_SCHUR_PRE_A11: return jac->pmat[1];
 83:   case PC_FIELDSPLIT_SCHUR_PRE_FULL: /* We calculate this and store it in schur_user */
 84:   case PC_FIELDSPLIT_SCHUR_PRE_USER: /* Use a user-provided matrix if it is given, otherwise diagonal block */
 85:   default:
 86:     return jac->schur_user ? jac->schur_user : jac->pmat[1];
 87:   }
 88: }


 91:  #include <petscdraw.h>
 92: static PetscErrorCode PCView_FieldSplit(PC pc,PetscViewer viewer)
 93: {
 94:   PC_FieldSplit     *jac = (PC_FieldSplit*)pc->data;
 95:   PetscErrorCode    ierr;
 96:   PetscBool         iascii,isdraw;
 97:   PetscInt          i,j;
 98:   PC_FieldSplitLink ilink = jac->head;

101:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&iascii);
102:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERDRAW,&isdraw);
103:   if (iascii) {
104:     if (jac->bs > 0) {
105:       PetscViewerASCIIPrintf(viewer,"  FieldSplit with %s composition: total splits = %D, blocksize = %D\n",PCCompositeTypes[jac->type],jac->nsplits,jac->bs);
106:     } else {
107:       PetscViewerASCIIPrintf(viewer,"  FieldSplit with %s composition: total splits = %D\n",PCCompositeTypes[jac->type],jac->nsplits);
108:     }
109:     if (pc->useAmat) {
110:       PetscViewerASCIIPrintf(viewer,"  using Amat (not Pmat) as operator for blocks\n");
111:     }
112:     if (jac->diag_use_amat) {
113:       PetscViewerASCIIPrintf(viewer,"  using Amat (not Pmat) as operator for diagonal blocks\n");
114:     }
115:     if (jac->offdiag_use_amat) {
116:       PetscViewerASCIIPrintf(viewer,"  using Amat (not Pmat) as operator for off-diagonal blocks\n");
117:     }
118:     PetscViewerASCIIPrintf(viewer,"  Solver info for each split is in the following KSP objects:\n");
119:     for (i=0; i<jac->nsplits; i++) {
120:       if (ilink->fields) {
121:         PetscViewerASCIIPrintf(viewer,"Split number %D Fields ",i);
122:         PetscViewerASCIIUseTabs(viewer,PETSC_FALSE);
123:         for (j=0; j<ilink->nfields; j++) {
124:           if (j > 0) {
125:             PetscViewerASCIIPrintf(viewer,",");
126:           }
127:           PetscViewerASCIIPrintf(viewer," %D",ilink->fields[j]);
128:         }
129:         PetscViewerASCIIPrintf(viewer,"\n");
130:         PetscViewerASCIIUseTabs(viewer,PETSC_TRUE);
131:       } else {
132:         PetscViewerASCIIPrintf(viewer,"Split number %D Defined by IS\n",i);
133:       }
134:       KSPView(ilink->ksp,viewer);
135:       ilink = ilink->next;
136:     }
137:   }

139:  if (isdraw) {
140:     PetscDraw draw;
141:     PetscReal x,y,w,wd;

143:     PetscViewerDrawGetDraw(viewer,0,&draw);
144:     PetscDrawGetCurrentPoint(draw,&x,&y);
145:     w    = 2*PetscMin(1.0 - x,x);
146:     wd   = w/(jac->nsplits + 1);
147:     x    = x - wd*(jac->nsplits-1)/2.0;
148:     for (i=0; i<jac->nsplits; i++) {
149:       PetscDrawPushCurrentPoint(draw,x,y);
150:       KSPView(ilink->ksp,viewer);
151:       PetscDrawPopCurrentPoint(draw);
152:       x    += wd;
153:       ilink = ilink->next;
154:     }
155:   }
156:   return(0);
157: }

159: static PetscErrorCode PCView_FieldSplit_Schur(PC pc,PetscViewer viewer)
160: {
161:   PC_FieldSplit              *jac = (PC_FieldSplit*)pc->data;
162:   PetscErrorCode             ierr;
163:   PetscBool                  iascii,isdraw;
164:   PetscInt                   i,j;
165:   PC_FieldSplitLink          ilink = jac->head;
166:   MatSchurComplementAinvType atype;

169:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&iascii);
170:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERDRAW,&isdraw);
171:   if (iascii) {
172:     if (jac->bs > 0) {
173:       PetscViewerASCIIPrintf(viewer,"  FieldSplit with Schur preconditioner, blocksize = %D, factorization %s\n",jac->bs,PCFieldSplitSchurFactTypes[jac->schurfactorization]);
174:     } else {
175:       PetscViewerASCIIPrintf(viewer,"  FieldSplit with Schur preconditioner, factorization %s\n",PCFieldSplitSchurFactTypes[jac->schurfactorization]);
176:     }
177:     if (pc->useAmat) {
178:       PetscViewerASCIIPrintf(viewer,"  using Amat (not Pmat) as operator for blocks\n");
179:     }
180:     switch (jac->schurpre) {
181:     case PC_FIELDSPLIT_SCHUR_PRE_SELF:
182:       PetscViewerASCIIPrintf(viewer,"  Preconditioner for the Schur complement formed from S itself\n");
183:       break;
184:     case PC_FIELDSPLIT_SCHUR_PRE_SELFP:
185:       MatSchurComplementGetAinvType(jac->schur,&atype);
186:       PetscViewerASCIIPrintf(viewer,"  Preconditioner for the Schur complement formed from Sp, an assembled approximation to S, which uses A00's %sdiagonal's inverse\n",atype == MAT_SCHUR_COMPLEMENT_AINV_DIAG ? "" : (atype == MAT_SCHUR_COMPLEMENT_AINV_BLOCK_DIAG ? "block " : "lumped "));break;
187:     case PC_FIELDSPLIT_SCHUR_PRE_A11:
188:       PetscViewerASCIIPrintf(viewer,"  Preconditioner for the Schur complement formed from A11\n");
189:       break;
190:     case PC_FIELDSPLIT_SCHUR_PRE_FULL:
191:       PetscViewerASCIIPrintf(viewer,"  Preconditioner for the Schur complement formed from the exact Schur complement\n");
192:       break;
193:     case PC_FIELDSPLIT_SCHUR_PRE_USER:
194:       if (jac->schur_user) {
195:         PetscViewerASCIIPrintf(viewer,"  Preconditioner for the Schur complement formed from user provided matrix\n");
196:       } else {
197:         PetscViewerASCIIPrintf(viewer,"  Preconditioner for the Schur complement formed from A11\n");
198:       }
199:       break;
200:     default:
201:       SETERRQ1(PetscObjectComm((PetscObject)pc), PETSC_ERR_ARG_OUTOFRANGE, "Invalid Schur preconditioning type: %d", jac->schurpre);
202:     }
203:     PetscViewerASCIIPrintf(viewer,"  Split info:\n");
204:     PetscViewerASCIIPushTab(viewer);
205:     for (i=0; i<jac->nsplits; i++) {
206:       if (ilink->fields) {
207:         PetscViewerASCIIPrintf(viewer,"Split number %D Fields ",i);
208:         PetscViewerASCIIUseTabs(viewer,PETSC_FALSE);
209:         for (j=0; j<ilink->nfields; j++) {
210:           if (j > 0) {
211:             PetscViewerASCIIPrintf(viewer,",");
212:           }
213:           PetscViewerASCIIPrintf(viewer," %D",ilink->fields[j]);
214:         }
215:         PetscViewerASCIIPrintf(viewer,"\n");
216:         PetscViewerASCIIUseTabs(viewer,PETSC_TRUE);
217:       } else {
218:         PetscViewerASCIIPrintf(viewer,"Split number %D Defined by IS\n",i);
219:       }
220:       ilink = ilink->next;
221:     }
222:     PetscViewerASCIIPrintf(viewer,"KSP solver for A00 block\n");
223:     PetscViewerASCIIPushTab(viewer);
224:     if (jac->head) {
225:       KSPView(jac->head->ksp,viewer);
226:     } else  {PetscViewerASCIIPrintf(viewer,"  not yet available\n");}
227:     PetscViewerASCIIPopTab(viewer);
228:     if (jac->head && jac->kspupper != jac->head->ksp) {
229:       PetscViewerASCIIPrintf(viewer,"KSP solver for upper A00 in upper triangular factor \n");
230:       PetscViewerASCIIPushTab(viewer);
231:       if (jac->kspupper) {KSPView(jac->kspupper,viewer);}
232:       else {PetscViewerASCIIPrintf(viewer,"  not yet available\n");}
233:       PetscViewerASCIIPopTab(viewer);
234:     }
235:     PetscViewerASCIIPrintf(viewer,"KSP solver for S = A11 - A10 inv(A00) A01 \n");
236:     PetscViewerASCIIPushTab(viewer);
237:     if (jac->kspschur) {
238:       KSPView(jac->kspschur,viewer);
239:     } else {
240:       PetscViewerASCIIPrintf(viewer,"  not yet available\n");
241:     }
242:     PetscViewerASCIIPopTab(viewer);
243:     PetscViewerASCIIPopTab(viewer);
244:   } else if (isdraw && jac->head) {
245:     PetscDraw draw;
246:     PetscReal x,y,w,wd,h;
247:     PetscInt  cnt = 2;
248:     char      str[32];

250:     PetscViewerDrawGetDraw(viewer,0,&draw);
251:     PetscDrawGetCurrentPoint(draw,&x,&y);
252:     if (jac->kspupper != jac->head->ksp) cnt++;
253:     w  = 2*PetscMin(1.0 - x,x);
254:     wd = w/(cnt + 1);

256:     PetscSNPrintf(str,32,"Schur fact. %s",PCFieldSplitSchurFactTypes[jac->schurfactorization]);
257:     PetscDrawStringBoxed(draw,x,y,PETSC_DRAW_RED,PETSC_DRAW_BLACK,str,NULL,&h);
258:     y   -= h;
259:     if (jac->schurpre == PC_FIELDSPLIT_SCHUR_PRE_USER &&  !jac->schur_user) {
260:       PetscSNPrintf(str,32,"Prec. for Schur from %s",PCFieldSplitSchurPreTypes[PC_FIELDSPLIT_SCHUR_PRE_A11]);
261:     } else {
262:       PetscSNPrintf(str,32,"Prec. for Schur from %s",PCFieldSplitSchurPreTypes[jac->schurpre]);
263:     }
264:     PetscDrawStringBoxed(draw,x+wd*(cnt-1)/2.0,y,PETSC_DRAW_RED,PETSC_DRAW_BLACK,str,NULL,&h);
265:     y   -= h;
266:     x    = x - wd*(cnt-1)/2.0;

268:     PetscDrawPushCurrentPoint(draw,x,y);
269:     KSPView(jac->head->ksp,viewer);
270:     PetscDrawPopCurrentPoint(draw);
271:     if (jac->kspupper != jac->head->ksp) {
272:       x   += wd;
273:       PetscDrawPushCurrentPoint(draw,x,y);
274:       KSPView(jac->kspupper,viewer);
275:       PetscDrawPopCurrentPoint(draw);
276:     }
277:     x   += wd;
278:     PetscDrawPushCurrentPoint(draw,x,y);
279:     KSPView(jac->kspschur,viewer);
280:     PetscDrawPopCurrentPoint(draw);
281:   }
282:   return(0);
283: }

285: static PetscErrorCode PCView_FieldSplit_GKB(PC pc,PetscViewer viewer)
286: {
287:   PC_FieldSplit     *jac = (PC_FieldSplit*)pc->data;
288:   PetscErrorCode    ierr;
289:   PetscBool         iascii,isdraw;
290:   PetscInt          i,j;
291:   PC_FieldSplitLink ilink = jac->head;

294:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&iascii);
295:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERDRAW,&isdraw);
296:   if (iascii) {
297:     if (jac->bs > 0) {
298:       PetscViewerASCIIPrintf(viewer,"  FieldSplit with %s composition: total splits = %D, blocksize = %D\n",PCCompositeTypes[jac->type],jac->nsplits,jac->bs);
299:     } else {
300:       PetscViewerASCIIPrintf(viewer,"  FieldSplit with %s composition: total splits = %D\n",PCCompositeTypes[jac->type],jac->nsplits);
301:     }
302:     if (pc->useAmat) {
303:       PetscViewerASCIIPrintf(viewer,"  using Amat (not Pmat) as operator for blocks\n");
304:     }
305:     if (jac->diag_use_amat) {
306:       PetscViewerASCIIPrintf(viewer,"  using Amat (not Pmat) as operator for diagonal blocks\n");
307:     }
308:     if (jac->offdiag_use_amat) {
309:       PetscViewerASCIIPrintf(viewer,"  using Amat (not Pmat) as operator for off-diagonal blocks\n");
310:     }

312:     PetscViewerASCIIPrintf(viewer,"  Stopping tolerance=%.1e, delay in error estimate=%D, maximum iterations=%D\n",jac->gkbtol,jac->gkbdelay,jac->gkbmaxit);
313:     PetscViewerASCIIPrintf(viewer,"  Solver info for H = A00 + nu*A01*A01' matrix:\n");
314:     PetscViewerASCIIPushTab(viewer);

316:     if (ilink->fields) {
317:       PetscViewerASCIIPrintf(viewer,"Split number %D Fields ",0);
318:       PetscViewerASCIIUseTabs(viewer,PETSC_FALSE);
319:       for (j=0; j<ilink->nfields; j++) {
320:         if (j > 0) {
321:           PetscViewerASCIIPrintf(viewer,",");
322:         }
323:         PetscViewerASCIIPrintf(viewer," %D",ilink->fields[j]);
324:       }
325:       PetscViewerASCIIPrintf(viewer,"\n");
326:       PetscViewerASCIIUseTabs(viewer,PETSC_TRUE);
327:     } else {
328:         PetscViewerASCIIPrintf(viewer,"Split number %D Defined by IS\n",0);
329:     }
330:     KSPView(ilink->ksp,viewer);

332:     PetscViewerASCIIPopTab(viewer);
333:   }

335:  if (isdraw) {
336:     PetscDraw draw;
337:     PetscReal x,y,w,wd;

339:     PetscViewerDrawGetDraw(viewer,0,&draw);
340:     PetscDrawGetCurrentPoint(draw,&x,&y);
341:     w    = 2*PetscMin(1.0 - x,x);
342:     wd   = w/(jac->nsplits + 1);
343:     x    = x - wd*(jac->nsplits-1)/2.0;
344:     for (i=0; i<jac->nsplits; i++) {
345:       PetscDrawPushCurrentPoint(draw,x,y);
346:       KSPView(ilink->ksp,viewer);
347:       PetscDrawPopCurrentPoint(draw);
348:       x    += wd;
349:       ilink = ilink->next;
350:     }
351:   }
352:   return(0);
353: }


356: /* Precondition: jac->bs is set to a meaningful value */
357: static PetscErrorCode PCFieldSplitSetRuntimeSplits_Private(PC pc)
358: {
360:   PC_FieldSplit  *jac = (PC_FieldSplit*)pc->data;
361:   PetscInt       i,nfields,*ifields,nfields_col,*ifields_col;
362:   PetscBool      flg,flg_col;
363:   char           optionname[128],splitname[8],optionname_col[128];

366:   PetscMalloc1(jac->bs,&ifields);
367:   PetscMalloc1(jac->bs,&ifields_col);
368:   for (i=0,flg=PETSC_TRUE;; i++) {
369:     PetscSNPrintf(splitname,sizeof(splitname),"%D",i);
370:     PetscSNPrintf(optionname,sizeof(optionname),"-pc_fieldsplit_%D_fields",i);
371:     PetscSNPrintf(optionname_col,sizeof(optionname_col),"-pc_fieldsplit_%D_fields_col",i);
372:     nfields     = jac->bs;
373:     nfields_col = jac->bs;
374:     PetscOptionsGetIntArray(((PetscObject)pc)->options,((PetscObject)pc)->prefix,optionname,ifields,&nfields,&flg);
375:     PetscOptionsGetIntArray(((PetscObject)pc)->options,((PetscObject)pc)->prefix,optionname_col,ifields_col,&nfields_col,&flg_col);
376:     if (!flg) break;
377:     else if (flg && !flg_col) {
378:       if (!nfields) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Cannot list zero fields");
379:       PCFieldSplitSetFields(pc,splitname,nfields,ifields,ifields);
380:     } else {
381:       if (!nfields || !nfields_col) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Cannot list zero fields");
382:       if (nfields != nfields_col) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Number of row and column fields must match");
383:       PCFieldSplitSetFields(pc,splitname,nfields,ifields,ifields_col);
384:     }
385:   }
386:   if (i > 0) {
387:     /* Makes command-line setting of splits take precedence over setting them in code.
388:        Otherwise subsequent calls to PCFieldSplitSetIS() or PCFieldSplitSetFields() would
389:        create new splits, which would probably not be what the user wanted. */
390:     jac->splitdefined = PETSC_TRUE;
391:   }
392:   PetscFree(ifields);
393:   PetscFree(ifields_col);
394:   return(0);
395: }

397: static PetscErrorCode PCFieldSplitSetDefaults(PC pc)
398: {
399:   PC_FieldSplit     *jac = (PC_FieldSplit*)pc->data;
400:   PetscErrorCode    ierr;
401:   PC_FieldSplitLink ilink = jac->head;
402:   PetscBool         fieldsplit_default = PETSC_FALSE,coupling = PETSC_FALSE;
403:   PetscInt          i;

406:   /*
407:    Kinda messy, but at least this now uses DMCreateFieldDecomposition().
408:    Should probably be rewritten.
409:    */
410:   if (!ilink) {
411:     PetscOptionsGetBool(((PetscObject)pc)->options,((PetscObject)pc)->prefix,"-pc_fieldsplit_detect_coupling",&coupling,NULL);
412:     if (pc->dm && jac->dm_splits && !jac->detect && !coupling) {
413:       PetscInt  numFields, f, i, j;
414:       char      **fieldNames;
415:       IS        *fields;
416:       DM        *dms;
417:       DM        subdm[128];
418:       PetscBool flg;

420:       DMCreateFieldDecomposition(pc->dm, &numFields, &fieldNames, &fields, &dms);
421:       /* Allow the user to prescribe the splits */
422:       for (i = 0, flg = PETSC_TRUE;; i++) {
423:         PetscInt ifields[128];
424:         IS       compField;
425:         char     optionname[128], splitname[8];
426:         PetscInt nfields = numFields;

428:         PetscSNPrintf(optionname, sizeof(optionname), "-pc_fieldsplit_%D_fields", i);
429:         PetscOptionsGetIntArray(((PetscObject)pc)->options,((PetscObject)pc)->prefix, optionname, ifields, &nfields, &flg);
430:         if (!flg) break;
431:         if (numFields > 128) SETERRQ1(PetscObjectComm((PetscObject)pc),PETSC_ERR_SUP,"Cannot currently support %d > 128 fields", numFields);
432:         DMCreateSubDM(pc->dm, nfields, ifields, &compField, &subdm[i]);
433:         if (nfields == 1) {
434:           PCFieldSplitSetIS(pc, fieldNames[ifields[0]], compField);
435:         } else {
436:           PetscSNPrintf(splitname, sizeof(splitname), "%D", i);
437:           PCFieldSplitSetIS(pc, splitname, compField);
438:         }
439:         ISDestroy(&compField);
440:         for (j = 0; j < nfields; ++j) {
441:           f    = ifields[j];
442:           PetscFree(fieldNames[f]);
443:           ISDestroy(&fields[f]);
444:         }
445:       }
446:       if (i == 0) {
447:         for (f = 0; f < numFields; ++f) {
448:           PCFieldSplitSetIS(pc, fieldNames[f], fields[f]);
449:           PetscFree(fieldNames[f]);
450:           ISDestroy(&fields[f]);
451:         }
452:       } else {
453:         for (j=0; j<numFields; j++) {
454:           DMDestroy(dms+j);
455:         }
456:         PetscFree(dms);
457:         PetscMalloc1(i, &dms);
458:         for (j = 0; j < i; ++j) dms[j] = subdm[j];
459:       }
460:       PetscFree(fieldNames);
461:       PetscFree(fields);
462:       if (dms) {
463:         PetscInfo(pc, "Setting up physics based fieldsplit preconditioner using the embedded DM\n");
464:         for (ilink = jac->head, i = 0; ilink; ilink = ilink->next, ++i) {
465:           const char *prefix;
466:           PetscObjectGetOptionsPrefix((PetscObject)(ilink->ksp),&prefix);
467:           PetscObjectSetOptionsPrefix((PetscObject)(dms[i]), prefix);
468:           KSPSetDM(ilink->ksp, dms[i]);
469:           KSPSetDMActive(ilink->ksp, PETSC_FALSE);
470:           {
471:             PetscErrorCode (*func)(KSP,Mat,Mat,void*);
472:             void            *ctx;

474:             DMKSPGetComputeOperators(pc->dm, &func, &ctx);
475:             DMKSPSetComputeOperators(dms[i],  func,  ctx);
476:           }
477:           PetscObjectIncrementTabLevel((PetscObject)dms[i],(PetscObject)ilink->ksp,0);
478:           DMDestroy(&dms[i]);
479:         }
480:         PetscFree(dms);
481:       }
482:     } else {
483:       if (jac->bs <= 0) {
484:         if (pc->pmat) {
485:           MatGetBlockSize(pc->pmat,&jac->bs);
486:         } else jac->bs = 1;
487:       }

489:       if (jac->detect) {
490:         IS       zerodiags,rest;
491:         PetscInt nmin,nmax;

493:         MatGetOwnershipRange(pc->mat,&nmin,&nmax);
494:         MatFindZeroDiagonals(pc->mat,&zerodiags);
495:         ISComplement(zerodiags,nmin,nmax,&rest);
496:         PCFieldSplitSetIS(pc,"0",rest);
497:         PCFieldSplitSetIS(pc,"1",zerodiags);
498:         ISDestroy(&zerodiags);
499:         ISDestroy(&rest);
500:       } else if (coupling) {
501:         IS       coupling,rest;
502:         PetscInt nmin,nmax;

504:         MatGetOwnershipRange(pc->mat,&nmin,&nmax);
505:         MatFindOffBlockDiagonalEntries(pc->mat,&coupling);
506:         ISCreateStride(PetscObjectComm((PetscObject)pc->mat),nmax-nmin,nmin,1,&rest);
507:         ISSetIdentity(rest);
508:         PCFieldSplitSetIS(pc,"0",rest);
509:         PCFieldSplitSetIS(pc,"1",coupling);
510:         ISDestroy(&coupling);
511:         ISDestroy(&rest);
512:       } else {
513:         PetscOptionsGetBool(((PetscObject)pc)->options,((PetscObject)pc)->prefix,"-pc_fieldsplit_default",&fieldsplit_default,NULL);
514:         if (!fieldsplit_default) {
515:           /* Allow user to set fields from command line,  if bs was known at the time of PCSetFromOptions_FieldSplit()
516:            then it is set there. This is not ideal because we should only have options set in XXSetFromOptions(). */
517:           PCFieldSplitSetRuntimeSplits_Private(pc);
518:           if (jac->splitdefined) {PetscInfo(pc,"Splits defined using the options database\n");}
519:         }
520:         if ((fieldsplit_default || !jac->splitdefined) && !jac->isrestrict) {
521:           Mat       M = pc->pmat;
522:           PetscBool isnest;

524:           PetscInfo(pc,"Using default splitting of fields\n");
525:           PetscObjectTypeCompare((PetscObject)pc->pmat,MATNEST,&isnest);
526:           if (!isnest) {
527:             M    = pc->mat;
528:             PetscObjectTypeCompare((PetscObject)pc->mat,MATNEST,&isnest);
529:           }
530:           if (isnest) {
531:             IS       *fields;
532:             PetscInt nf;

534:             MatNestGetSize(M,&nf,NULL);
535:             PetscMalloc1(nf,&fields);
536:             MatNestGetISs(M,fields,NULL);
537:             for (i=0;i<nf;i++) {
538:               PCFieldSplitSetIS(pc,NULL,fields[i]);
539:             }
540:             PetscFree(fields);
541:           } else {
542:             for (i=0; i<jac->bs; i++) {
543:               char splitname[8];
544:               PetscSNPrintf(splitname,sizeof(splitname),"%D",i);
545:               PCFieldSplitSetFields(pc,splitname,1,&i,&i);
546:             }
547:             jac->defaultsplit = PETSC_TRUE;
548:           }
549:         }
550:       }
551:     }
552:   } else if (jac->nsplits == 1) {
553:     if (ilink->is) {
554:       IS       is2;
555:       PetscInt nmin,nmax;

557:       MatGetOwnershipRange(pc->mat,&nmin,&nmax);
558:       ISComplement(ilink->is,nmin,nmax,&is2);
559:       PCFieldSplitSetIS(pc,"1",is2);
560:       ISDestroy(&is2);
561:     } else SETERRQ(PetscObjectComm((PetscObject)pc),PETSC_ERR_SUP,"Must provide at least two sets of fields to PCFieldSplit()");
562:   }

564:   if (jac->nsplits < 2) SETERRQ1(PetscObjectComm((PetscObject)pc),PETSC_ERR_PLIB,"Unhandled case, must have at least two fields, not %d", jac->nsplits);
565:   return(0);
566: }

568: static PetscErrorCode MatGolubKahanComputeExplicitOperator(Mat A,Mat B,Mat C,Mat *H,PetscReal gkbnu)
569: {
570:   PetscErrorCode    ierr;
571:   Mat               BT,T;
572:   PetscReal         nrmT,nrmB;

575:   MatHermitianTranspose(C,MAT_INITIAL_MATRIX,&T);            /* Test if augmented matrix is symmetric */
576:   MatAXPY(T,-1.0,B,DIFFERENT_NONZERO_PATTERN);
577:   MatNorm(T,NORM_1,&nrmT);
578:   MatNorm(B,NORM_1,&nrmB);
579:   if (nrmB > 0) {
580:     if (nrmT/nrmB >= PETSC_SMALL) {
581:       SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Matrix is not symmetric/hermitian, GKB is not applicable.");
582:     }
583:   }
584:   /* Compute augmented Lagrangian matrix H = A00 + nu*A01*A01'. This corresponds to */
585:   /* setting N := 1/nu*I in [Ar13].                                                 */
586:   MatHermitianTranspose(B,MAT_INITIAL_MATRIX,&BT);
587:   MatMatMult(B,BT,MAT_INITIAL_MATRIX,PETSC_DEFAULT,H);       /* H = A01*A01'          */
588:   MatAYPX(*H,gkbnu,A,DIFFERENT_NONZERO_PATTERN);             /* H = A00 + nu*A01*A01' */

590:   MatDestroy(&BT);
591:   MatDestroy(&T);
592:   return(0);
593: }

595: PETSC_EXTERN PetscErrorCode PetscOptionsFindPairPrefix_Private(PetscOptions,const char pre[], const char name[],const char *value[],PetscBool *flg);

597: static PetscErrorCode PCSetUp_FieldSplit(PC pc)
598: {
599:   PC_FieldSplit     *jac = (PC_FieldSplit*)pc->data;
600:   PetscErrorCode    ierr;
601:   PC_FieldSplitLink ilink;
602:   PetscInt          i,nsplit;
603:   PetscBool         sorted, sorted_col;

606:   pc->failedreason = PC_NOERROR;
607:   PCFieldSplitSetDefaults(pc);
608:   nsplit = jac->nsplits;
609:   ilink  = jac->head;

611:   /* get the matrices for each split */
612:   if (!jac->issetup) {
613:     PetscInt rstart,rend,nslots,bs;

615:     jac->issetup = PETSC_TRUE;

617:     /* This is done here instead of in PCFieldSplitSetFields() because may not have matrix at that point */
618:     if (jac->defaultsplit || !ilink->is) {
619:       if (jac->bs <= 0) jac->bs = nsplit;
620:     }
621:     bs     = jac->bs;
622:     MatGetOwnershipRange(pc->pmat,&rstart,&rend);
623:     nslots = (rend - rstart)/bs;
624:     for (i=0; i<nsplit; i++) {
625:       if (jac->defaultsplit) {
626:         ISCreateStride(PetscObjectComm((PetscObject)pc),nslots,rstart+i,nsplit,&ilink->is);
627:         ISDuplicate(ilink->is,&ilink->is_col);
628:       } else if (!ilink->is) {
629:         if (ilink->nfields > 1) {
630:           PetscInt *ii,*jj,j,k,nfields = ilink->nfields,*fields = ilink->fields,*fields_col = ilink->fields_col;
631:           PetscMalloc1(ilink->nfields*nslots,&ii);
632:           PetscMalloc1(ilink->nfields*nslots,&jj);
633:           for (j=0; j<nslots; j++) {
634:             for (k=0; k<nfields; k++) {
635:               ii[nfields*j + k] = rstart + bs*j + fields[k];
636:               jj[nfields*j + k] = rstart + bs*j + fields_col[k];
637:             }
638:           }
639:           ISCreateGeneral(PetscObjectComm((PetscObject)pc),nslots*nfields,ii,PETSC_OWN_POINTER,&ilink->is);
640:           ISCreateGeneral(PetscObjectComm((PetscObject)pc),nslots*nfields,jj,PETSC_OWN_POINTER,&ilink->is_col);
641:           ISSetBlockSize(ilink->is, nfields);
642:           ISSetBlockSize(ilink->is_col, nfields);
643:         } else {
644:           ISCreateStride(PetscObjectComm((PetscObject)pc),nslots,rstart+ilink->fields[0],bs,&ilink->is);
645:           ISCreateStride(PetscObjectComm((PetscObject)pc),nslots,rstart+ilink->fields_col[0],bs,&ilink->is_col);
646:         }
647:       }
648:       ISSorted(ilink->is,&sorted);
649:       if (ilink->is_col) { ISSorted(ilink->is_col,&sorted_col); }
650:       if (!sorted || !sorted_col) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Fields must be sorted when creating split");
651:       ilink = ilink->next;
652:     }
653:   }

655:   ilink = jac->head;
656:   if (!jac->pmat) {
657:     Vec xtmp;

659:     MatCreateVecs(pc->pmat,&xtmp,NULL);
660:     PetscMalloc1(nsplit,&jac->pmat);
661:     PetscMalloc2(nsplit,&jac->x,nsplit,&jac->y);
662:     for (i=0; i<nsplit; i++) {
663:       MatNullSpace sp;

665:       /* Check for preconditioning matrix attached to IS */
666:       PetscObjectQuery((PetscObject) ilink->is, "pmat", (PetscObject*) &jac->pmat[i]);
667:       if (jac->pmat[i]) {
668:         PetscObjectReference((PetscObject) jac->pmat[i]);
669:         if (jac->type == PC_COMPOSITE_SCHUR) {
670:           jac->schur_user = jac->pmat[i];

672:           PetscObjectReference((PetscObject) jac->schur_user);
673:         }
674:       } else {
675:         const char *prefix;
676:         MatCreateSubMatrix(pc->pmat,ilink->is,ilink->is_col,MAT_INITIAL_MATRIX,&jac->pmat[i]);
677:         KSPGetOptionsPrefix(ilink->ksp,&prefix);
678:         MatSetOptionsPrefix(jac->pmat[i],prefix);
679:         MatViewFromOptions(jac->pmat[i],NULL,"-mat_view");
680:       }
681:       /* create work vectors for each split */
682:       MatCreateVecs(jac->pmat[i],&jac->x[i],&jac->y[i]);
683:       ilink->x = jac->x[i]; ilink->y = jac->y[i]; ilink->z = NULL;
684:       /* compute scatter contexts needed by multiplicative versions and non-default splits */
685:       VecScatterCreate(xtmp,ilink->is,jac->x[i],NULL,&ilink->sctx);
686:       PetscObjectQuery((PetscObject) ilink->is, "nearnullspace", (PetscObject*) &sp);
687:       if (sp) {
688:         MatSetNearNullSpace(jac->pmat[i], sp);
689:       }
690:       ilink = ilink->next;
691:     }
692:     VecDestroy(&xtmp);
693:   } else {
694:     MatReuse scall;
695:     if (pc->flag == DIFFERENT_NONZERO_PATTERN) {
696:       for (i=0; i<nsplit; i++) {
697:         MatDestroy(&jac->pmat[i]);
698:       }
699:       scall = MAT_INITIAL_MATRIX;
700:     } else scall = MAT_REUSE_MATRIX;

702:     for (i=0; i<nsplit; i++) {
703:       Mat pmat;

705:       /* Check for preconditioning matrix attached to IS */
706:       PetscObjectQuery((PetscObject) ilink->is, "pmat", (PetscObject*) &pmat);
707:       if (!pmat) {
708:         MatCreateSubMatrix(pc->pmat,ilink->is,ilink->is_col,scall,&jac->pmat[i]);
709:       }
710:       ilink = ilink->next;
711:     }
712:   }
713:   if (jac->diag_use_amat) {
714:     ilink = jac->head;
715:     if (!jac->mat) {
716:       PetscMalloc1(nsplit,&jac->mat);
717:       for (i=0; i<nsplit; i++) {
718:         MatCreateSubMatrix(pc->mat,ilink->is,ilink->is_col,MAT_INITIAL_MATRIX,&jac->mat[i]);
719:         ilink = ilink->next;
720:       }
721:     } else {
722:       MatReuse scall;
723:       if (pc->flag == DIFFERENT_NONZERO_PATTERN) {
724:         for (i=0; i<nsplit; i++) {
725:           MatDestroy(&jac->mat[i]);
726:         }
727:         scall = MAT_INITIAL_MATRIX;
728:       } else scall = MAT_REUSE_MATRIX;

730:       for (i=0; i<nsplit; i++) {
731:         if (jac->mat[i]) {MatCreateSubMatrix(pc->mat,ilink->is,ilink->is_col,scall,&jac->mat[i]);}
732:         ilink = ilink->next;
733:       }
734:     }
735:   } else {
736:     jac->mat = jac->pmat;
737:   }

739:   /* Check for null space attached to IS */
740:   ilink = jac->head;
741:   for (i=0; i<nsplit; i++) {
742:     MatNullSpace sp;

744:     PetscObjectQuery((PetscObject) ilink->is, "nullspace", (PetscObject*) &sp);
745:     if (sp) {
746:       MatSetNullSpace(jac->mat[i], sp);
747:     }
748:     ilink = ilink->next;
749:   }

751:   if (jac->type != PC_COMPOSITE_ADDITIVE  && jac->type != PC_COMPOSITE_SCHUR && jac->type != PC_COMPOSITE_GKB) {
752:     /* extract the rows of the matrix associated with each field: used for efficient computation of residual inside algorithm */
753:     /* FIXME: Can/should we reuse jac->mat whenever (jac->diag_use_amat) is true? */
754:     ilink = jac->head;
755:     if (nsplit == 2 && jac->type == PC_COMPOSITE_MULTIPLICATIVE) {
756:       /* special case need where Afield[0] is not needed and only certain columns of Afield[1] are needed since update is only on those rows of the solution */
757:       if (!jac->Afield) {
758:         PetscCalloc1(nsplit,&jac->Afield);
759:         if (jac->offdiag_use_amat) {
760:           MatCreateSubMatrix(pc->mat,ilink->next->is,ilink->is,MAT_INITIAL_MATRIX,&jac->Afield[1]);
761:         } else {
762:           MatCreateSubMatrix(pc->pmat,ilink->next->is,ilink->is,MAT_INITIAL_MATRIX,&jac->Afield[1]);
763:         }
764:       } else {
765:         MatReuse scall;
766:         if (pc->flag == DIFFERENT_NONZERO_PATTERN) {
767:           for (i=0; i<nsplit; i++) {
768:             MatDestroy(&jac->Afield[1]);
769:           }
770:           scall = MAT_INITIAL_MATRIX;
771:         } else scall = MAT_REUSE_MATRIX;

773:         if (jac->offdiag_use_amat) {
774:           MatCreateSubMatrix(pc->mat,ilink->next->is,ilink->is,scall,&jac->Afield[1]);
775:         } else {
776:           MatCreateSubMatrix(pc->pmat,ilink->next->is,ilink->is,scall,&jac->Afield[1]);
777:         }
778:       }
779:     } else {
780:       if (!jac->Afield) {
781:         PetscMalloc1(nsplit,&jac->Afield);
782:         for (i=0; i<nsplit; i++) {
783:           if (jac->offdiag_use_amat) {
784:             MatCreateSubMatrix(pc->mat,ilink->is,NULL,MAT_INITIAL_MATRIX,&jac->Afield[i]);
785:           } else {
786:             MatCreateSubMatrix(pc->pmat,ilink->is,NULL,MAT_INITIAL_MATRIX,&jac->Afield[i]);
787:           }
788:           ilink = ilink->next;
789:         }
790:       } else {
791:         MatReuse scall;
792:         if (pc->flag == DIFFERENT_NONZERO_PATTERN) {
793:           for (i=0; i<nsplit; i++) {
794:             MatDestroy(&jac->Afield[i]);
795:           }
796:           scall = MAT_INITIAL_MATRIX;
797:         } else scall = MAT_REUSE_MATRIX;

799:         for (i=0; i<nsplit; i++) {
800:           if (jac->offdiag_use_amat) {
801:             MatCreateSubMatrix(pc->mat,ilink->is,NULL,scall,&jac->Afield[i]);
802:           } else {
803:             MatCreateSubMatrix(pc->pmat,ilink->is,NULL,scall,&jac->Afield[i]);
804:           }
805:           ilink = ilink->next;
806:         }
807:       }
808:     }
809:   }

811:   if (jac->type == PC_COMPOSITE_SCHUR) {
812:     IS          ccis;
813:     PetscBool   isspd;
814:     PetscInt    rstart,rend;
815:     char        lscname[256];
816:     PetscObject LSC_L;

818:     if (nsplit != 2) SETERRQ(PetscObjectComm((PetscObject)pc),PETSC_ERR_ARG_INCOMP,"To use Schur complement preconditioner you must have exactly 2 fields");

820:     /* If pc->mat is SPD, don't scale by -1 the Schur complement */
821:     if (jac->schurscale == (PetscScalar)-1.0) {
822:       MatGetOption(pc->pmat,MAT_SPD,&isspd);
823:       jac->schurscale = (isspd == PETSC_TRUE) ? 1.0 : -1.0;
824:     }

826:     /* When extracting off-diagonal submatrices, we take complements from this range */
827:     MatGetOwnershipRangeColumn(pc->mat,&rstart,&rend);

829:     /* need to handle case when one is resetting up the preconditioner */
830:     if (jac->schur) {
831:       KSP kspA = jac->head->ksp, kspInner = NULL, kspUpper = jac->kspupper;

833:       MatSchurComplementGetKSP(jac->schur, &kspInner);
834:       ilink = jac->head;
835:       ISComplement(ilink->is_col,rstart,rend,&ccis);
836:       if (jac->offdiag_use_amat) {
837:         MatCreateSubMatrix(pc->mat,ilink->is,ccis,MAT_REUSE_MATRIX,&jac->B);
838:       } else {
839:         MatCreateSubMatrix(pc->pmat,ilink->is,ccis,MAT_REUSE_MATRIX,&jac->B);
840:       }
841:       ISDestroy(&ccis);
842:       ilink = ilink->next;
843:       ISComplement(ilink->is_col,rstart,rend,&ccis);
844:       if (jac->offdiag_use_amat) {
845:         MatCreateSubMatrix(pc->mat,ilink->is,ccis,MAT_REUSE_MATRIX,&jac->C);
846:       } else {
847:         MatCreateSubMatrix(pc->pmat,ilink->is,ccis,MAT_REUSE_MATRIX,&jac->C);
848:       }
849:       ISDestroy(&ccis);
850:       MatSchurComplementUpdateSubMatrices(jac->schur,jac->mat[0],jac->pmat[0],jac->B,jac->C,jac->mat[1]);
851:       if (jac->schurpre == PC_FIELDSPLIT_SCHUR_PRE_SELFP) {
852:         MatDestroy(&jac->schurp);
853:         MatSchurComplementGetPmat(jac->schur,MAT_INITIAL_MATRIX,&jac->schurp);
854:       }
855:       if (kspA != kspInner) {
856:         KSPSetOperators(kspA,jac->mat[0],jac->pmat[0]);
857:       }
858:       if (kspUpper != kspA) {
859:         KSPSetOperators(kspUpper,jac->mat[0],jac->pmat[0]);
860:       }
861:       KSPSetOperators(jac->kspschur,jac->schur,FieldSplitSchurPre(jac));
862:     } else {
863:       const char   *Dprefix;
864:       char         schurprefix[256], schurmatprefix[256];
865:       char         schurtestoption[256];
866:       MatNullSpace sp;
867:       PetscBool    flg;
868:       KSP          kspt;

870:       /* extract the A01 and A10 matrices */
871:       ilink = jac->head;
872:       ISComplement(ilink->is_col,rstart,rend,&ccis);
873:       if (jac->offdiag_use_amat) {
874:         MatCreateSubMatrix(pc->mat,ilink->is,ccis,MAT_INITIAL_MATRIX,&jac->B);
875:       } else {
876:         MatCreateSubMatrix(pc->pmat,ilink->is,ccis,MAT_INITIAL_MATRIX,&jac->B);
877:       }
878:       ISDestroy(&ccis);
879:       ilink = ilink->next;
880:       ISComplement(ilink->is_col,rstart,rend,&ccis);
881:       if (jac->offdiag_use_amat) {
882:         MatCreateSubMatrix(pc->mat,ilink->is,ccis,MAT_INITIAL_MATRIX,&jac->C);
883:       } else {
884:         MatCreateSubMatrix(pc->pmat,ilink->is,ccis,MAT_INITIAL_MATRIX,&jac->C);
885:       }
886:       ISDestroy(&ccis);

888:       /* Use mat[0] (diagonal block of Amat) preconditioned by pmat[0] to define Schur complement */
889:       MatCreate(((PetscObject)jac->mat[0])->comm,&jac->schur);
890:       MatSetType(jac->schur,MATSCHURCOMPLEMENT);
891:       MatSchurComplementSetSubMatrices(jac->schur,jac->mat[0],jac->pmat[0],jac->B,jac->C,jac->mat[1]);
892:       PetscSNPrintf(schurmatprefix, sizeof(schurmatprefix), "%sfieldsplit_%s_", ((PetscObject)pc)->prefix ? ((PetscObject)pc)->prefix : "", ilink->splitname);
893:       MatSetOptionsPrefix(jac->schur,schurmatprefix);
894:       MatSchurComplementGetKSP(jac->schur,&kspt);
895:       KSPSetOptionsPrefix(kspt,schurmatprefix);

897:       /* Note: this is not true in general */
898:       MatGetNullSpace(jac->mat[1], &sp);
899:       if (sp) {
900:         MatSetNullSpace(jac->schur, sp);
901:       }

903:       PetscSNPrintf(schurtestoption, sizeof(schurtestoption), "-fieldsplit_%s_inner_", ilink->splitname);
904:       PetscOptionsFindPairPrefix_Private(((PetscObject)pc)->options,((PetscObject)pc)->prefix, schurtestoption, NULL, &flg);
905:       if (flg) {
906:         DM  dmInner;
907:         KSP kspInner;
908:         PC  pcInner;

910:         MatSchurComplementGetKSP(jac->schur, &kspInner);
911:         KSPReset(kspInner);
912:         KSPSetOperators(kspInner,jac->mat[0],jac->pmat[0]);
913:         PetscSNPrintf(schurprefix, sizeof(schurprefix), "%sfieldsplit_%s_inner_", ((PetscObject)pc)->prefix ? ((PetscObject)pc)->prefix : "", ilink->splitname);
914:         /* Indent this deeper to emphasize the "inner" nature of this solver. */
915:         PetscObjectIncrementTabLevel((PetscObject)kspInner, (PetscObject) pc, 2);
916:         PetscObjectIncrementTabLevel((PetscObject)kspInner->pc, (PetscObject) pc, 2);
917:         KSPSetOptionsPrefix(kspInner, schurprefix);

919:         /* Set DM for new solver */
920:         KSPGetDM(jac->head->ksp, &dmInner);
921:         KSPSetDM(kspInner, dmInner);
922:         KSPSetDMActive(kspInner, PETSC_FALSE);

924:         /* Defaults to PCKSP as preconditioner */
925:         KSPGetPC(kspInner, &pcInner);
926:         PCSetType(pcInner, PCKSP);
927:         PCKSPSetKSP(pcInner, jac->head->ksp);
928:       } else {
929:          /* Use the outer solver for the inner solve, but revert the KSPPREONLY from PCFieldSplitSetFields_FieldSplit or
930:           * PCFieldSplitSetIS_FieldSplit. We don't want KSPPREONLY because it makes the Schur complement inexact,
931:           * preventing Schur complement reduction to be an accurate solve. Usually when an iterative solver is used for
932:           * S = D - C A_inner^{-1} B, we expect S to be defined using an accurate definition of A_inner^{-1}, so we make
933:           * GMRES the default. Note that it is also common to use PREONLY for S, in which case S may not be used
934:           * directly, and the user is responsible for setting an inexact method for fieldsplit's A^{-1}. */
935:         KSPSetType(jac->head->ksp,KSPGMRES);
936:         MatSchurComplementSetKSP(jac->schur,jac->head->ksp);
937:       }
938:       KSPSetOperators(jac->head->ksp,jac->mat[0],jac->pmat[0]);
939:       KSPSetFromOptions(jac->head->ksp);
940:       MatSetFromOptions(jac->schur);

942:       PetscObjectTypeCompare((PetscObject)jac->schur, MATSCHURCOMPLEMENT, &flg);
943:       if (flg) { /* Need to do this otherwise PCSetUp_KSP will overwrite the amat of jac->head->ksp */
944:         KSP kspInner;
945:         PC  pcInner;

947:         MatSchurComplementGetKSP(jac->schur, &kspInner);
948:         KSPGetPC(kspInner, &pcInner);
949:         PetscObjectTypeCompare((PetscObject)pcInner, PCKSP, &flg);
950:         if (flg) {
951:           KSP ksp;

953:           PCKSPGetKSP(pcInner, &ksp);
954:           if (ksp == jac->head->ksp) {
955:             PCSetUseAmat(pcInner, PETSC_TRUE);
956:           }
957:         }
958:       }
959:       PetscSNPrintf(schurtestoption, sizeof(schurtestoption), "-fieldsplit_%s_upper_", ilink->splitname);
960:       PetscOptionsFindPairPrefix_Private(((PetscObject)pc)->options,((PetscObject)pc)->prefix, schurtestoption, NULL, &flg);
961:       if (flg) {
962:         DM dmInner;

964:         PetscSNPrintf(schurprefix, sizeof(schurprefix), "%sfieldsplit_%s_upper_", ((PetscObject)pc)->prefix ? ((PetscObject)pc)->prefix : "", ilink->splitname);
965:         KSPCreate(PetscObjectComm((PetscObject)pc), &jac->kspupper);
966:         KSPSetErrorIfNotConverged(jac->kspupper,pc->erroriffailure);
967:         KSPSetOptionsPrefix(jac->kspupper, schurprefix);
968:         PetscObjectIncrementTabLevel((PetscObject)jac->kspupper, (PetscObject) pc, 1);
969:         PetscObjectIncrementTabLevel((PetscObject)jac->kspupper->pc, (PetscObject) pc, 1);
970:         KSPGetDM(jac->head->ksp, &dmInner);
971:         KSPSetDM(jac->kspupper, dmInner);
972:         KSPSetDMActive(jac->kspupper, PETSC_FALSE);
973:         KSPSetFromOptions(jac->kspupper);
974:         KSPSetOperators(jac->kspupper,jac->mat[0],jac->pmat[0]);
975:         VecDuplicate(jac->head->x, &jac->head->z);
976:       } else {
977:         jac->kspupper = jac->head->ksp;
978:         PetscObjectReference((PetscObject) jac->head->ksp);
979:       }

981:       if (jac->schurpre == PC_FIELDSPLIT_SCHUR_PRE_SELFP) {
982:         MatSchurComplementGetPmat(jac->schur,MAT_INITIAL_MATRIX,&jac->schurp);
983:       }
984:       KSPCreate(PetscObjectComm((PetscObject)pc),&jac->kspschur);
985:       KSPSetErrorIfNotConverged(jac->kspschur,pc->erroriffailure);
986:       PetscLogObjectParent((PetscObject)pc,(PetscObject)jac->kspschur);
987:       PetscObjectIncrementTabLevel((PetscObject)jac->kspschur,(PetscObject)pc,1);
988:       if (jac->schurpre == PC_FIELDSPLIT_SCHUR_PRE_SELF) {
989:         PC pcschur;
990:         KSPGetPC(jac->kspschur,&pcschur);
991:         PCSetType(pcschur,PCNONE);
992:         /* Note: This is bad if there exist preconditioners for MATSCHURCOMPLEMENT */
993:       } else if (jac->schurpre == PC_FIELDSPLIT_SCHUR_PRE_FULL) {
994:         MatSchurComplementComputeExplicitOperator(jac->schur, &jac->schur_user);
995:       }
996:       KSPSetOperators(jac->kspschur,jac->schur,FieldSplitSchurPre(jac));
997:       KSPGetOptionsPrefix(jac->head->next->ksp, &Dprefix);
998:       KSPSetOptionsPrefix(jac->kspschur,         Dprefix);
999:       /* propagate DM */
1000:       {
1001:         DM sdm;
1002:         KSPGetDM(jac->head->next->ksp, &sdm);
1003:         if (sdm) {
1004:           KSPSetDM(jac->kspschur, sdm);
1005:           KSPSetDMActive(jac->kspschur, PETSC_FALSE);
1006:         }
1007:       }
1008:       /* really want setfromoptions called in PCSetFromOptions_FieldSplit(), but it is not ready yet */
1009:       /* need to call this every time, since the jac->kspschur is freshly created, otherwise its options never get set */
1010:       KSPSetFromOptions(jac->kspschur);
1011:     }
1012:     MatAssemblyBegin(jac->schur,MAT_FINAL_ASSEMBLY);
1013:     MatAssemblyEnd(jac->schur,MAT_FINAL_ASSEMBLY);

1015:     /* HACK: special support to forward L and Lp matrices that might be used by PCLSC */
1016:     PetscSNPrintf(lscname,sizeof(lscname),"%s_LSC_L",ilink->splitname);
1017:     PetscObjectQuery((PetscObject)pc->mat,lscname,(PetscObject*)&LSC_L);
1018:     if (!LSC_L) {PetscObjectQuery((PetscObject)pc->pmat,lscname,(PetscObject*)&LSC_L);}
1019:     if (LSC_L) {PetscObjectCompose((PetscObject)jac->schur,"LSC_L",(PetscObject)LSC_L);}
1020:     PetscSNPrintf(lscname,sizeof(lscname),"%s_LSC_Lp",ilink->splitname);
1021:     PetscObjectQuery((PetscObject)pc->pmat,lscname,(PetscObject*)&LSC_L);
1022:     if (!LSC_L) {PetscObjectQuery((PetscObject)pc->mat,lscname,(PetscObject*)&LSC_L);}
1023:     if (LSC_L) {PetscObjectCompose((PetscObject)jac->schur,"LSC_Lp",(PetscObject)LSC_L);}
1024:   } else if (jac->type == PC_COMPOSITE_GKB) {
1025:     IS          ccis;
1026:     PetscInt    rstart,rend;

1028:     if (nsplit != 2) SETERRQ(PetscObjectComm((PetscObject)pc),PETSC_ERR_ARG_INCOMP,"To use GKB preconditioner you must have exactly 2 fields");

1030:     ilink = jac->head;

1032:     /* When extracting off-diagonal submatrices, we take complements from this range */
1033:     MatGetOwnershipRangeColumn(pc->mat,&rstart,&rend);

1035:     ISComplement(ilink->is_col,rstart,rend,&ccis);
1036:     if (jac->offdiag_use_amat) {
1037:      MatCreateSubMatrix(pc->mat,ilink->is,ccis,MAT_INITIAL_MATRIX,&jac->B);
1038:     } else {
1039:       MatCreateSubMatrix(pc->pmat,ilink->is,ccis,MAT_INITIAL_MATRIX,&jac->B);
1040:     }
1041:     ISDestroy(&ccis);
1042:     /* Create work vectors for GKB algorithm */
1043:     VecDuplicate(ilink->x,&jac->u);
1044:     VecDuplicate(ilink->x,&jac->Hu);
1045:     VecDuplicate(ilink->x,&jac->w2);
1046:     ilink = ilink->next;
1047:     ISComplement(ilink->is_col,rstart,rend,&ccis);
1048:     if (jac->offdiag_use_amat) {
1049:       MatCreateSubMatrix(pc->mat,ilink->is,ccis,MAT_INITIAL_MATRIX,&jac->C);
1050:     } else {
1051:       MatCreateSubMatrix(pc->pmat,ilink->is,ccis,MAT_INITIAL_MATRIX,&jac->C);
1052:     }
1053:     ISDestroy(&ccis);
1054:     /* Create work vectors for GKB algorithm */
1055:     VecDuplicate(ilink->x,&jac->v);
1056:     VecDuplicate(ilink->x,&jac->d);
1057:     VecDuplicate(ilink->x,&jac->w1);
1058:     MatGolubKahanComputeExplicitOperator(jac->mat[0],jac->B,jac->C,&jac->H,jac->gkbnu);
1059:     PetscCalloc1(jac->gkbdelay,&jac->vecz);

1061:     ilink = jac->head;
1062:     KSPSetOperators(ilink->ksp,jac->H,jac->H);
1063:     if (!jac->suboptionsset) {KSPSetFromOptions(ilink->ksp);}
1064:     /* Create gkb_monitor context */
1065:     if (jac->gkbmonitor) {
1066:       PetscInt  tablevel;
1067:       PetscViewerCreate(PETSC_COMM_WORLD,&jac->gkbviewer);
1068:       PetscViewerSetType(jac->gkbviewer,PETSCVIEWERASCII);
1069:       PetscObjectGetTabLevel((PetscObject)ilink->ksp,&tablevel);
1070:       PetscViewerASCIISetTab(jac->gkbviewer,tablevel);
1071:       PetscObjectIncrementTabLevel((PetscObject)ilink->ksp,(PetscObject)ilink->ksp,1);
1072:     }
1073:   } else {
1074:     /* set up the individual splits' PCs */
1075:     i     = 0;
1076:     ilink = jac->head;
1077:     while (ilink) {
1078:       KSPSetOperators(ilink->ksp,jac->mat[i],jac->pmat[i]);
1079:       /* really want setfromoptions called in PCSetFromOptions_FieldSplit(), but it is not ready yet */
1080:       if (!jac->suboptionsset) {KSPSetFromOptions(ilink->ksp);}
1081:       i++;
1082:       ilink = ilink->next;
1083:     }
1084:   }

1086:   jac->suboptionsset = PETSC_TRUE;
1087:   return(0);
1088: }

1090: #define FieldSplitSplitSolveAdd(ilink,xx,yy) \
1091:   (VecScatterBegin(ilink->sctx,xx,ilink->x,INSERT_VALUES,SCATTER_FORWARD) || \
1092:    VecScatterEnd(ilink->sctx,xx,ilink->x,INSERT_VALUES,SCATTER_FORWARD) || \
1093:    PetscLogEventBegin(ilink->event,ilink->ksp,ilink->x,ilink->y,NULL) ||\
1094:    KSPSolve(ilink->ksp,ilink->x,ilink->y) ||                               \
1095:    KSPCheckSolve(ilink->ksp,pc,ilink->y)  || \
1096:    PetscLogEventEnd(ilink->event,ilink->ksp,ilink->x,ilink->y,NULL) ||\
1097:    VecScatterBegin(ilink->sctx,ilink->y,yy,ADD_VALUES,SCATTER_REVERSE) ||  \
1098:    VecScatterEnd(ilink->sctx,ilink->y,yy,ADD_VALUES,SCATTER_REVERSE))

1100: static PetscErrorCode PCApply_FieldSplit_Schur(PC pc,Vec x,Vec y)
1101: {
1102:   PC_FieldSplit      *jac = (PC_FieldSplit*)pc->data;
1103:   PetscErrorCode     ierr;
1104:   PC_FieldSplitLink  ilinkA = jac->head, ilinkD = ilinkA->next;
1105:   KSP                kspA   = ilinkA->ksp, kspLower = kspA, kspUpper = jac->kspupper;

1108:   switch (jac->schurfactorization) {
1109:   case PC_FIELDSPLIT_SCHUR_FACT_DIAG:
1110:     /* [A00 0; 0 -S], positive definite, suitable for MINRES */
1111:     VecScatterBegin(ilinkA->sctx,x,ilinkA->x,INSERT_VALUES,SCATTER_FORWARD);
1112:     VecScatterBegin(ilinkD->sctx,x,ilinkD->x,INSERT_VALUES,SCATTER_FORWARD);
1113:     VecScatterEnd(ilinkA->sctx,x,ilinkA->x,INSERT_VALUES,SCATTER_FORWARD);
1114:     PetscLogEventBegin(ilinkA->event,kspA,ilinkA->x,ilinkA->y,NULL);
1115:     KSPSolve(kspA,ilinkA->x,ilinkA->y);
1116:     KSPCheckSolve(kspA,pc,ilinkA->y);
1117:     PetscLogEventEnd(ilinkA->event,kspA,ilinkA->x,ilinkA->y,NULL);
1118:     VecScatterBegin(ilinkA->sctx,ilinkA->y,y,INSERT_VALUES,SCATTER_REVERSE);
1119:     VecScatterEnd(ilinkD->sctx,x,ilinkD->x,INSERT_VALUES,SCATTER_FORWARD);
1120:     PetscLogEventBegin(KSP_Solve_FS_S,jac->kspschur,ilinkD->x,ilinkD->y,NULL);
1121:     KSPSolve(jac->kspschur,ilinkD->x,ilinkD->y);
1122:     KSPCheckSolve(jac->kspschur,pc,ilinkD->y);
1123:     PetscLogEventEnd(KSP_Solve_FS_S,jac->kspschur,ilinkD->x,ilinkD->y,NULL);
1124:     VecScale(ilinkD->y,jac->schurscale);
1125:     VecScatterEnd(ilinkA->sctx,ilinkA->y,y,INSERT_VALUES,SCATTER_REVERSE);
1126:     VecScatterBegin(ilinkD->sctx,ilinkD->y,y,INSERT_VALUES,SCATTER_REVERSE);
1127:     VecScatterEnd(ilinkD->sctx,ilinkD->y,y,INSERT_VALUES,SCATTER_REVERSE);
1128:     break;
1129:   case PC_FIELDSPLIT_SCHUR_FACT_LOWER:
1130:     /* [A00 0; A10 S], suitable for left preconditioning */
1131:     VecScatterBegin(ilinkA->sctx,x,ilinkA->x,INSERT_VALUES,SCATTER_FORWARD);
1132:     VecScatterEnd(ilinkA->sctx,x,ilinkA->x,INSERT_VALUES,SCATTER_FORWARD);
1133:     PetscLogEventBegin(ilinkA->event,kspA,ilinkA->x,ilinkA->y,NULL);
1134:     KSPSolve(kspA,ilinkA->x,ilinkA->y);
1135:     KSPCheckSolve(kspA,pc,ilinkA->y);
1136:     PetscLogEventEnd(ilinkA->event,kspA,ilinkA->x,ilinkA->y,NULL);
1137:     MatMult(jac->C,ilinkA->y,ilinkD->x);
1138:     VecScale(ilinkD->x,-1.);
1139:     VecScatterBegin(ilinkD->sctx,x,ilinkD->x,ADD_VALUES,SCATTER_FORWARD);
1140:     VecScatterBegin(ilinkA->sctx,ilinkA->y,y,INSERT_VALUES,SCATTER_REVERSE);
1141:     VecScatterEnd(ilinkD->sctx,x,ilinkD->x,ADD_VALUES,SCATTER_FORWARD);
1142:     PetscLogEventBegin(KSP_Solve_FS_S,jac->kspschur,ilinkD->x,ilinkD->y,NULL);
1143:     KSPSolve(jac->kspschur,ilinkD->x,ilinkD->y);
1144:     KSPCheckSolve(jac->kspschur,pc,ilinkD->y);
1145:     PetscLogEventEnd(KSP_Solve_FS_S,jac->kspschur,ilinkD->x,ilinkD->y,NULL);
1146:     VecScatterEnd(ilinkA->sctx,ilinkA->y,y,INSERT_VALUES,SCATTER_REVERSE);
1147:     VecScatterBegin(ilinkD->sctx,ilinkD->y,y,INSERT_VALUES,SCATTER_REVERSE);
1148:     VecScatterEnd(ilinkD->sctx,ilinkD->y,y,INSERT_VALUES,SCATTER_REVERSE);
1149:     break;
1150:   case PC_FIELDSPLIT_SCHUR_FACT_UPPER:
1151:     /* [A00 A01; 0 S], suitable for right preconditioning */
1152:     VecScatterBegin(ilinkD->sctx,x,ilinkD->x,INSERT_VALUES,SCATTER_FORWARD);
1153:     VecScatterEnd(ilinkD->sctx,x,ilinkD->x,INSERT_VALUES,SCATTER_FORWARD);
1154:     PetscLogEventBegin(KSP_Solve_FS_S,jac->kspschur,ilinkD->x,ilinkD->y,NULL);
1155:     KSPSolve(jac->kspschur,ilinkD->x,ilinkD->y);
1156:     KSPCheckSolve(jac->kspschur,pc,ilinkD->y);
1157:     PetscLogEventEnd(KSP_Solve_FS_S,jac->kspschur,ilinkD->x,ilinkD->y,NULL);    MatMult(jac->B,ilinkD->y,ilinkA->x);
1158:     VecScale(ilinkA->x,-1.);
1159:     VecScatterBegin(ilinkA->sctx,x,ilinkA->x,ADD_VALUES,SCATTER_FORWARD);
1160:     VecScatterBegin(ilinkD->sctx,ilinkD->y,y,INSERT_VALUES,SCATTER_REVERSE);
1161:     VecScatterEnd(ilinkA->sctx,x,ilinkA->x,ADD_VALUES,SCATTER_FORWARD);
1162:     PetscLogEventBegin(ilinkA->event,kspA,ilinkA->x,ilinkA->y,NULL);
1163:     KSPSolve(kspA,ilinkA->x,ilinkA->y);
1164:     KSPCheckSolve(kspA,pc,ilinkA->y);
1165:     PetscLogEventEnd(ilinkA->event,kspA,ilinkA->x,ilinkA->y,NULL);
1166:     VecScatterEnd(ilinkD->sctx,ilinkD->y,y,INSERT_VALUES,SCATTER_REVERSE);
1167:     VecScatterBegin(ilinkA->sctx,ilinkA->y,y,INSERT_VALUES,SCATTER_REVERSE);
1168:     VecScatterEnd(ilinkA->sctx,ilinkA->y,y,INSERT_VALUES,SCATTER_REVERSE);
1169:     break;
1170:   case PC_FIELDSPLIT_SCHUR_FACT_FULL:
1171:     /* [1 0; A10 A00^{-1} 1] [A00 0; 0 S] [1 A00^{-1}A01; 0 1] */
1172:     VecScatterBegin(ilinkA->sctx,x,ilinkA->x,INSERT_VALUES,SCATTER_FORWARD);
1173:     VecScatterEnd(ilinkA->sctx,x,ilinkA->x,INSERT_VALUES,SCATTER_FORWARD);
1174:     PetscLogEventBegin(KSP_Solve_FS_L,kspLower,ilinkA->x,ilinkA->y,NULL);
1175:     KSPSolve(kspLower,ilinkA->x,ilinkA->y);
1176:     KSPCheckSolve(kspLower,pc,ilinkA->y);
1177:     PetscLogEventEnd(KSP_Solve_FS_L,kspLower,ilinkA->x,ilinkA->y,NULL);
1178:     MatMult(jac->C,ilinkA->y,ilinkD->x);
1179:     VecScale(ilinkD->x,-1.0);
1180:     VecScatterBegin(ilinkD->sctx,x,ilinkD->x,ADD_VALUES,SCATTER_FORWARD);
1181:     VecScatterEnd(ilinkD->sctx,x,ilinkD->x,ADD_VALUES,SCATTER_FORWARD);

1183:     PetscLogEventBegin(KSP_Solve_FS_S,jac->kspschur,ilinkD->x,ilinkD->y,NULL);
1184:     KSPSolve(jac->kspschur,ilinkD->x,ilinkD->y);
1185:     KSPCheckSolve(jac->kspschur,pc,ilinkD->y);
1186:     PetscLogEventEnd(KSP_Solve_FS_S,jac->kspschur,ilinkD->x,ilinkD->y,NULL);
1187:     VecScatterBegin(ilinkD->sctx,ilinkD->y,y,INSERT_VALUES,SCATTER_REVERSE);

1189:     if (kspUpper == kspA) {
1190:       MatMult(jac->B,ilinkD->y,ilinkA->y);
1191:       VecAXPY(ilinkA->x,-1.0,ilinkA->y);
1192:       PetscLogEventBegin(ilinkA->event,kspA,ilinkA->x,ilinkA->y,NULL);
1193:       KSPSolve(kspA,ilinkA->x,ilinkA->y);
1194:       KSPCheckSolve(kspA,pc,ilinkA->y);
1195:       PetscLogEventEnd(ilinkA->event,kspA,ilinkA->x,ilinkA->y,NULL);
1196:     } else {
1197:       PetscLogEventBegin(ilinkA->event,kspA,ilinkA->x,ilinkA->y,NULL);
1198:       KSPSolve(kspA,ilinkA->x,ilinkA->y);
1199:       KSPCheckSolve(kspA,pc,ilinkA->y);
1200:       MatMult(jac->B,ilinkD->y,ilinkA->x);
1201:       PetscLogEventBegin(KSP_Solve_FS_U,kspUpper,ilinkA->x,ilinkA->z,NULL);
1202:       KSPSolve(kspUpper,ilinkA->x,ilinkA->z);
1203:       KSPCheckSolve(kspUpper,pc,ilinkA->z);
1204:       PetscLogEventEnd(KSP_Solve_FS_U,kspUpper,ilinkA->x,ilinkA->z,NULL);
1205:       VecAXPY(ilinkA->y,-1.0,ilinkA->z);
1206:     }
1207:     VecScatterEnd(ilinkD->sctx,ilinkD->y,y,INSERT_VALUES,SCATTER_REVERSE);
1208:     VecScatterBegin(ilinkA->sctx,ilinkA->y,y,INSERT_VALUES,SCATTER_REVERSE);
1209:     VecScatterEnd(ilinkA->sctx,ilinkA->y,y,INSERT_VALUES,SCATTER_REVERSE);
1210:   }
1211:   return(0);
1212: }

1214: static PetscErrorCode PCApply_FieldSplit(PC pc,Vec x,Vec y)
1215: {
1216:   PC_FieldSplit      *jac = (PC_FieldSplit*)pc->data;
1217:   PetscErrorCode     ierr;
1218:   PC_FieldSplitLink  ilink = jac->head;
1219:   PetscInt           cnt,bs;

1222:   if (jac->type == PC_COMPOSITE_ADDITIVE) {
1223:     if (jac->defaultsplit) {
1224:       VecGetBlockSize(x,&bs);
1225:       if (jac->bs > 0 && bs != jac->bs) SETERRQ2(PetscObjectComm((PetscObject)pc),PETSC_ERR_ARG_WRONGSTATE,"Blocksize of x vector %D does not match fieldsplit blocksize %D",bs,jac->bs);
1226:       VecGetBlockSize(y,&bs);
1227:       if (jac->bs > 0 && bs != jac->bs) SETERRQ2(PetscObjectComm((PetscObject)pc),PETSC_ERR_ARG_WRONGSTATE,"Blocksize of y vector %D does not match fieldsplit blocksize %D",bs,jac->bs);
1228:       VecStrideGatherAll(x,jac->x,INSERT_VALUES);
1229:       while (ilink) {
1230:         PetscLogEventBegin(ilink->event,ilink->ksp,ilink->x,ilink->y,NULL);
1231:         KSPSolve(ilink->ksp,ilink->x,ilink->y);
1232:         KSPCheckSolve(ilink->ksp,pc,ilink->y);
1233:         PetscLogEventEnd(ilink->event,ilink->ksp,ilink->x,ilink->y,NULL);
1234:         ilink = ilink->next;
1235:       }
1236:       VecStrideScatterAll(jac->y,y,INSERT_VALUES);
1237:     } else {
1238:       VecSet(y,0.0);
1239:       while (ilink) {
1240:         FieldSplitSplitSolveAdd(ilink,x,y);
1241:         ilink = ilink->next;
1242:       }
1243:     }
1244:   } else if (jac->type == PC_COMPOSITE_MULTIPLICATIVE && jac->nsplits == 2) {
1245:     VecSet(y,0.0);
1246:     /* solve on first block for first block variables */
1247:     VecScatterBegin(ilink->sctx,x,ilink->x,INSERT_VALUES,SCATTER_FORWARD);
1248:     VecScatterEnd(ilink->sctx,x,ilink->x,INSERT_VALUES,SCATTER_FORWARD);
1249:     PetscLogEventBegin(ilink->event,ilink->ksp,ilink->x,ilink->y,NULL);
1250:     KSPSolve(ilink->ksp,ilink->x,ilink->y);
1251:     KSPCheckSolve(ilink->ksp,pc,ilink->y);
1252:     PetscLogEventEnd(ilink->event,ilink->ksp,ilink->x,ilink->y,NULL);
1253:     VecScatterBegin(ilink->sctx,ilink->y,y,ADD_VALUES,SCATTER_REVERSE);
1254:     VecScatterEnd(ilink->sctx,ilink->y,y,ADD_VALUES,SCATTER_REVERSE);

1256:     /* compute the residual only onto second block variables using first block variables */
1257:     MatMult(jac->Afield[1],ilink->y,ilink->next->x);
1258:     ilink = ilink->next;
1259:     VecScale(ilink->x,-1.0);
1260:     VecScatterBegin(ilink->sctx,x,ilink->x,ADD_VALUES,SCATTER_FORWARD);
1261:     VecScatterEnd(ilink->sctx,x,ilink->x,ADD_VALUES,SCATTER_FORWARD);

1263:     /* solve on second block variables */
1264:     PetscLogEventBegin(ilink->event,ilink->ksp,ilink->x,ilink->y,NULL);
1265:     KSPSolve(ilink->ksp,ilink->x,ilink->y);
1266:     KSPCheckSolve(ilink->ksp,pc,ilink->y);
1267:     PetscLogEventEnd(ilink->event,ilink->ksp,ilink->x,ilink->y,NULL);
1268:     VecScatterBegin(ilink->sctx,ilink->y,y,ADD_VALUES,SCATTER_REVERSE);
1269:     VecScatterEnd(ilink->sctx,ilink->y,y,ADD_VALUES,SCATTER_REVERSE);
1270:   } else if (jac->type == PC_COMPOSITE_MULTIPLICATIVE || jac->type == PC_COMPOSITE_SYMMETRIC_MULTIPLICATIVE) {
1271:     if (!jac->w1) {
1272:       VecDuplicate(x,&jac->w1);
1273:       VecDuplicate(x,&jac->w2);
1274:     }
1275:     VecSet(y,0.0);
1276:     FieldSplitSplitSolveAdd(ilink,x,y);
1277:     cnt  = 1;
1278:     while (ilink->next) {
1279:       ilink = ilink->next;
1280:       /* compute the residual only over the part of the vector needed */
1281:       MatMult(jac->Afield[cnt++],y,ilink->x);
1282:       VecScale(ilink->x,-1.0);
1283:       VecScatterBegin(ilink->sctx,x,ilink->x,ADD_VALUES,SCATTER_FORWARD);
1284:       VecScatterEnd(ilink->sctx,x,ilink->x,ADD_VALUES,SCATTER_FORWARD);
1285:       PetscLogEventBegin(ilink->event,ilink->ksp,ilink->x,ilink->y,NULL);
1286:       KSPSolve(ilink->ksp,ilink->x,ilink->y);
1287:       KSPCheckSolve(ilink->ksp,pc,ilink->y);
1288:       PetscLogEventEnd(ilink->event,ilink->ksp,ilink->x,ilink->y,NULL);
1289:       VecScatterBegin(ilink->sctx,ilink->y,y,ADD_VALUES,SCATTER_REVERSE);
1290:       VecScatterEnd(ilink->sctx,ilink->y,y,ADD_VALUES,SCATTER_REVERSE);
1291:     }
1292:     if (jac->type == PC_COMPOSITE_SYMMETRIC_MULTIPLICATIVE) {
1293:       cnt -= 2;
1294:       while (ilink->previous) {
1295:         ilink = ilink->previous;
1296:         /* compute the residual only over the part of the vector needed */
1297:         MatMult(jac->Afield[cnt--],y,ilink->x);
1298:         VecScale(ilink->x,-1.0);
1299:         VecScatterBegin(ilink->sctx,x,ilink->x,ADD_VALUES,SCATTER_FORWARD);
1300:         VecScatterEnd(ilink->sctx,x,ilink->x,ADD_VALUES,SCATTER_FORWARD);
1301:         PetscLogEventBegin(ilink->event,ilink->ksp,ilink->x,ilink->y,NULL);
1302:         KSPSolve(ilink->ksp,ilink->x,ilink->y);
1303:         KSPCheckSolve(ilink->ksp,pc,ilink->y);
1304:         PetscLogEventEnd(ilink->event,ilink->ksp,ilink->x,ilink->y,NULL);
1305:         VecScatterBegin(ilink->sctx,ilink->y,y,ADD_VALUES,SCATTER_REVERSE);
1306:         VecScatterEnd(ilink->sctx,ilink->y,y,ADD_VALUES,SCATTER_REVERSE);
1307:       }
1308:     }
1309:   } else SETERRQ1(PetscObjectComm((PetscObject)pc),PETSC_ERR_SUP,"Unsupported or unknown composition",(int) jac->type);
1310:   return(0);
1311: }


1314: static PetscErrorCode PCApply_FieldSplit_GKB(PC pc,Vec x,Vec y)
1315: {
1316:   PC_FieldSplit      *jac = (PC_FieldSplit*)pc->data;
1317:   PetscErrorCode     ierr;
1318:   PC_FieldSplitLink  ilinkA = jac->head,ilinkD = ilinkA->next;
1319:   KSP                ksp = ilinkA->ksp;
1320:   Vec                u,v,Hu,d,work1,work2;
1321:   PetscScalar        alpha,z,nrmz2,*vecz;
1322:   PetscReal          lowbnd,nu,beta;
1323:   PetscInt           j,iterGKB;

1326:   VecScatterBegin(ilinkA->sctx,x,ilinkA->x,INSERT_VALUES,SCATTER_FORWARD);
1327:   VecScatterBegin(ilinkD->sctx,x,ilinkD->x,INSERT_VALUES,SCATTER_FORWARD);
1328:   VecScatterEnd(ilinkA->sctx,x,ilinkA->x,INSERT_VALUES,SCATTER_FORWARD);
1329:   VecScatterEnd(ilinkD->sctx,x,ilinkD->x,INSERT_VALUES,SCATTER_FORWARD);

1331:   u     = jac->u;
1332:   v     = jac->v;
1333:   Hu    = jac->Hu;
1334:   d     = jac->d;
1335:   work1 = jac->w1;
1336:   work2 = jac->w2;
1337:   vecz  = jac->vecz;

1339:   /* Change RHS to comply with matrix regularization H = A + nu*B*B' */
1340:   /* Add q = q + nu*B*b */
1341:   if (jac->gkbnu) {
1342:     nu = jac->gkbnu;
1343:     VecScale(ilinkD->x,jac->gkbnu);
1344:     MatMultAdd(jac->B,ilinkD->x,ilinkA->x,ilinkA->x);            /* q = q + nu*B*b */
1345:   } else {
1346:     /* Situation when no augmented Lagrangian is used. Then we set inner  */
1347:     /* matrix N = I in [Ar13], and thus nu = 1.                           */
1348:     nu = 1;
1349:   }

1351:   /* Transform rhs from [q,tilde{b}] to [0,b] */
1352:   PetscLogEventBegin(ilinkA->event,ksp,ilinkA->x,ilinkA->y,NULL);
1353:   KSPSolve(ksp,ilinkA->x,ilinkA->y);
1354:   KSPCheckSolve(ksp,pc,ilinkA->y);
1355:   PetscLogEventEnd(ilinkA->event,ksp,ilinkA->x,ilinkA->y,NULL);
1356:   MatMultHermitianTranspose(jac->B,ilinkA->y,work1);
1357:   VecAXPBY(work1,1.0/nu,-1.0,ilinkD->x);            /* c = b - B'*x        */

1359:   /* First step of algorithm */
1360:   VecNorm(work1,NORM_2,&beta);                   /* beta = sqrt(nu*c'*c)*/
1361:   KSPCheckDot(ksp,beta);
1362:   beta  = PetscSqrtScalar(nu)*beta;
1363:   VecAXPBY(v,nu/beta,0.0,work1);                   /* v = nu/beta *c      */
1364:   MatMult(jac->B,v,work2);                       /* u = H^{-1}*B*v      */
1365:   PetscLogEventBegin(ilinkA->event,ksp,work2,u,NULL);
1366:   KSPSolve(ksp,work2,u);
1367:   KSPCheckSolve(ksp,pc,u);
1368:   PetscLogEventEnd(ilinkA->event,ksp,work2,u,NULL);
1369:   MatMult(jac->H,u,Hu);                          /* alpha = u'*H*u      */
1370:   VecDot(Hu,u,&alpha);
1371:   KSPCheckDot(ksp,alpha);
1372:   if (PetscRealPart(alpha) <= 0.0) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_NOT_CONVERGED,"GKB preconditioner diverged, H is not positive definite");
1373:   alpha = PetscSqrtScalar(PetscAbsScalar(alpha));
1374:   VecScale(u,1.0/alpha);
1375:   VecAXPBY(d,1.0/alpha,0.0,v);                       /* v = nu/beta *c      */

1377:   z = beta/alpha;
1378:   vecz[1] = z;

1380:   /* Computation of first iterate x(1) and p(1) */
1381:   VecAXPY(ilinkA->y,z,u);
1382:   VecCopy(d,ilinkD->y);
1383:   VecScale(ilinkD->y,-z);

1385:   iterGKB = 1; lowbnd = 2*jac->gkbtol;
1386:   if (jac->gkbmonitor) {
1387:       PetscViewerASCIIPrintf(jac->gkbviewer,"%3D GKB Lower bound estimate %14.12e\n",iterGKB,lowbnd);
1388:   }

1390:   while (iterGKB < jac->gkbmaxit && lowbnd > jac->gkbtol) {
1391:     iterGKB += 1;
1392:     MatMultHermitianTranspose(jac->B,u,work1); /* v <- nu*(B'*u-alpha/nu*v) */
1393:     VecAXPBY(v,nu,-alpha,work1);
1394:     VecNorm(v,NORM_2,&beta);                   /* beta = sqrt(nu)*v'*v      */
1395:     beta  = beta/PetscSqrtScalar(nu);
1396:     VecScale(v,1.0/beta);
1397:     MatMult(jac->B,v,work2);                  /* u <- H^{-1}*(B*v-beta*H*u) */
1398:     MatMult(jac->H,u,Hu);
1399:     VecAXPY(work2,-beta,Hu);
1400:     PetscLogEventBegin(ilinkA->event,ksp,work2,u,NULL);
1401:     KSPSolve(ksp,work2,u);
1402:     KSPCheckSolve(ksp,pc,u);
1403:     PetscLogEventEnd(ilinkA->event,ksp,work2,u,NULL);
1404:     MatMult(jac->H,u,Hu);                      /* alpha = u'*H*u            */
1405:     VecDot(Hu,u,&alpha);
1406:     KSPCheckDot(ksp,alpha);
1407:     if (PetscRealPart(alpha) <= 0.0) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_NOT_CONVERGED,"GKB preconditioner diverged, H is not positive definite");
1408:     alpha = PetscSqrtScalar(PetscAbsScalar(alpha));
1409:     VecScale(u,1.0/alpha);

1411:     z = -beta/alpha*z;                                            /* z <- beta/alpha*z     */
1412:     vecz[0] = z;

1414:     /* Computation of new iterate x(i+1) and p(i+1) */
1415:     VecAXPBY(d,1.0/alpha,-beta/alpha,v);       /* d = (v-beta*d)/alpha */
1416:     VecAXPY(ilinkA->y,z,u);                  /* r = r + z*u          */
1417:     VecAXPY(ilinkD->y,-z,d);                 /* p = p - z*d          */
1418:     MatMult(jac->H,ilinkA->y,Hu);            /* ||u||_H = u'*H*u     */
1419:     VecDot(Hu,ilinkA->y,&nrmz2);

1421:     /* Compute Lower Bound estimate */
1422:     if (iterGKB > jac->gkbdelay) {
1423:       lowbnd = 0.0;
1424:       for (j=0; j<jac->gkbdelay; j++) {
1425:         lowbnd += PetscAbsScalar(vecz[j]*vecz[j]);
1426:       }
1427:       lowbnd = PetscSqrtScalar(lowbnd/PetscAbsScalar(nrmz2));
1428:     }

1430:     for (j=0; j<jac->gkbdelay-1; j++) {
1431:       vecz[jac->gkbdelay-j-1] = vecz[jac->gkbdelay-j-2];
1432:     }
1433:     if (jac->gkbmonitor) {
1434:       PetscViewerASCIIPrintf(jac->gkbviewer,"%3D GKB Lower bound estimate %14.12e\n",iterGKB,lowbnd);
1435:     }
1436:   }

1438:   VecScatterBegin(ilinkA->sctx,ilinkA->y,y,INSERT_VALUES,SCATTER_REVERSE);
1439:   VecScatterEnd(ilinkA->sctx,ilinkA->y,y,INSERT_VALUES,SCATTER_REVERSE);
1440:   VecScatterBegin(ilinkD->sctx,ilinkD->y,y,INSERT_VALUES,SCATTER_REVERSE);
1441:   VecScatterEnd(ilinkD->sctx,ilinkD->y,y,INSERT_VALUES,SCATTER_REVERSE);

1443:   return(0);
1444: }


1447: #define FieldSplitSplitSolveAddTranspose(ilink,xx,yy) \
1448:   (VecScatterBegin(ilink->sctx,xx,ilink->y,INSERT_VALUES,SCATTER_FORWARD) || \
1449:    VecScatterEnd(ilink->sctx,xx,ilink->y,INSERT_VALUES,SCATTER_FORWARD) || \
1450:    PetscLogEventBegin(ilink->event,ilink->ksp,ilink->y,ilink->x,NULL) || \
1451:    KSPSolveTranspose(ilink->ksp,ilink->y,ilink->x) ||                  \
1452:    KSPCheckSolve(ilink->ksp,pc,ilink->x) || \
1453:    PetscLogEventEnd(ilink->event,ilink->ksp,ilink->y,ilink->x,NULL) ||   \
1454:    VecScatterBegin(ilink->sctx,ilink->x,yy,ADD_VALUES,SCATTER_REVERSE) || \
1455:    VecScatterEnd(ilink->sctx,ilink->x,yy,ADD_VALUES,SCATTER_REVERSE))

1457: static PetscErrorCode PCApplyTranspose_FieldSplit(PC pc,Vec x,Vec y)
1458: {
1459:   PC_FieldSplit      *jac = (PC_FieldSplit*)pc->data;
1460:   PetscErrorCode     ierr;
1461:   PC_FieldSplitLink  ilink = jac->head;
1462:   PetscInt           bs;

1465:   if (jac->type == PC_COMPOSITE_ADDITIVE) {
1466:     if (jac->defaultsplit) {
1467:       VecGetBlockSize(x,&bs);
1468:       if (jac->bs > 0 && bs != jac->bs) SETERRQ2(PetscObjectComm((PetscObject)pc),PETSC_ERR_ARG_WRONGSTATE,"Blocksize of x vector %D does not match fieldsplit blocksize %D",bs,jac->bs);
1469:       VecGetBlockSize(y,&bs);
1470:       if (jac->bs > 0 && bs != jac->bs) SETERRQ2(PetscObjectComm((PetscObject)pc),PETSC_ERR_ARG_WRONGSTATE,"Blocksize of y vector %D does not match fieldsplit blocksize %D",bs,jac->bs);
1471:       VecStrideGatherAll(x,jac->x,INSERT_VALUES);
1472:       while (ilink) {
1473:         PetscLogEventBegin(ilink->event,ilink->ksp,ilink->x,ilink->y,NULL);
1474:         KSPSolveTranspose(ilink->ksp,ilink->x,ilink->y);
1475:         KSPCheckSolve(ilink->ksp,pc,ilink->y);
1476:         PetscLogEventEnd(ilink->event,ilink->ksp,ilink->x,ilink->y,NULL);
1477:         ilink = ilink->next;
1478:       }
1479:       VecStrideScatterAll(jac->y,y,INSERT_VALUES);
1480:     } else {
1481:       VecSet(y,0.0);
1482:       while (ilink) {
1483:         FieldSplitSplitSolveAddTranspose(ilink,x,y);
1484:         ilink = ilink->next;
1485:       }
1486:     }
1487:   } else {
1488:     if (!jac->w1) {
1489:       VecDuplicate(x,&jac->w1);
1490:       VecDuplicate(x,&jac->w2);
1491:     }
1492:     VecSet(y,0.0);
1493:     if (jac->type == PC_COMPOSITE_SYMMETRIC_MULTIPLICATIVE) {
1494:       FieldSplitSplitSolveAddTranspose(ilink,x,y);
1495:       while (ilink->next) {
1496:         ilink = ilink->next;
1497:         MatMultTranspose(pc->mat,y,jac->w1);
1498:         VecWAXPY(jac->w2,-1.0,jac->w1,x);
1499:         FieldSplitSplitSolveAddTranspose(ilink,jac->w2,y);
1500:       }
1501:       while (ilink->previous) {
1502:         ilink = ilink->previous;
1503:         MatMultTranspose(pc->mat,y,jac->w1);
1504:         VecWAXPY(jac->w2,-1.0,jac->w1,x);
1505:         FieldSplitSplitSolveAddTranspose(ilink,jac->w2,y);
1506:       }
1507:     } else {
1508:       while (ilink->next) {   /* get to last entry in linked list */
1509:         ilink = ilink->next;
1510:       }
1511:       FieldSplitSplitSolveAddTranspose(ilink,x,y);
1512:       while (ilink->previous) {
1513:         ilink = ilink->previous;
1514:         MatMultTranspose(pc->mat,y,jac->w1);
1515:         VecWAXPY(jac->w2,-1.0,jac->w1,x);
1516:         FieldSplitSplitSolveAddTranspose(ilink,jac->w2,y);
1517:       }
1518:     }
1519:   }
1520:   return(0);
1521: }

1523: static PetscErrorCode PCReset_FieldSplit(PC pc)
1524: {
1525:   PC_FieldSplit     *jac = (PC_FieldSplit*)pc->data;
1526:   PetscErrorCode    ierr;
1527:   PC_FieldSplitLink ilink = jac->head,next;

1530:   while (ilink) {
1531:     KSPDestroy(&ilink->ksp);
1532:     VecDestroy(&ilink->x);
1533:     VecDestroy(&ilink->y);
1534:     VecDestroy(&ilink->z);
1535:     VecScatterDestroy(&ilink->sctx);
1536:     ISDestroy(&ilink->is);
1537:     ISDestroy(&ilink->is_col);
1538:     PetscFree(ilink->splitname);
1539:     PetscFree(ilink->fields);
1540:     PetscFree(ilink->fields_col);
1541:     next  = ilink->next;
1542:     PetscFree(ilink);
1543:     ilink = next;
1544:   }
1545:   jac->head = NULL;
1546:   PetscFree2(jac->x,jac->y);
1547:   if (jac->mat && jac->mat != jac->pmat) {
1548:     MatDestroyMatrices(jac->nsplits,&jac->mat);
1549:   } else if (jac->mat) {
1550:     jac->mat = NULL;
1551:   }
1552:   if (jac->pmat) {MatDestroyMatrices(jac->nsplits,&jac->pmat);}
1553:   if (jac->Afield) {MatDestroyMatrices(jac->nsplits,&jac->Afield);}
1554:   jac->nsplits = 0;
1555:   VecDestroy(&jac->w1);
1556:   VecDestroy(&jac->w2);
1557:   MatDestroy(&jac->schur);
1558:   MatDestroy(&jac->schurp);
1559:   MatDestroy(&jac->schur_user);
1560:   KSPDestroy(&jac->kspschur);
1561:   KSPDestroy(&jac->kspupper);
1562:   MatDestroy(&jac->B);
1563:   MatDestroy(&jac->C);
1564:   MatDestroy(&jac->H);
1565:   VecDestroy(&jac->u);
1566:   VecDestroy(&jac->v);
1567:   VecDestroy(&jac->Hu);
1568:   VecDestroy(&jac->d);
1569:   PetscFree(jac->vecz);
1570:   PetscViewerDestroy(&jac->gkbviewer);
1571:   jac->isrestrict = PETSC_FALSE;
1572:   return(0);
1573: }

1575: static PetscErrorCode PCDestroy_FieldSplit(PC pc)
1576: {
1577:   PetscErrorCode    ierr;

1580:   PCReset_FieldSplit(pc);
1581:   PetscFree(pc->data);
1582:   PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitSchurGetSubKSP_C",NULL);
1583:   PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitGetSubKSP_C",NULL);
1584:   PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitSetFields_C",NULL);
1585:   PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitSetIS_C",NULL);
1586:   PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitSetType_C",NULL);
1587:   PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitSetBlockSize_C",NULL);
1588:   PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitSetSchurPre_C",NULL);
1589:   PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitGetSchurPre_C",NULL);
1590:   PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitSetSchurFactType_C",NULL);
1591:   PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitRestrictIS_C",NULL);
1592:   return(0);
1593: }

1595: static PetscErrorCode PCSetFromOptions_FieldSplit(PetscOptionItems *PetscOptionsObject,PC pc)
1596: {
1597:   PetscErrorCode  ierr;
1598:   PetscInt        bs;
1599:   PetscBool       flg;
1600:   PC_FieldSplit   *jac = (PC_FieldSplit*)pc->data;
1601:   PCCompositeType ctype;

1604:   PetscOptionsHead(PetscOptionsObject,"FieldSplit options");
1605:   PetscOptionsBool("-pc_fieldsplit_dm_splits","Whether to use DMCreateFieldDecomposition() for splits","PCFieldSplitSetDMSplits",jac->dm_splits,&jac->dm_splits,NULL);
1606:   PetscOptionsInt("-pc_fieldsplit_block_size","Blocksize that defines number of fields","PCFieldSplitSetBlockSize",jac->bs,&bs,&flg);
1607:   if (flg) {
1608:     PCFieldSplitSetBlockSize(pc,bs);
1609:   }
1610:   jac->diag_use_amat = pc->useAmat;
1611:   PetscOptionsBool("-pc_fieldsplit_diag_use_amat","Use Amat (not Pmat) to extract diagonal fieldsplit blocks", "PCFieldSplitSetDiagUseAmat",jac->diag_use_amat,&jac->diag_use_amat,NULL);
1612:   jac->offdiag_use_amat = pc->useAmat;
1613:   PetscOptionsBool("-pc_fieldsplit_off_diag_use_amat","Use Amat (not Pmat) to extract off-diagonal fieldsplit blocks", "PCFieldSplitSetOffDiagUseAmat",jac->offdiag_use_amat,&jac->offdiag_use_amat,NULL);
1614:   PetscOptionsBool("-pc_fieldsplit_detect_saddle_point","Form 2-way split by detecting zero diagonal entries", "PCFieldSplitSetDetectSaddlePoint",jac->detect,&jac->detect,NULL);
1615:   PCFieldSplitSetDetectSaddlePoint(pc,jac->detect); /* Sets split type and Schur PC type */
1616:   PetscOptionsEnum("-pc_fieldsplit_type","Type of composition","PCFieldSplitSetType",PCCompositeTypes,(PetscEnum)jac->type,(PetscEnum*)&ctype,&flg);
1617:   if (flg) {
1618:     PCFieldSplitSetType(pc,ctype);
1619:   }
1620:   /* Only setup fields once */
1621:   if ((jac->bs > 0) && (jac->nsplits == 0)) {
1622:     /* only allow user to set fields from command line if bs is already known.
1623:        otherwise user can set them in PCFieldSplitSetDefaults() */
1624:     PCFieldSplitSetRuntimeSplits_Private(pc);
1625:     if (jac->splitdefined) {PetscInfo(pc,"Splits defined using the options database\n");}
1626:   }
1627:   if (jac->type == PC_COMPOSITE_SCHUR) {
1628:     PetscOptionsGetEnum(((PetscObject)pc)->options,((PetscObject)pc)->prefix,"-pc_fieldsplit_schur_factorization_type",PCFieldSplitSchurFactTypes,(PetscEnum*)&jac->schurfactorization,&flg);
1629:     if (flg) {PetscInfo(pc,"Deprecated use of -pc_fieldsplit_schur_factorization_type\n");}
1630:     PetscOptionsEnum("-pc_fieldsplit_schur_fact_type","Which off-diagonal parts of the block factorization to use","PCFieldSplitSetSchurFactType",PCFieldSplitSchurFactTypes,(PetscEnum)jac->schurfactorization,(PetscEnum*)&jac->schurfactorization,NULL);
1631:     PetscOptionsEnum("-pc_fieldsplit_schur_precondition","How to build preconditioner for Schur complement","PCFieldSplitSetSchurPre",PCFieldSplitSchurPreTypes,(PetscEnum)jac->schurpre,(PetscEnum*)&jac->schurpre,NULL);
1632:     PetscOptionsScalar("-pc_fieldsplit_schur_scale","Scale Schur complement","PCFieldSplitSetSchurScale",jac->schurscale,&jac->schurscale,NULL);
1633:   } else if (jac->type == PC_COMPOSITE_GKB) {
1634:     PetscOptionsReal("-pc_fieldsplit_gkb_tol","The tolerance for the lower bound stopping criterion","PCFieldSplitGKBTol",jac->gkbtol,&jac->gkbtol,NULL);
1635:     PetscOptionsInt("-pc_fieldsplit_gkb_delay","The delay value for lower bound criterion","PCFieldSplitGKBDelay",jac->gkbdelay,&jac->gkbdelay,NULL);
1636:     PetscOptionsReal("-pc_fieldsplit_gkb_nu","Parameter in augmented Lagrangian approach","PCFieldSplitGKBNu",jac->gkbnu,&jac->gkbnu,NULL);
1637:     if (jac->gkbnu < 0) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"nu cannot be less than 0: value %f",jac->gkbnu);
1638:     PetscOptionsInt("-pc_fieldsplit_gkb_maxit","Maximum allowed number of iterations","PCFieldSplitGKBMaxit",jac->gkbmaxit,&jac->gkbmaxit,NULL);
1639:     PetscOptionsBool("-pc_fieldsplit_gkb_monitor","Prints number of GKB iterations and error","PCFieldSplitGKB",jac->gkbmonitor,&jac->gkbmonitor,NULL);
1640:   }
1641:   PetscOptionsTail();
1642:   return(0);
1643: }

1645: /*------------------------------------------------------------------------------------*/

1647: static PetscErrorCode  PCFieldSplitSetFields_FieldSplit(PC pc,const char splitname[],PetscInt n,const PetscInt *fields,const PetscInt *fields_col)
1648: {
1649:   PC_FieldSplit     *jac = (PC_FieldSplit*)pc->data;
1650:   PetscErrorCode    ierr;
1651:   PC_FieldSplitLink ilink,next = jac->head;
1652:   char              prefix[128];
1653:   PetscInt          i;

1656:   if (jac->splitdefined) {
1657:     PetscInfo1(pc,"Ignoring new split \"%s\" because the splits have already been defined\n",splitname);
1658:     return(0);
1659:   }
1660:   for (i=0; i<n; i++) {
1661:     if (fields[i] >= jac->bs) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Field %D requested but only %D exist",fields[i],jac->bs);
1662:     if (fields[i] < 0) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Negative field %D requested",fields[i]);
1663:   }
1664:   PetscNew(&ilink);
1665:   if (splitname) {
1666:     PetscStrallocpy(splitname,&ilink->splitname);
1667:   } else {
1668:     PetscMalloc1(3,&ilink->splitname);
1669:     PetscSNPrintf(ilink->splitname,2,"%s",jac->nsplits);
1670:   }
1671:   ilink->event = jac->nsplits < 5 ? KSP_Solve_FS_0 + jac->nsplits : KSP_Solve_FS_0 + 4; /* Any split great than 4 gets logged in the 4th split */
1672:   PetscMalloc1(n,&ilink->fields);
1673:   PetscArraycpy(ilink->fields,fields,n);
1674:   PetscMalloc1(n,&ilink->fields_col);
1675:   PetscArraycpy(ilink->fields_col,fields_col,n);

1677:   ilink->nfields = n;
1678:   ilink->next    = NULL;
1679:   KSPCreate(PetscObjectComm((PetscObject)pc),&ilink->ksp);
1680:   KSPSetErrorIfNotConverged(ilink->ksp,pc->erroriffailure);
1681:   PetscObjectIncrementTabLevel((PetscObject)ilink->ksp,(PetscObject)pc,1);
1682:   KSPSetType(ilink->ksp,KSPPREONLY);
1683:   PetscLogObjectParent((PetscObject)pc,(PetscObject)ilink->ksp);

1685:   PetscSNPrintf(prefix,sizeof(prefix),"%sfieldsplit_%s_",((PetscObject)pc)->prefix ? ((PetscObject)pc)->prefix : "",ilink->splitname);
1686:   KSPSetOptionsPrefix(ilink->ksp,prefix);

1688:   if (!next) {
1689:     jac->head       = ilink;
1690:     ilink->previous = NULL;
1691:   } else {
1692:     while (next->next) {
1693:       next = next->next;
1694:     }
1695:     next->next      = ilink;
1696:     ilink->previous = next;
1697:   }
1698:   jac->nsplits++;
1699:   return(0);
1700: }

1702: static PetscErrorCode  PCFieldSplitSchurGetSubKSP_FieldSplit(PC pc,PetscInt *n,KSP **subksp)
1703: {
1704:   PC_FieldSplit  *jac = (PC_FieldSplit*)pc->data;

1708:   *subksp = NULL;
1709:   if (n) *n = 0;
1710:   if (jac->type == PC_COMPOSITE_SCHUR) {
1711:     PetscInt nn;

1713:     if (!jac->schur) SETERRQ(PetscObjectComm((PetscObject)pc),PETSC_ERR_ARG_WRONGSTATE,"Must call KSPSetUp() or PCSetUp() before calling PCFieldSplitSchurGetSubKSP()");
1714:     if (jac->nsplits != 2) SETERRQ1(PetscObjectComm((PetscObject)pc),PETSC_ERR_PLIB,"Unexpected number of splits %D != 2",jac->nsplits);
1715:     nn   = jac->nsplits + (jac->kspupper != jac->head->ksp ? 1 : 0);
1716:     PetscMalloc1(nn,subksp);
1717:     (*subksp)[0] = jac->head->ksp;
1718:     (*subksp)[1] = jac->kspschur;
1719:     if (jac->kspupper != jac->head->ksp) (*subksp)[2] = jac->kspupper;
1720:     if (n) *n = nn;
1721:   }
1722:   return(0);
1723: }

1725: static PetscErrorCode  PCFieldSplitGetSubKSP_FieldSplit_Schur(PC pc,PetscInt *n,KSP **subksp)
1726: {
1727:   PC_FieldSplit  *jac = (PC_FieldSplit*)pc->data;

1731:   if (!jac->schur) SETERRQ(PetscObjectComm((PetscObject)pc),PETSC_ERR_ARG_WRONGSTATE,"Must call KSPSetUp() or PCSetUp() before calling PCFieldSplitGetSubKSP()");
1732:   PetscMalloc1(jac->nsplits,subksp);
1733:   MatSchurComplementGetKSP(jac->schur,*subksp);

1735:   (*subksp)[1] = jac->kspschur;
1736:   if (n) *n = jac->nsplits;
1737:   return(0);
1738: }

1740: static PetscErrorCode  PCFieldSplitGetSubKSP_FieldSplit(PC pc,PetscInt *n,KSP **subksp)
1741: {
1742:   PC_FieldSplit     *jac = (PC_FieldSplit*)pc->data;
1743:   PetscErrorCode    ierr;
1744:   PetscInt          cnt   = 0;
1745:   PC_FieldSplitLink ilink = jac->head;

1748:   PetscMalloc1(jac->nsplits,subksp);
1749:   while (ilink) {
1750:     (*subksp)[cnt++] = ilink->ksp;
1751:     ilink            = ilink->next;
1752:   }
1753:   if (cnt != jac->nsplits) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_PLIB,"Corrupt PCFIELDSPLIT object: number of splits in linked list %D does not match number in object %D",cnt,jac->nsplits);
1754:   if (n) *n = jac->nsplits;
1755:   return(0);
1756: }

1758: /*@C
1759:     PCFieldSplitRestrictIS - Restricts the fieldsplit ISs to be within a given IS.

1761:     Input Parameters:
1762: +   pc  - the preconditioner context
1763: -   is - the index set that defines the indices to which the fieldsplit is to be restricted

1765:     Level: advanced

1767: @*/
1768: PetscErrorCode  PCFieldSplitRestrictIS(PC pc,IS isy)
1769: {

1775:   PetscTryMethod(pc,"PCFieldSplitRestrictIS_C",(PC,IS),(pc,isy));
1776:   return(0);
1777: }


1780: static PetscErrorCode  PCFieldSplitRestrictIS_FieldSplit(PC pc, IS isy)
1781: {
1782:   PC_FieldSplit     *jac = (PC_FieldSplit*)pc->data;
1783:   PetscErrorCode    ierr;
1784:   PC_FieldSplitLink ilink = jac->head, next;
1785:   PetscInt          localsize,size,sizez,i;
1786:   const PetscInt    *ind, *indz;
1787:   PetscInt          *indc, *indcz;
1788:   PetscBool         flg;

1791:   ISGetLocalSize(isy,&localsize);
1792:   MPI_Scan(&localsize,&size,1,MPIU_INT,MPI_SUM,PetscObjectComm((PetscObject)isy));
1793:   size -= localsize;
1794:   while(ilink) {
1795:     IS isrl,isr;
1796:     PC subpc;
1797:     ISEmbed(ilink->is, isy, PETSC_TRUE, &isrl);
1798:     ISGetLocalSize(isrl,&localsize);
1799:     PetscMalloc1(localsize,&indc);
1800:     ISGetIndices(isrl,&ind);
1801:     PetscArraycpy(indc,ind,localsize);
1802:     ISRestoreIndices(isrl,&ind);
1803:     ISDestroy(&isrl);
1804:     for (i=0; i<localsize; i++) *(indc+i) += size;
1805:     ISCreateGeneral(PetscObjectComm((PetscObject)isy),localsize,indc,PETSC_OWN_POINTER,&isr);
1806:     PetscObjectReference((PetscObject)isr);
1807:     ISDestroy(&ilink->is);
1808:     ilink->is     = isr;
1809:     PetscObjectReference((PetscObject)isr);
1810:     ISDestroy(&ilink->is_col);
1811:     ilink->is_col = isr;
1812:     ISDestroy(&isr);
1813:     KSPGetPC(ilink->ksp, &subpc);
1814:     PetscObjectTypeCompare((PetscObject)subpc,PCFIELDSPLIT,&flg);
1815:     if(flg) {
1816:       IS iszl,isz;
1817:       MPI_Comm comm;
1818:       ISGetLocalSize(ilink->is,&localsize);
1819:       comm   = PetscObjectComm((PetscObject)ilink->is);
1820:       ISEmbed(isy, ilink->is, PETSC_TRUE, &iszl);
1821:       MPI_Scan(&localsize,&sizez,1,MPIU_INT,MPI_SUM,comm);
1822:       sizez -= localsize;
1823:       ISGetLocalSize(iszl,&localsize);
1824:       PetscMalloc1(localsize,&indcz);
1825:       ISGetIndices(iszl,&indz);
1826:       PetscArraycpy(indcz,indz,localsize);
1827:       ISRestoreIndices(iszl,&indz);
1828:       ISDestroy(&iszl);
1829:       for (i=0; i<localsize; i++) *(indcz+i) += sizez;
1830:       ISCreateGeneral(comm,localsize,indcz,PETSC_OWN_POINTER,&isz);
1831:       PCFieldSplitRestrictIS(subpc,isz);
1832:       ISDestroy(&isz);
1833:     }
1834:     next = ilink->next;
1835:     ilink = next;
1836:   }
1837:   jac->isrestrict = PETSC_TRUE;
1838:   return(0);
1839: }

1841: static PetscErrorCode  PCFieldSplitSetIS_FieldSplit(PC pc,const char splitname[],IS is)
1842: {
1843:   PC_FieldSplit     *jac = (PC_FieldSplit*)pc->data;
1844:   PetscErrorCode    ierr;
1845:   PC_FieldSplitLink ilink, next = jac->head;
1846:   char              prefix[128];

1849:   if (jac->splitdefined) {
1850:     PetscInfo1(pc,"Ignoring new split \"%s\" because the splits have already been defined\n",splitname);
1851:     return(0);
1852:   }
1853:   PetscNew(&ilink);
1854:   if (splitname) {
1855:     PetscStrallocpy(splitname,&ilink->splitname);
1856:   } else {
1857:     PetscMalloc1(8,&ilink->splitname);
1858:     PetscSNPrintf(ilink->splitname,7,"%D",jac->nsplits);
1859:   }
1860:   ilink->event  = jac->nsplits < 5 ? KSP_Solve_FS_0 + jac->nsplits : KSP_Solve_FS_0 + 4; /* Any split great than 4 gets logged in the 4th split */
1861:   PetscObjectReference((PetscObject)is);
1862:   ISDestroy(&ilink->is);
1863:   ilink->is     = is;
1864:   PetscObjectReference((PetscObject)is);
1865:   ISDestroy(&ilink->is_col);
1866:   ilink->is_col = is;
1867:   ilink->next   = NULL;
1868:   KSPCreate(PetscObjectComm((PetscObject)pc),&ilink->ksp);
1869:   KSPSetErrorIfNotConverged(ilink->ksp,pc->erroriffailure);
1870:   PetscObjectIncrementTabLevel((PetscObject)ilink->ksp,(PetscObject)pc,1);
1871:   KSPSetType(ilink->ksp,KSPPREONLY);
1872:   PetscLogObjectParent((PetscObject)pc,(PetscObject)ilink->ksp);

1874:   PetscSNPrintf(prefix,sizeof(prefix),"%sfieldsplit_%s_",((PetscObject)pc)->prefix ? ((PetscObject)pc)->prefix : "",ilink->splitname);
1875:   KSPSetOptionsPrefix(ilink->ksp,prefix);

1877:   if (!next) {
1878:     jac->head       = ilink;
1879:     ilink->previous = NULL;
1880:   } else {
1881:     while (next->next) {
1882:       next = next->next;
1883:     }
1884:     next->next      = ilink;
1885:     ilink->previous = next;
1886:   }
1887:   jac->nsplits++;
1888:   return(0);
1889: }

1891: /*@C
1892:     PCFieldSplitSetFields - Sets the fields for one particular split in the field split preconditioner

1894:     Logically Collective on PC

1896:     Input Parameters:
1897: +   pc  - the preconditioner context
1898: .   splitname - name of this split, if NULL the number of the split is used
1899: .   n - the number of fields in this split
1900: -   fields - the fields in this split

1902:     Level: intermediate

1904:     Notes:
1905:     Use PCFieldSplitSetIS() to set a completely general set of indices as a field.

1907:      The PCFieldSplitSetFields() is for defining fields as strided blocks. For example, if the block
1908:      size is three then one can define a field as 0, or 1 or 2 or 0,1 or 0,2 or 1,2 which mean
1909:      0xx3xx6xx9xx12 ... x1xx4xx7xx ... xx2xx5xx8xx.. 01x34x67x... 0x1x3x5x7.. x12x45x78x....
1910:      where the numbered entries indicate what is in the field.

1912:      This function is called once per split (it creates a new split each time).  Solve options
1913:      for this split will be available under the prefix -fieldsplit_SPLITNAME_.

1915:      Developer Note: This routine does not actually create the IS representing the split, that is delayed
1916:      until PCSetUp_FieldSplit(), because information about the vector/matrix layouts may not be
1917:      available when this routine is called.

1919: .seealso: PCFieldSplitGetSubKSP(), PCFIELDSPLIT, PCFieldSplitSetBlockSize(), PCFieldSplitSetIS()

1921: @*/
1922: PetscErrorCode  PCFieldSplitSetFields(PC pc,const char splitname[],PetscInt n,const PetscInt *fields,const PetscInt *fields_col)
1923: {

1929:   if (n < 1) SETERRQ2(PetscObjectComm((PetscObject)pc),PETSC_ERR_ARG_OUTOFRANGE,"Provided number of fields %D in split \"%s\" not positive",n,splitname);
1931:   PetscTryMethod(pc,"PCFieldSplitSetFields_C",(PC,const char[],PetscInt,const PetscInt*,const PetscInt*),(pc,splitname,n,fields,fields_col));
1932:   return(0);
1933: }

1935: /*@
1936:     PCFieldSplitSetDiagUseAmat - set flag indicating whether to extract diagonal blocks from Amat (rather than Pmat)

1938:     Logically Collective on PC

1940:     Input Parameters:
1941: +   pc  - the preconditioner object
1942: -   flg - boolean flag indicating whether or not to use Amat to extract the diagonal blocks from

1944:     Options Database:
1945: .     -pc_fieldsplit_diag_use_amat

1947:     Level: intermediate

1949: .seealso: PCFieldSplitGetDiagUseAmat(), PCFieldSplitSetOffDiagUseAmat(), PCFIELDSPLIT

1951: @*/
1952: PetscErrorCode  PCFieldSplitSetDiagUseAmat(PC pc,PetscBool flg)
1953: {
1954:   PC_FieldSplit  *jac = (PC_FieldSplit*)pc->data;
1955:   PetscBool      isfs;

1960:   PetscObjectTypeCompare((PetscObject)pc,PCFIELDSPLIT,&isfs);
1961:   if (!isfs) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"PC not of type %s",PCFIELDSPLIT);
1962:   jac->diag_use_amat = flg;
1963:   return(0);
1964: }

1966: /*@
1967:     PCFieldSplitGetDiagUseAmat - get the flag indicating whether to extract diagonal blocks from Amat (rather than Pmat)

1969:     Logically Collective on PC

1971:     Input Parameters:
1972: .   pc  - the preconditioner object

1974:     Output Parameters:
1975: .   flg - boolean flag indicating whether or not to use Amat to extract the diagonal blocks from


1978:     Level: intermediate

1980: .seealso: PCFieldSplitSetDiagUseAmat(), PCFieldSplitGetOffDiagUseAmat(), PCFIELDSPLIT

1982: @*/
1983: PetscErrorCode  PCFieldSplitGetDiagUseAmat(PC pc,PetscBool *flg)
1984: {
1985:   PC_FieldSplit  *jac = (PC_FieldSplit*)pc->data;
1986:   PetscBool      isfs;

1992:   PetscObjectTypeCompare((PetscObject)pc,PCFIELDSPLIT,&isfs);
1993:   if (!isfs) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"PC not of type %s",PCFIELDSPLIT);
1994:   *flg = jac->diag_use_amat;
1995:   return(0);
1996: }

1998: /*@
1999:     PCFieldSplitSetOffDiagUseAmat - set flag indicating whether to extract off-diagonal blocks from Amat (rather than Pmat)

2001:     Logically Collective on PC

2003:     Input Parameters:
2004: +   pc  - the preconditioner object
2005: -   flg - boolean flag indicating whether or not to use Amat to extract the off-diagonal blocks from

2007:     Options Database:
2008: .     -pc_fieldsplit_off_diag_use_amat

2010:     Level: intermediate

2012: .seealso: PCFieldSplitGetOffDiagUseAmat(), PCFieldSplitSetDiagUseAmat(), PCFIELDSPLIT

2014: @*/
2015: PetscErrorCode  PCFieldSplitSetOffDiagUseAmat(PC pc,PetscBool flg)
2016: {
2017:   PC_FieldSplit *jac = (PC_FieldSplit*)pc->data;
2018:   PetscBool      isfs;

2023:   PetscObjectTypeCompare((PetscObject)pc,PCFIELDSPLIT,&isfs);
2024:   if (!isfs) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"PC not of type %s",PCFIELDSPLIT);
2025:   jac->offdiag_use_amat = flg;
2026:   return(0);
2027: }

2029: /*@
2030:     PCFieldSplitGetOffDiagUseAmat - get the flag indicating whether to extract off-diagonal blocks from Amat (rather than Pmat)

2032:     Logically Collective on PC

2034:     Input Parameters:
2035: .   pc  - the preconditioner object

2037:     Output Parameters:
2038: .   flg - boolean flag indicating whether or not to use Amat to extract the off-diagonal blocks from


2041:     Level: intermediate

2043: .seealso: PCFieldSplitSetOffDiagUseAmat(), PCFieldSplitGetDiagUseAmat(), PCFIELDSPLIT

2045: @*/
2046: PetscErrorCode  PCFieldSplitGetOffDiagUseAmat(PC pc,PetscBool *flg)
2047: {
2048:   PC_FieldSplit  *jac = (PC_FieldSplit*)pc->data;
2049:   PetscBool      isfs;

2055:   PetscObjectTypeCompare((PetscObject)pc,PCFIELDSPLIT,&isfs);
2056:   if (!isfs) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"PC not of type %s",PCFIELDSPLIT);
2057:   *flg = jac->offdiag_use_amat;
2058:   return(0);
2059: }



2063: /*@C
2064:     PCFieldSplitSetIS - Sets the exact elements for field

2066:     Logically Collective on PC

2068:     Input Parameters:
2069: +   pc  - the preconditioner context
2070: .   splitname - name of this split, if NULL the number of the split is used
2071: -   is - the index set that defines the vector elements in this field


2074:     Notes:
2075:     Use PCFieldSplitSetFields(), for fields defined by strided types.

2077:     This function is called once per split (it creates a new split each time).  Solve options
2078:     for this split will be available under the prefix -fieldsplit_SPLITNAME_.

2080:     Level: intermediate

2082: .seealso: PCFieldSplitGetSubKSP(), PCFIELDSPLIT, PCFieldSplitSetBlockSize()

2084: @*/
2085: PetscErrorCode  PCFieldSplitSetIS(PC pc,const char splitname[],IS is)
2086: {

2093:   PetscTryMethod(pc,"PCFieldSplitSetIS_C",(PC,const char[],IS),(pc,splitname,is));
2094:   return(0);
2095: }

2097: /*@C
2098:     PCFieldSplitGetIS - Retrieves the elements for a field as an IS

2100:     Logically Collective on PC

2102:     Input Parameters:
2103: +   pc  - the preconditioner context
2104: -   splitname - name of this split

2106:     Output Parameter:
2107: -   is - the index set that defines the vector elements in this field, or NULL if the field is not found

2109:     Level: intermediate

2111: .seealso: PCFieldSplitGetSubKSP(), PCFIELDSPLIT, PCFieldSplitSetIS()

2113: @*/
2114: PetscErrorCode PCFieldSplitGetIS(PC pc,const char splitname[],IS *is)
2115: {

2122:   {
2123:     PC_FieldSplit     *jac  = (PC_FieldSplit*) pc->data;
2124:     PC_FieldSplitLink ilink = jac->head;
2125:     PetscBool         found;

2127:     *is = NULL;
2128:     while (ilink) {
2129:       PetscStrcmp(ilink->splitname, splitname, &found);
2130:       if (found) {
2131:         *is = ilink->is;
2132:         break;
2133:       }
2134:       ilink = ilink->next;
2135:     }
2136:   }
2137:   return(0);
2138: }

2140: /*@C
2141:     PCFieldSplitGetISByIndex - Retrieves the elements for a given index field as an IS

2143:     Logically Collective on PC

2145:     Input Parameters:
2146: +   pc  - the preconditioner context
2147: -   index - index of this split

2149:     Output Parameter:
2150: -   is - the index set that defines the vector elements in this field

2152:     Level: intermediate

2154: .seealso: PCFieldSplitGetSubKSP(), PCFIELDSPLIT, PCFieldSplitGetIS(), PCFieldSplitSetIS()

2156: @*/
2157: PetscErrorCode PCFieldSplitGetISByIndex(PC pc,PetscInt index,IS *is)
2158: {

2162:   if (index < 0) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Negative field %D requested",index);
2165:   {
2166:     PC_FieldSplit     *jac  = (PC_FieldSplit*) pc->data;
2167:     PC_FieldSplitLink ilink = jac->head;
2168:     PetscInt          i     = 0;
2169:     if (index >= jac->nsplits) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Field %D requested but only %D exist",index,jac->nsplits);

2171:     while (i < index) {
2172:       ilink = ilink->next;
2173:       ++i;
2174:     }
2175:     PCFieldSplitGetIS(pc,ilink->splitname,is);
2176:   }
2177:   return(0);
2178: }

2180: /*@
2181:     PCFieldSplitSetBlockSize - Sets the block size for defining where fields start in the
2182:       fieldsplit preconditioner. If not set the matrix block size is used.

2184:     Logically Collective on PC

2186:     Input Parameters:
2187: +   pc  - the preconditioner context
2188: -   bs - the block size

2190:     Level: intermediate

2192: .seealso: PCFieldSplitGetSubKSP(), PCFIELDSPLIT, PCFieldSplitSetFields()

2194: @*/
2195: PetscErrorCode  PCFieldSplitSetBlockSize(PC pc,PetscInt bs)
2196: {

2202:   PetscTryMethod(pc,"PCFieldSplitSetBlockSize_C",(PC,PetscInt),(pc,bs));
2203:   return(0);
2204: }

2206: /*@C
2207:    PCFieldSplitGetSubKSP - Gets the KSP contexts for all splits

2209:    Collective on KSP

2211:    Input Parameter:
2212: .  pc - the preconditioner context

2214:    Output Parameters:
2215: +  n - the number of splits
2216: -  subksp - the array of KSP contexts

2218:    Note:
2219:    After PCFieldSplitGetSubKSP() the array of KSPs is to be freed by the user with PetscFree()
2220:    (not the KSP just the array that contains them).

2222:    You must call PCSetUp() before calling PCFieldSplitGetSubKSP().

2224:    If the fieldsplit is of type PC_COMPOSITE_SCHUR, it returns the KSP object used inside the
2225:    Schur complement and the KSP object used to iterate over the Schur complement.
2226:    To access all the KSP objects used in PC_COMPOSITE_SCHUR, use PCFieldSplitSchurGetSubKSP().

2228:    If the fieldsplit is of type PC_COMPOSITE_GKB, it returns the KSP object used to solve the
2229:    inner linear system defined by the matrix H in each loop.

2231:    Fortran Usage: You must pass in a KSP array that is large enough to contain all the local KSPs.
2232:       You can call PCFieldSplitGetSubKSP(pc,n,PETSC_NULL_KSP,ierr) to determine how large the
2233:       KSP array must be.


2236:    Level: advanced

2238: .seealso: PCFIELDSPLIT
2239: @*/
2240: PetscErrorCode  PCFieldSplitGetSubKSP(PC pc,PetscInt *n,KSP *subksp[])
2241: {

2247:   PetscUseMethod(pc,"PCFieldSplitGetSubKSP_C",(PC,PetscInt*,KSP **),(pc,n,subksp));
2248:   return(0);
2249: }

2251: /*@C
2252:    PCFieldSplitSchurGetSubKSP - Gets the KSP contexts used inside the Schur complement based PCFIELDSPLIT

2254:    Collective on KSP

2256:    Input Parameter:
2257: .  pc - the preconditioner context

2259:    Output Parameters:
2260: +  n - the number of splits
2261: -  subksp - the array of KSP contexts

2263:    Note:
2264:    After PCFieldSplitSchurGetSubKSP() the array of KSPs is to be freed by the user with PetscFree()
2265:    (not the KSP just the array that contains them).

2267:    You must call PCSetUp() before calling PCFieldSplitSchurGetSubKSP().

2269:    If the fieldsplit type is of type PC_COMPOSITE_SCHUR, it returns (in order)
2270:    - the KSP used for the (1,1) block
2271:    - the KSP used for the Schur complement (not the one used for the interior Schur solver)
2272:    - the KSP used for the (1,1) block in the upper triangular factor (if different from that of the (1,1) block).

2274:    It returns a null array if the fieldsplit is not of type PC_COMPOSITE_SCHUR; in this case, you should use PCFieldSplitGetSubKSP().

2276:    Fortran Usage: You must pass in a KSP array that is large enough to contain all the local KSPs.
2277:       You can call PCFieldSplitSchurGetSubKSP(pc,n,PETSC_NULL_KSP,ierr) to determine how large the
2278:       KSP array must be.

2280:    Level: advanced

2282: .seealso: PCFIELDSPLIT
2283: @*/
2284: PetscErrorCode  PCFieldSplitSchurGetSubKSP(PC pc,PetscInt *n,KSP *subksp[])
2285: {

2291:   PetscUseMethod(pc,"PCFieldSplitSchurGetSubKSP_C",(PC,PetscInt*,KSP **),(pc,n,subksp));
2292:   return(0);
2293: }

2295: /*@
2296:     PCFieldSplitSetSchurPre -  Indicates what operator is used to construct the preconditioner for the Schur complement.
2297:       A11 matrix. Otherwise no preconditioner is used.

2299:     Collective on PC

2301:     Input Parameters:
2302: +   pc      - the preconditioner context
2303: .   ptype   - which matrix to use for preconditioning the Schur complement: PC_FIELDSPLIT_SCHUR_PRE_A11 (default), PC_FIELDSPLIT_SCHUR_PRE_SELF, PC_FIELDSPLIT_SCHUR_PRE_USER
2304:               PC_FIELDSPLIT_SCHUR_PRE_SELFP, and PC_FIELDSPLIT_SCHUR_PRE_FULL
2305: -   userpre - matrix to use for preconditioning, or NULL

2307:     Options Database:
2308: .     -pc_fieldsplit_schur_precondition <self,selfp,user,a11,full> - default is a11. See notes for meaning of various arguments

2310:     Notes:
2311: $    If ptype is
2312: $        a11 then the preconditioner for the Schur complement is generated from the block diagonal part of the preconditioner
2313: $             matrix associated with the Schur complement (i.e. A11), not the Schur complement matrix
2314: $        self the preconditioner for the Schur complement is generated from the symbolic representation of the Schur complement matrix:
2315: $             The only preconditioner that currently works with this symbolic respresentation matrix object is the PCLSC
2316: $             preconditioner
2317: $        user then the preconditioner for the Schur complement is generated from the user provided matrix (pre argument
2318: $             to this function).
2319: $        selfp then the preconditioning for the Schur complement is generated from an explicitly-assembled approximation Sp = A11 - A10 inv(diag(A00)) A01
2320: $             This is only a good preconditioner when diag(A00) is a good preconditioner for A00. Optionally, A00 can be
2321: $             lumped before extracting the diagonal using the additional option -fieldsplit_1_mat_schur_complement_ainv_type lump
2322: $        full then the preconditioner for the Schur complement is generated from the exact Schur complement matrix representation computed internally by PCFIELDSPLIT (this is expensive)
2323: $             useful mostly as a test that the Schur complement approach can work for your problem

2325:      When solving a saddle point problem, where the A11 block is identically zero, using a11 as the ptype only makes sense
2326:     with the additional option -fieldsplit_1_pc_type none. Usually for saddle point problems one would use a ptype of self and
2327:     -fieldsplit_1_pc_type lsc which uses the least squares commutator to compute a preconditioner for the Schur complement.

2329:     Level: intermediate

2331: .seealso: PCFieldSplitGetSchurPre(), PCFieldSplitGetSubKSP(), PCFIELDSPLIT, PCFieldSplitSetFields(), PCFieldSplitSchurPreType,
2332:           MatSchurComplementSetAinvType(), PCLSC

2334: @*/
2335: PetscErrorCode PCFieldSplitSetSchurPre(PC pc,PCFieldSplitSchurPreType ptype,Mat pre)
2336: {

2341:   PetscTryMethod(pc,"PCFieldSplitSetSchurPre_C",(PC,PCFieldSplitSchurPreType,Mat),(pc,ptype,pre));
2342:   return(0);
2343: }

2345: PetscErrorCode PCFieldSplitSchurPrecondition(PC pc,PCFieldSplitSchurPreType ptype,Mat pre) {return PCFieldSplitSetSchurPre(pc,ptype,pre);} /* Deprecated name */

2347: /*@
2348:     PCFieldSplitGetSchurPre - For Schur complement fieldsplit, determine how the Schur complement will be
2349:     preconditioned.  See PCFieldSplitSetSchurPre() for details.

2351:     Logically Collective on PC

2353:     Input Parameters:
2354: .   pc      - the preconditioner context

2356:     Output Parameters:
2357: +   ptype   - which matrix to use for preconditioning the Schur complement: PC_FIELDSPLIT_SCHUR_PRE_A11, PC_FIELDSPLIT_SCHUR_PRE_SELF, PC_FIELDSPLIT_PRE_USER
2358: -   userpre - matrix to use for preconditioning (with PC_FIELDSPLIT_PRE_USER), or NULL

2360:     Level: intermediate

2362: .seealso: PCFieldSplitSetSchurPre(), PCFieldSplitGetSubKSP(), PCFIELDSPLIT, PCFieldSplitSetFields(), PCFieldSplitSchurPreType, PCLSC

2364: @*/
2365: PetscErrorCode PCFieldSplitGetSchurPre(PC pc,PCFieldSplitSchurPreType *ptype,Mat *pre)
2366: {

2371:   PetscUseMethod(pc,"PCFieldSplitGetSchurPre_C",(PC,PCFieldSplitSchurPreType*,Mat*),(pc,ptype,pre));
2372:   return(0);
2373: }

2375: /*@
2376:     PCFieldSplitSchurGetS -  extract the MatSchurComplement object used by this PC in case it needs to be configured separately

2378:     Not collective

2380:     Input Parameter:
2381: .   pc      - the preconditioner context

2383:     Output Parameter:
2384: .   S       - the Schur complement matrix

2386:     Notes:
2387:     This matrix should not be destroyed using MatDestroy(); rather, use PCFieldSplitSchurRestoreS().

2389:     Level: advanced

2391: .seealso: PCFieldSplitGetSubKSP(), PCFIELDSPLIT, PCFieldSplitSchurPreType, PCFieldSplitSetSchurPre(), MatSchurComplement, PCFieldSplitSchurRestoreS()

2393: @*/
2394: PetscErrorCode  PCFieldSplitSchurGetS(PC pc,Mat *S)
2395: {
2397:   const char*    t;
2398:   PetscBool      isfs;
2399:   PC_FieldSplit  *jac;

2403:   PetscObjectGetType((PetscObject)pc,&t);
2404:   PetscStrcmp(t,PCFIELDSPLIT,&isfs);
2405:   if (!isfs) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Expected PC of type PCFIELDSPLIT, got %s instead",t);
2406:   jac = (PC_FieldSplit*)pc->data;
2407:   if (jac->type != PC_COMPOSITE_SCHUR) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Expected PCFIELDSPLIT of type SCHUR, got %D instead",jac->type);
2408:   if (S) *S = jac->schur;
2409:   return(0);
2410: }

2412: /*@
2413:     PCFieldSplitSchurRestoreS -  restores the MatSchurComplement object used by this PC

2415:     Not collective

2417:     Input Parameters:
2418: +   pc      - the preconditioner context
2419: -   S       - the Schur complement matrix

2421:     Level: advanced

2423: .seealso: PCFieldSplitGetSubKSP(), PCFIELDSPLIT, PCFieldSplitSchurPreType, PCFieldSplitSetSchurPre(), MatSchurComplement, PCFieldSplitSchurGetS()

2425: @*/
2426: PetscErrorCode  PCFieldSplitSchurRestoreS(PC pc,Mat *S)
2427: {
2429:   const char*    t;
2430:   PetscBool      isfs;
2431:   PC_FieldSplit  *jac;

2435:   PetscObjectGetType((PetscObject)pc,&t);
2436:   PetscStrcmp(t,PCFIELDSPLIT,&isfs);
2437:   if (!isfs) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Expected PC of type PCFIELDSPLIT, got %s instead",t);
2438:   jac = (PC_FieldSplit*)pc->data;
2439:   if (jac->type != PC_COMPOSITE_SCHUR) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Expected PCFIELDSPLIT of type SCHUR, got %D instead",jac->type);
2440:   if (!S || *S != jac->schur) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"MatSchurComplement restored is not the same as gotten");
2441:   return(0);
2442: }


2445: static PetscErrorCode  PCFieldSplitSetSchurPre_FieldSplit(PC pc,PCFieldSplitSchurPreType ptype,Mat pre)
2446: {
2447:   PC_FieldSplit  *jac = (PC_FieldSplit*)pc->data;

2451:   jac->schurpre = ptype;
2452:   if (ptype == PC_FIELDSPLIT_SCHUR_PRE_USER && pre) {
2453:     MatDestroy(&jac->schur_user);
2454:     jac->schur_user = pre;
2455:     PetscObjectReference((PetscObject)jac->schur_user);
2456:   }
2457:   return(0);
2458: }

2460: static PetscErrorCode  PCFieldSplitGetSchurPre_FieldSplit(PC pc,PCFieldSplitSchurPreType *ptype,Mat *pre)
2461: {
2462:   PC_FieldSplit  *jac = (PC_FieldSplit*)pc->data;

2465:   *ptype = jac->schurpre;
2466:   *pre   = jac->schur_user;
2467:   return(0);
2468: }

2470: /*@
2471:     PCFieldSplitSetSchurFactType -  sets which blocks of the approximate block factorization to retain in the preconditioner

2473:     Collective on PC

2475:     Input Parameters:
2476: +   pc  - the preconditioner context
2477: -   ftype - which blocks of factorization to retain, PC_FIELDSPLIT_SCHUR_FACT_FULL is default

2479:     Options Database:
2480: .     -pc_fieldsplit_schur_fact_type <diag,lower,upper,full> default is full


2483:     Level: intermediate

2485:     Notes:
2486:     The FULL factorization is

2488: $   (A   B)  = (1       0) (A   0) (1  Ainv*B)  = L D U
2489: $   (C   E)    (C*Ainv  1) (0   S) (0     1  )

2491:     where S = E - C*Ainv*B. In practice, the full factorization is applied via block triangular solves with the grouping L*(D*U). UPPER uses D*U, LOWER uses L*D,
2492:     and DIAG is the diagonal part with the sign of S flipped (because this makes the preconditioner positive definite for many formulations, thus allowing the use of KSPMINRES). Sign flipping of S can be turned off with PCFieldSplitSetSchurScale().

2494: $    If A and S are solved exactly
2495: $      *) FULL factorization is a direct solver.
2496: $      *) The preconditioned operator with LOWER or UPPER has all eigenvalues equal to 1 and minimal polynomial of degree 2, so KSPGMRES converges in 2 iterations.
2497: $      *) With DIAG, the preconditioned operator has three distinct nonzero eigenvalues and minimal polynomial of degree at most 4, so KSPGMRES converges in at most 4 iterations.

2499:     If the iteration count is very low, consider using KSPFGMRES or KSPGCR which can use one less preconditioner
2500:     application in this case. Note that the preconditioned operator may be highly non-normal, so such fast convergence may not be observed in practice.

2502:     For symmetric problems in which A is positive definite and S is negative definite, DIAG can be used with KSPMINRES.

2504:     Note that a flexible method like KSPFGMRES or KSPGCR must be used if the fieldsplit preconditioner is nonlinear (e.g. a few iterations of a Krylov method is used to solve with A or S).

2506:     References:
2507: +   1. - Murphy, Golub, and Wathen, A note on preconditioning indefinite linear systems, SIAM J. Sci. Comput., 21 (2000).
2508: -   2. - Ipsen, A note on preconditioning nonsymmetric matrices, SIAM J. Sci. Comput., 23 (2001).

2510: .seealso: PCFieldSplitGetSubKSP(), PCFIELDSPLIT, PCFieldSplitSetFields(), PCFieldSplitSchurPreType, PCFieldSplitSetSchurScale()
2511: @*/
2512: PetscErrorCode  PCFieldSplitSetSchurFactType(PC pc,PCFieldSplitSchurFactType ftype)
2513: {

2518:   PetscTryMethod(pc,"PCFieldSplitSetSchurFactType_C",(PC,PCFieldSplitSchurFactType),(pc,ftype));
2519:   return(0);
2520: }

2522: static PetscErrorCode PCFieldSplitSetSchurFactType_FieldSplit(PC pc,PCFieldSplitSchurFactType ftype)
2523: {
2524:   PC_FieldSplit *jac = (PC_FieldSplit*)pc->data;

2527:   jac->schurfactorization = ftype;
2528:   return(0);
2529: }

2531: /*@
2532:     PCFieldSplitSetSchurScale -  Controls the sign flip of S for PC_FIELDSPLIT_SCHUR_FACT_DIAG.

2534:     Collective on PC

2536:     Input Parameters:
2537: +   pc    - the preconditioner context
2538: -   scale - scaling factor for the Schur complement

2540:     Options Database:
2541: .     -pc_fieldsplit_schur_scale - default is -1.0

2543:     Level: intermediate

2545: .seealso: PCFIELDSPLIT, PCFieldSplitSetFields(), PCFieldSplitSchurFactType, PCFieldSplitSetSchurScale()
2546: @*/
2547: PetscErrorCode PCFieldSplitSetSchurScale(PC pc,PetscScalar scale)
2548: {

2554:   PetscTryMethod(pc,"PCFieldSplitSetSchurScale_C",(PC,PetscScalar),(pc,scale));
2555:   return(0);
2556: }

2558: static PetscErrorCode PCFieldSplitSetSchurScale_FieldSplit(PC pc,PetscScalar scale)
2559: {
2560:   PC_FieldSplit *jac = (PC_FieldSplit*)pc->data;

2563:   jac->schurscale = scale;
2564:   return(0);
2565: }

2567: /*@C
2568:    PCFieldSplitGetSchurBlocks - Gets all matrix blocks for the Schur complement

2570:    Collective on KSP

2572:    Input Parameter:
2573: .  pc - the preconditioner context

2575:    Output Parameters:
2576: +  A00 - the (0,0) block
2577: .  A01 - the (0,1) block
2578: .  A10 - the (1,0) block
2579: -  A11 - the (1,1) block

2581:    Level: advanced

2583: .seealso: PCFIELDSPLIT
2584: @*/
2585: PetscErrorCode  PCFieldSplitGetSchurBlocks(PC pc,Mat *A00,Mat *A01,Mat *A10, Mat *A11)
2586: {
2587:   PC_FieldSplit *jac = (PC_FieldSplit*) pc->data;

2591:   if (jac->type != PC_COMPOSITE_SCHUR) SETERRQ(PetscObjectComm((PetscObject)pc),PETSC_ERR_ARG_WRONG, "FieldSplit is not using a Schur complement approach.");
2592:   if (A00) *A00 = jac->pmat[0];
2593:   if (A01) *A01 = jac->B;
2594:   if (A10) *A10 = jac->C;
2595:   if (A11) *A11 = jac->pmat[1];
2596:   return(0);
2597: }

2599: /*@
2600:     PCFieldSplitSetGKBTol -  Sets the solver tolerance for the generalized Golub-Kahan bidiagonalization preconditioner.

2602:     Collective on PC

2604:     Notes:
2605:     The generalized GKB algorithm uses a lower bound estimate of the error in energy norm as stopping criterion.
2606:     It stops once the lower bound estimate undershoots the required solver tolerance. Although the actual error might be bigger than
2607:     this estimate, the stopping criterion is satisfactory in practical cases [A13].

2609: [Ar13] Generalized Golub-Kahan bidiagonalization and stopping criteria, SIAM J. Matrix Anal. Appl., Vol. 34, No. 2, pp. 571-592, 2013.

2611:     Input Parameters:
2612: +   pc        - the preconditioner context
2613: -   tolerance - the solver tolerance

2615:     Options Database:
2616: .     -pc_fieldsplit_gkb_tol - default is 1e-5

2618:     Level: intermediate

2620: .seealso: PCFIELDSPLIT, PCFieldSplitSetGKBDelay(), PCFieldSplitSetGKBNu(), PCFieldSplitSetGKBMaxit()
2621: @*/
2622: PetscErrorCode PCFieldSplitSetGKBTol(PC pc,PetscReal tolerance)
2623: {

2629:   PetscTryMethod(pc,"PCFieldSplitSetGKBTol_C",(PC,PetscReal),(pc,tolerance));
2630:   return(0);
2631: }

2633: static PetscErrorCode PCFieldSplitSetGKBTol_FieldSplit(PC pc,PetscReal tolerance)
2634: {
2635:   PC_FieldSplit *jac = (PC_FieldSplit*)pc->data;

2638:   jac->gkbtol = tolerance;
2639:   return(0);
2640: }


2643: /*@
2644:     PCFieldSplitSetGKBMaxit -  Sets the maximum number of iterations for the generalized Golub-Kahan bidiagonalization
2645:     preconditioner.

2647:     Collective on PC

2649:     Input Parameters:
2650: +   pc     - the preconditioner context
2651: -   maxit  - the maximum number of iterations

2653:     Options Database:
2654: .     -pc_fieldsplit_gkb_maxit - default is 100

2656:     Level: intermediate

2658: .seealso: PCFIELDSPLIT, PCFieldSplitSetGKBDelay(), PCFieldSplitSetGKBTol(), PCFieldSplitSetGKBNu()
2659: @*/
2660: PetscErrorCode PCFieldSplitSetGKBMaxit(PC pc,PetscInt maxit)
2661: {

2667:   PetscTryMethod(pc,"PCFieldSplitSetGKBMaxit_C",(PC,PetscInt),(pc,maxit));
2668:   return(0);
2669: }

2671: static PetscErrorCode PCFieldSplitSetGKBMaxit_FieldSplit(PC pc,PetscInt maxit)
2672: {
2673:   PC_FieldSplit *jac = (PC_FieldSplit*)pc->data;

2676:   jac->gkbmaxit = maxit;
2677:   return(0);
2678: }

2680: /*@
2681:     PCFieldSplitSetGKBDelay -  Sets the delay in the lower bound error estimate in the generalized Golub-Kahan bidiagonalization
2682:     preconditioner.

2684:     Collective on PC

2686:     Notes:
2687:     The algorithm uses a lower bound estimate of the error in energy norm as stopping criterion. The lower bound of the error ||u-u^k||_H
2688:     is expressed as a truncated sum. The error at iteration k can only be measured at iteration (k + delay), and thus the algorithm needs
2689:     at least (delay + 1) iterations to stop. For more details on the generalized Golub-Kahan bidiagonalization method and its lower bound stopping criterion, please refer to

2691: [Ar13] Generalized Golub-Kahan bidiagonalization and stopping criteria, SIAM J. Matrix Anal. Appl., Vol. 34, No. 2, pp. 571-592, 2013.

2693:     Input Parameters:
2694: +   pc     - the preconditioner context
2695: -   delay  - the delay window in the lower bound estimate

2697:     Options Database:
2698: .     -pc_fieldsplit_gkb_delay - default is 5

2700:     Level: intermediate

2702: .seealso: PCFIELDSPLIT, PCFieldSplitSetGKBNu(), PCFieldSplitSetGKBTol(), PCFieldSplitSetGKBMaxit()
2703: @*/
2704: PetscErrorCode PCFieldSplitSetGKBDelay(PC pc,PetscInt delay)
2705: {

2711:   PetscTryMethod(pc,"PCFieldSplitSetGKBDelay_C",(PC,PetscInt),(pc,delay));
2712:   return(0);
2713: }

2715: static PetscErrorCode PCFieldSplitSetGKBDelay_FieldSplit(PC pc,PetscInt delay)
2716: {
2717:   PC_FieldSplit *jac = (PC_FieldSplit*)pc->data;

2720:   jac->gkbdelay = delay;
2721:   return(0);
2722: }

2724: /*@
2725:     PCFieldSplitSetGKBNu -  Sets the scalar value nu >= 0 in the transformation H = A00 + nu*A01*A01' of the (1,1) block in the Golub-Kahan bidiagonalization preconditioner.

2727:     Collective on PC

2729:     Notes:
2730:     This shift is in general done to obtain better convergence properties for the outer loop of the algorithm. This is often achieved by chosing nu sufficiently big. However,
2731:     if nu is chosen too big, the matrix H might be badly conditioned and the solution of the linear system Hx = b in the inner loop gets difficult. It is therefore
2732:     necessary to find a good balance in between the convergence of the inner and outer loop.

2734:     For nu = 0, no shift is done. In this case A00 has to be positive definite. The matrix N in [Ar13] is then chosen as identity.

2736: [Ar13] Generalized Golub-Kahan bidiagonalization and stopping criteria, SIAM J. Matrix Anal. Appl., Vol. 34, No. 2, pp. 571-592, 2013.

2738:     Input Parameters:
2739: +   pc     - the preconditioner context
2740: -   nu     - the shift parameter

2742:     Options Database:
2743: .     -pc_fieldsplit_gkb_nu - default is 1

2745:     Level: intermediate

2747: .seealso: PCFIELDSPLIT, PCFieldSplitSetGKBDelay(), PCFieldSplitSetGKBTol(), PCFieldSplitSetGKBMaxit()
2748: @*/
2749: PetscErrorCode PCFieldSplitSetGKBNu(PC pc,PetscReal nu)
2750: {

2756:   PetscTryMethod(pc,"PCFieldSplitSetGKBNu_C",(PC,PetscReal),(pc,nu));
2757:   return(0);
2758: }

2760: static PetscErrorCode PCFieldSplitSetGKBNu_FieldSplit(PC pc,PetscReal nu)
2761: {
2762:   PC_FieldSplit *jac = (PC_FieldSplit*)pc->data;

2765:   jac->gkbnu = nu;
2766:   return(0);
2767: }


2770: static PetscErrorCode  PCFieldSplitSetType_FieldSplit(PC pc,PCCompositeType type)
2771: {
2772:   PC_FieldSplit  *jac = (PC_FieldSplit*)pc->data;

2776:   jac->type = type;

2778:   PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitGetSubKSP_C",0);
2779:   PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitSetSchurPre_C",0);
2780:   PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitGetSchurPre_C",0);
2781:   PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitSetSchurFactType_C",0);
2782:   PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitSetSchurScale_C",0);
2783:   PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitSetGKBTol_C",0);
2784:   PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitSetGKBMaxit_C",0);
2785:   PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitSetGKBNu_C",0);
2786:   PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitSetGKBDelay_C",0);

2788:   if (type == PC_COMPOSITE_SCHUR) {
2789:     pc->ops->apply = PCApply_FieldSplit_Schur;
2790:     pc->ops->view  = PCView_FieldSplit_Schur;

2792:     PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitGetSubKSP_C",PCFieldSplitGetSubKSP_FieldSplit_Schur);
2793:     PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitSetSchurPre_C",PCFieldSplitSetSchurPre_FieldSplit);
2794:     PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitGetSchurPre_C",PCFieldSplitGetSchurPre_FieldSplit);
2795:     PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitSetSchurFactType_C",PCFieldSplitSetSchurFactType_FieldSplit);
2796:     PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitSetSchurScale_C",PCFieldSplitSetSchurScale_FieldSplit);
2797:   } else if (type == PC_COMPOSITE_GKB){
2798:     pc->ops->apply = PCApply_FieldSplit_GKB;
2799:     pc->ops->view  = PCView_FieldSplit_GKB;

2801:     PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitGetSubKSP_C",PCFieldSplitGetSubKSP_FieldSplit);
2802:     PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitSetGKBTol_C",PCFieldSplitSetGKBTol_FieldSplit);
2803:     PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitSetGKBMaxit_C",PCFieldSplitSetGKBMaxit_FieldSplit);
2804:     PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitSetGKBNu_C",PCFieldSplitSetGKBNu_FieldSplit);
2805:     PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitSetGKBDelay_C",PCFieldSplitSetGKBDelay_FieldSplit);
2806:   } else {
2807:     pc->ops->apply = PCApply_FieldSplit;
2808:     pc->ops->view  = PCView_FieldSplit;

2810:     PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitGetSubKSP_C",PCFieldSplitGetSubKSP_FieldSplit);
2811:   }
2812:   return(0);
2813: }

2815: static PetscErrorCode  PCFieldSplitSetBlockSize_FieldSplit(PC pc,PetscInt bs)
2816: {
2817:   PC_FieldSplit *jac = (PC_FieldSplit*)pc->data;

2820:   if (bs < 1) SETERRQ1(PetscObjectComm((PetscObject)pc),PETSC_ERR_ARG_OUTOFRANGE,"Blocksize must be positive, you gave %D",bs);
2821:   if (jac->bs > 0 && jac->bs != bs) SETERRQ2(PetscObjectComm((PetscObject)pc),PETSC_ERR_ARG_WRONGSTATE,"Cannot change fieldsplit blocksize from %D to %D after it has been set",jac->bs,bs);
2822:   jac->bs = bs;
2823:   return(0);
2824: }

2826: /*@
2827:    PCFieldSplitSetType - Sets the type of fieldsplit preconditioner.

2829:    Collective on PC

2831:    Input Parameter:
2832: +  pc - the preconditioner context
2833: -  type - PC_COMPOSITE_ADDITIVE, PC_COMPOSITE_MULTIPLICATIVE (default), PC_COMPOSITE_SYMMETRIC_MULTIPLICATIVE, PC_COMPOSITE_SPECIAL, PC_COMPOSITE_SCHUR

2835:    Options Database Key:
2836: .  -pc_fieldsplit_type <type: one of multiplicative, additive, symmetric_multiplicative, special, schur> - Sets fieldsplit preconditioner type

2838:    Level: Intermediate

2840: .seealso: PCCompositeSetType()

2842: @*/
2843: PetscErrorCode  PCFieldSplitSetType(PC pc,PCCompositeType type)
2844: {

2849:   PetscTryMethod(pc,"PCFieldSplitSetType_C",(PC,PCCompositeType),(pc,type));
2850:   return(0);
2851: }

2853: /*@
2854:   PCFieldSplitGetType - Gets the type of fieldsplit preconditioner.

2856:   Not collective

2858:   Input Parameter:
2859: . pc - the preconditioner context

2861:   Output Parameter:
2862: . type - PC_COMPOSITE_ADDITIVE, PC_COMPOSITE_MULTIPLICATIVE (default), PC_COMPOSITE_SYMMETRIC_MULTIPLICATIVE, PC_COMPOSITE_SPECIAL, PC_COMPOSITE_SCHUR

2864:   Level: Intermediate

2866: .seealso: PCCompositeSetType()
2867: @*/
2868: PetscErrorCode PCFieldSplitGetType(PC pc, PCCompositeType *type)
2869: {
2870:   PC_FieldSplit *jac = (PC_FieldSplit*) pc->data;

2875:   *type = jac->type;
2876:   return(0);
2877: }

2879: /*@
2880:    PCFieldSplitSetDMSplits - Flags whether DMCreateFieldDecomposition() should be used to define the splits, whenever possible.

2882:    Logically Collective

2884:    Input Parameters:
2885: +  pc   - the preconditioner context
2886: -  flg  - boolean indicating whether to use field splits defined by the DM

2888:    Options Database Key:
2889: .  -pc_fieldsplit_dm_splits

2891:    Level: Intermediate

2893: .seealso: PCFieldSplitGetDMSplits()

2895: @*/
2896: PetscErrorCode  PCFieldSplitSetDMSplits(PC pc,PetscBool flg)
2897: {
2898:   PC_FieldSplit  *jac = (PC_FieldSplit*)pc->data;
2899:   PetscBool      isfs;

2905:   PetscObjectTypeCompare((PetscObject)pc,PCFIELDSPLIT,&isfs);
2906:   if (isfs) {
2907:     jac->dm_splits = flg;
2908:   }
2909:   return(0);
2910: }


2913: /*@
2914:    PCFieldSplitGetDMSplits - Returns flag indicating whether DMCreateFieldDecomposition() should be used to define the splits, whenever possible.

2916:    Logically Collective

2918:    Input Parameter:
2919: .  pc   - the preconditioner context

2921:    Output Parameter:
2922: .  flg  - boolean indicating whether to use field splits defined by the DM

2924:    Level: Intermediate

2926: .seealso: PCFieldSplitSetDMSplits()

2928: @*/
2929: PetscErrorCode  PCFieldSplitGetDMSplits(PC pc,PetscBool* flg)
2930: {
2931:   PC_FieldSplit  *jac = (PC_FieldSplit*)pc->data;
2932:   PetscBool      isfs;

2938:   PetscObjectTypeCompare((PetscObject)pc,PCFIELDSPLIT,&isfs);
2939:   if (isfs) {
2940:     if(flg) *flg = jac->dm_splits;
2941:   }
2942:   return(0);
2943: }

2945: /*@
2946:    PCFieldSplitGetDetectSaddlePoint - Returns flag indicating whether PCFieldSplit will attempt to automatically determine fields based on zero diagonal entries.

2948:    Logically Collective

2950:    Input Parameter:
2951: .  pc   - the preconditioner context

2953:    Output Parameter:
2954: .  flg  - boolean indicating whether to detect fields or not

2956:    Level: Intermediate

2958: .seealso: PCFIELDSPLIT, PCFieldSplitSetDetectSaddlePoint()

2960: @*/
2961: PetscErrorCode PCFieldSplitGetDetectSaddlePoint(PC pc,PetscBool *flg)
2962: {
2963:   PC_FieldSplit *jac = (PC_FieldSplit*)pc->data;

2966:   *flg = jac->detect;
2967:   return(0);
2968: }

2970: /*@
2971:    PCFieldSplitSetDetectSaddlePoint - Sets flag indicating whether PCFieldSplit will attempt to automatically determine fields based on zero diagonal entries.

2973:    Logically Collective

2975:    Notes:
2976:    Also sets the split type to PC_COMPOSITE_SCHUR (see PCFieldSplitSetType()) and the Schur preconditioner type to PC_FIELDSPLIT_SCHUR_PRE_SELF (see PCFieldSplitSetSchurPre()).

2978:    Input Parameter:
2979: .  pc   - the preconditioner context

2981:    Output Parameter:
2982: .  flg  - boolean indicating whether to detect fields or not

2984:    Options Database Key:
2985: .  -pc_fieldsplit_detect_saddle_point

2987:    Level: Intermediate

2989: .seealso: PCFIELDSPLIT, PCFieldSplitSetDetectSaddlePoint(), PCFieldSplitSetType(), PCFieldSplitSetSchurPre()

2991: @*/
2992: PetscErrorCode PCFieldSplitSetDetectSaddlePoint(PC pc,PetscBool flg)
2993: {
2994:   PC_FieldSplit  *jac = (PC_FieldSplit*)pc->data;

2998:   jac->detect = flg;
2999:   if (jac->detect) {
3000:     PCFieldSplitSetType(pc,PC_COMPOSITE_SCHUR);
3001:     PCFieldSplitSetSchurPre(pc,PC_FIELDSPLIT_SCHUR_PRE_SELF,NULL);
3002:   }
3003:   return(0);
3004: }

3006: /* -------------------------------------------------------------------------------------*/
3007: /*MC
3008:    PCFIELDSPLIT - Preconditioner created by combining separate preconditioners for individual
3009:                   fields or groups of fields. See the users manual section "Solving Block Matrices" for more details.

3011:      To set options on the solvers for each block append -fieldsplit_ to all the PC
3012:         options database keys. For example, -fieldsplit_pc_type ilu -fieldsplit_pc_factor_levels 1

3014:      To set the options on the solvers separate for each block call PCFieldSplitGetSubKSP()
3015:          and set the options directly on the resulting KSP object

3017:    Level: intermediate

3019:    Options Database Keys:
3020: +   -pc_fieldsplit_%d_fields <a,b,..> - indicates the fields to be used in the %d'th split
3021: .   -pc_fieldsplit_default - automatically add any fields to additional splits that have not
3022:                               been supplied explicitly by -pc_fieldsplit_%d_fields
3023: .   -pc_fieldsplit_block_size <bs> - size of block that defines fields (i.e. there are bs fields)
3024: .   -pc_fieldsplit_type <additive,multiplicative,symmetric_multiplicative,schur,gkb> - type of relaxation or factorization splitting
3025: .   -pc_fieldsplit_schur_precondition <self,selfp,user,a11,full> - default is a11; see PCFieldSplitSetSchurPre()
3026: .   -pc_fieldsplit_detect_saddle_point - automatically finds rows with zero diagonal and uses Schur complement with no preconditioner as the solver

3028: .    Options prefix for inner solvers when using Schur complement preconditioner are -fieldsplit_0_ and -fieldsplit_1_
3029:      for all other solvers they are -fieldsplit_%d_ for the dth field, use -fieldsplit_ for all fields
3030: -    Options prefix for inner solver when using Golub Kahan biadiagonalization preconditioner is -fieldsplit_0_

3032:    Notes:
3033:     Use PCFieldSplitSetFields() to set fields defined by "strided" entries and PCFieldSplitSetIS()
3034:      to define a field by an arbitrary collection of entries.

3036:       If no fields are set the default is used. The fields are defined by entries strided by bs,
3037:       beginning at 0 then 1, etc to bs-1. The block size can be set with PCFieldSplitSetBlockSize(),
3038:       if this is not called the block size defaults to the blocksize of the second matrix passed
3039:       to KSPSetOperators()/PCSetOperators().

3041: $     For the Schur complement preconditioner if J = ( A00 A01 )
3042: $                                                    ( A10 A11 )
3043: $     the preconditioner using full factorization is
3044: $              ( I   -ksp(A00) A01 ) ( inv(A00)     0  ) (     I          0  )
3045: $              ( 0         I       ) (   0      ksp(S) ) ( -A10 ksp(A00)  I  )
3046:      where the action of inv(A00) is applied using the KSP solver with prefix -fieldsplit_0_.  S is the Schur complement
3047: $              S = A11 - A10 ksp(A00) A01
3048:      which is usually dense and not stored explicitly.  The action of ksp(S) is computed using the KSP solver with prefix -fieldsplit_splitname_ (where splitname was given
3049:      in providing the SECOND split or 1 if not give). For PCFieldSplitGetSubKSP() when field number is 0,
3050:      it returns the KSP associated with -fieldsplit_0_ while field number 1 gives -fieldsplit_1_ KSP. By default
3051:      A11 is used to construct a preconditioner for S, use PCFieldSplitSetSchurPre() for all the possible ways to construct the preconditioner for S.

3053:      The factorization type is set using -pc_fieldsplit_schur_fact_type <diag, lower, upper, full>. The full is shown above,
3054:      diag gives
3055: $              ( inv(A00)     0   )
3056: $              (   0      -ksp(S) )
3057:      note that slightly counter intuitively there is a negative in front of the ksp(S) so that the preconditioner is positive definite. For SPD matrices J, the sign flip
3058:      can be turned off with PCFieldSplitSetSchurScale() or by command line -pc_fieldsplit_schur_scale 1.0. The lower factorization is the inverse of
3059: $              (  A00   0 )
3060: $              (  A10   S )
3061:      where the inverses of A00 and S are applied using KSPs. The upper factorization is the inverse of
3062: $              ( A00 A01 )
3063: $              (  0   S  )
3064:      where again the inverses of A00 and S are applied using KSPs.

3066:      If only one set of indices (one IS) is provided with PCFieldSplitSetIS() then the complement of that IS
3067:      is used automatically for a second block.

3069:      The fieldsplit preconditioner cannot currently be used with the BAIJ or SBAIJ data formats if the blocksize is larger than 1.
3070:      Generally it should be used with the AIJ format.

3072:      The forms of these preconditioners are closely related if not identical to forms derived as "Distributive Iterations", see,
3073:      for example, page 294 in "Principles of Computational Fluid Dynamics" by Pieter Wesseling. Note that one can also use PCFIELDSPLIT
3074:      inside a smoother resulting in "Distributive Smoothers".

3076:    There is a nice discussion of block preconditioners in

3078: [El08] A taxonomy and comparison of parallel block multi-level preconditioners for the incompressible Navier-Stokes equations
3079:        Howard Elman, V.E. Howle, John Shadid, Robert Shuttleworth, Ray Tuminaro, Journal of Computational Physics 227 (2008) 1790--1808
3080:        http://chess.cs.umd.edu/~elman/papers/tax.pdf

3082:    The Constrained Pressure Preconditioner (CPR) can be implemented using PCCOMPOSITE with PCGALERKIN. CPR first solves an R A P subsystem, updates the
3083:    residual on all variables (PCCompositeSetType(pc,PC_COMPOSITE_MULTIPLICATIVE)), and then applies a simple ILU like preconditioner on all the variables.

3085:    The generalized Golub-Kahan bidiagonalization preconditioner (gkb) can be applied to symmetric 2x2 block matrices of the shape
3086: $        ( A00  A01 )
3087: $        ( A01' 0   )
3088:    with A00 positive semi-definite. The implementation follows [Ar13]. Therein, we choose N := 1/nu * I and the (1,1)-block of the matrix is modified to H = A00 + nu*A01*A01'.
3089:    A linear system Hx = b has to be solved in each iteration of the GKB algorithm. This solver is chosen with the option prefix -fieldsplit_0_.

3091: [Ar13] Generalized Golub-Kahan bidiagonalization and stopping criteria, SIAM J. Matrix Anal. Appl., Vol. 34, No. 2, pp. 571-592, 2013.

3093: .seealso:  PCCreate(), PCSetType(), PCType (for list of available types), PC, Block_Preconditioners, PCLSC,
3094:            PCFieldSplitGetSubKSP(), PCFieldSplitSchurGetSubKSP(), PCFieldSplitSetFields(), PCFieldSplitSetType(), PCFieldSplitSetIS(), PCFieldSplitSetSchurPre(),
3095:           MatSchurComplementSetAinvType(), PCFieldSplitSetSchurScale(),
3096:           PCFieldSplitSetDetectSaddlePoint()
3097: M*/

3099: PETSC_EXTERN PetscErrorCode PCCreate_FieldSplit(PC pc)
3100: {
3102:   PC_FieldSplit  *jac;

3105:   PetscNewLog(pc,&jac);

3107:   jac->bs                 = -1;
3108:   jac->nsplits            = 0;
3109:   jac->type               = PC_COMPOSITE_MULTIPLICATIVE;
3110:   jac->schurpre           = PC_FIELDSPLIT_SCHUR_PRE_USER; /* Try user preconditioner first, fall back on diagonal */
3111:   jac->schurfactorization = PC_FIELDSPLIT_SCHUR_FACT_FULL;
3112:   jac->schurscale         = -1.0;
3113:   jac->dm_splits          = PETSC_TRUE;
3114:   jac->detect             = PETSC_FALSE;
3115:   jac->gkbtol             = 1e-5;
3116:   jac->gkbdelay           = 5;
3117:   jac->gkbnu              = 1;
3118:   jac->gkbmaxit           = 100;
3119:   jac->gkbmonitor         = PETSC_FALSE;

3121:   pc->data = (void*)jac;

3123:   pc->ops->apply           = PCApply_FieldSplit;
3124:   pc->ops->applytranspose  = PCApplyTranspose_FieldSplit;
3125:   pc->ops->setup           = PCSetUp_FieldSplit;
3126:   pc->ops->reset           = PCReset_FieldSplit;
3127:   pc->ops->destroy         = PCDestroy_FieldSplit;
3128:   pc->ops->setfromoptions  = PCSetFromOptions_FieldSplit;
3129:   pc->ops->view            = PCView_FieldSplit;
3130:   pc->ops->applyrichardson = 0;

3132:   PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitSchurGetSubKSP_C",PCFieldSplitSchurGetSubKSP_FieldSplit);
3133:   PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitGetSubKSP_C",PCFieldSplitGetSubKSP_FieldSplit);
3134:   PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitSetFields_C",PCFieldSplitSetFields_FieldSplit);
3135:   PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitSetIS_C",PCFieldSplitSetIS_FieldSplit);
3136:   PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitSetType_C",PCFieldSplitSetType_FieldSplit);
3137:   PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitSetBlockSize_C",PCFieldSplitSetBlockSize_FieldSplit);
3138:   PetscObjectComposeFunction((PetscObject)pc,"PCFieldSplitRestrictIS_C",PCFieldSplitRestrictIS_FieldSplit);
3139:   return(0);
3140: }