Actual source code: aoptions.c

petsc-3.14.6 2021-03-30
Report Typos and Errors


  3: /*
  4:    Implements the higher-level options database querying methods. These are self-documenting and can attach at runtime to
  5:    GUI code to display the options and get values from the users.

  7: */

  9: #include <petsc/private/petscimpl.h>
 10: #include <petscviewer.h>

 12: #define ManSection(str) ((str) ? (str) : "None")

 14: /*
 15:     Keep a linked list of options that have been posted and we are waiting for
 16:    user selection. See the manual page for PetscOptionsBegin()

 18:     Eventually we'll attach this beast to a MPI_Comm
 19: */


 22: /*
 23:     Handles setting up the data structure in a call to PetscOptionsBegin()
 24: */
 25: PetscErrorCode PetscOptionsBegin_Private(PetscOptionItems *PetscOptionsObject,MPI_Comm comm,const char prefix[],const char title[],const char mansec[])
 26: {

 33:   if (!PetscOptionsObject->alreadyprinted) {
 34:     if (!PetscOptionsHelpPrintedSingleton) {
 35:       PetscOptionsHelpPrintedCreate(&PetscOptionsHelpPrintedSingleton);
 36:     }
 37:     PetscOptionsHelpPrintedCheck(PetscOptionsHelpPrintedSingleton,prefix,title,&PetscOptionsObject->alreadyprinted);
 38:   }
 39:   PetscOptionsObject->next          = NULL;
 40:   PetscOptionsObject->comm          = comm;
 41:   PetscOptionsObject->changedmethod = PETSC_FALSE;

 43:   PetscStrallocpy(prefix,&PetscOptionsObject->prefix);
 44:   PetscStrallocpy(title,&PetscOptionsObject->title);

 46:   PetscOptionsHasHelp(PetscOptionsObject->options,&PetscOptionsObject->printhelp);
 47:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1) {
 48:     if (!PetscOptionsObject->alreadyprinted) {
 49:       (*PetscHelpPrintf)(comm,"----------------------------------------\n%s:\n",title);
 50:     }
 51:   }
 52:   return(0);
 53: }

 55: /*
 56:     Handles setting up the data structure in a call to PetscObjectOptionsBegin()
 57: */
 58: PetscErrorCode PetscObjectOptionsBegin_Private(PetscOptionItems *PetscOptionsObject,PetscObject obj)
 59: {
 61:   char           title[256];
 62:   PetscBool      flg;

 66:   PetscOptionsObject->object         = obj;
 67:   PetscOptionsObject->alreadyprinted = obj->optionsprinted;

 69:   PetscStrcmp(obj->description,obj->class_name,&flg);
 70:   if (flg) {
 71:     PetscSNPrintf(title,sizeof(title),"%s options",obj->class_name);
 72:   } else {
 73:     PetscSNPrintf(title,sizeof(title),"%s (%s) options",obj->description,obj->class_name);
 74:   }
 75:   PetscOptionsBegin_Private(PetscOptionsObject,obj->comm,obj->prefix,title,obj->mansec);
 76:   return(0);
 77: }

 79: /*
 80:      Handles adding another option to the list of options within this particular PetscOptionsBegin() PetscOptionsEnd()
 81: */
 82: static int PetscOptionItemCreate_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscOptionType t,PetscOptionItem *amsopt)
 83: {
 84:   int             ierr;
 85:   PetscOptionItem next;
 86:   PetscBool       valid;

 89:   PetscOptionsValidKey(opt,&valid);
 90:   if (!valid) SETERRQ1(PETSC_COMM_WORLD,PETSC_ERR_ARG_INCOMP,"The option '%s' is not a valid key",opt);

 92:   PetscNew(amsopt);
 93:   (*amsopt)->next = NULL;
 94:   (*amsopt)->set  = PETSC_FALSE;
 95:   (*amsopt)->type = t;
 96:   (*amsopt)->data = NULL;

 98:   PetscStrallocpy(text,&(*amsopt)->text);
 99:   PetscStrallocpy(opt,&(*amsopt)->option);
100:   PetscStrallocpy(man,&(*amsopt)->man);

102:   if (!PetscOptionsObject->next) PetscOptionsObject->next = *amsopt;
103:   else {
104:     next = PetscOptionsObject->next;
105:     while (next->next) next = next->next;
106:     next->next = *amsopt;
107:   }
108:   return(0);
109: }

111: /*
112:     PetscScanString -  Gets user input via stdin from process and broadcasts to all processes

114:     Collective

116:    Input Parameters:
117: +     commm - communicator for the broadcast, must be PETSC_COMM_WORLD
118: .     n - length of the string, must be the same on all processes
119: -     str - location to store input

121:     Bugs:
122: .   Assumes process 0 of the given communicator has access to stdin

124: */
125: static PetscErrorCode PetscScanString(MPI_Comm comm,size_t n,char str[])
126: {
127:   size_t         i;
128:   char           c;
129:   PetscMPIInt    rank,nm;

133:   MPI_Comm_rank(comm,&rank);
134:   if (!rank) {
135:     c = (char) getchar();
136:     i = 0;
137:     while (c != '\n' && i < n-1) {
138:       str[i++] = c;
139:       c = (char)getchar();
140:     }
141:     str[i] = 0;
142:   }
143:   PetscMPIIntCast(n,&nm);
144:   MPI_Bcast(str,nm,MPI_CHAR,0,comm);
145:   return(0);
146: }

148: /*
149:     This is needed because certain strings may be freed by SAWs, hence we cannot use PetscStrallocpy()
150: */
151: static PetscErrorCode  PetscStrdup(const char s[],char *t[])
152: {
154:   size_t         len;
155:   char           *tmp = NULL;

158:   if (s) {
159:     PetscStrlen(s,&len);
160:     tmp = (char*) malloc((len+1)*sizeof(char));
161:     if (!tmp) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_MEM,"No memory to duplicate string");
162:     PetscStrcpy(tmp,s);
163:   }
164:   *t = tmp;
165:   return(0);
166: }


169: /*
170:     PetscOptionsGetFromTextInput - Presents all the PETSc Options processed by the program so the user may change them at runtime

172:     Notes:
173:     this isn't really practical, it is just to demonstrate the principle

175:     A carriage return indicates no change from the default; but this like -ksp_monitor <stdout>  the default is actually not stdout the default
176:     is to do nothing so to get it to use stdout you need to type stdout. This is kind of bug?

178:     Bugs:
179: +    All processes must traverse through the exact same set of option queries due to the call to PetscScanString()
180: .    Internal strings have arbitrary length and string copies are not checked that they fit into string space
181: -    Only works for PetscInt == int, PetscReal == double etc

183:     Developer Notes:
184:     Normally the GUI that presents the options the user and retrieves the values would be running in a different
185:      address space and communicating with the PETSc program

187: */
188: PetscErrorCode PetscOptionsGetFromTextInput(PetscOptionItems *PetscOptionsObject)
189: {
190:   PetscErrorCode  ierr;
191:   PetscOptionItem next = PetscOptionsObject->next;
192:   char            str[512];
193:   PetscBool       bid;
194:   PetscReal       ir,*valr;
195:   PetscInt        *vald;
196:   size_t          i;

199:   (*PetscPrintf)(PETSC_COMM_WORLD,"%s --------------------\n",PetscOptionsObject->title);
200:   while (next) {
201:     switch (next->type) {
202:     case OPTION_HEAD:
203:       break;
204:     case OPTION_INT_ARRAY:
205:       PetscPrintf(PETSC_COMM_WORLD,"-%s%s <",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1);
206:       vald = (PetscInt*) next->data;
207:       for (i=0; i<next->arraylength; i++) {
208:         PetscPrintf(PETSC_COMM_WORLD,"%d",vald[i]);
209:         if (i < next->arraylength-1) {
210:           PetscPrintf(PETSC_COMM_WORLD,",");
211:         }
212:       }
213:       PetscPrintf(PETSC_COMM_WORLD,">: %s (%s) ",next->text,next->man);
214:       PetscScanString(PETSC_COMM_WORLD,512,str);
215:       if (str[0]) {
216:         PetscToken token;
217:         PetscInt   n=0,nmax = next->arraylength,*dvalue = (PetscInt*)next->data,start,end;
218:         size_t     len;
219:         char       *value;
220:         PetscBool  foundrange;

222:         next->set = PETSC_TRUE;
223:         value     = str;
224:         PetscTokenCreate(value,',',&token);
225:         PetscTokenFind(token,&value);
226:         while (n < nmax) {
227:           if (!value) break;

229:           /* look for form  d-D where d and D are integers */
230:           foundrange = PETSC_FALSE;
231:           PetscStrlen(value,&len);
232:           if (value[0] == '-') i=2;
233:           else i=1;
234:           for (;i<len; i++) {
235:             if (value[i] == '-') {
236:               if (i == len-1) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
237:               value[i] = 0;
238:               PetscOptionsStringToInt(value,&start);
239:               PetscOptionsStringToInt(value+i+1,&end);
240:               if (end <= start) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry, %s-%s cannot have decreasing list",n,value,value+i+1);
241:               if (n + end - start - 1 >= nmax) SETERRQ4(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry, not enough space in left in array (%D) to contain entire range from %D to %D",n,nmax-n,start,end);
242:               for (; start<end; start++) {
243:                 *dvalue = start; dvalue++;n++;
244:               }
245:               foundrange = PETSC_TRUE;
246:               break;
247:             }
248:           }
249:           if (!foundrange) {
250:             PetscOptionsStringToInt(value,dvalue);
251:             dvalue++;
252:             n++;
253:           }
254:           PetscTokenFind(token,&value);
255:         }
256:         PetscTokenDestroy(&token);
257:       }
258:       break;
259:     case OPTION_REAL_ARRAY:
260:       PetscPrintf(PETSC_COMM_WORLD,"-%s%s <",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1);
261:       valr = (PetscReal*) next->data;
262:       for (i=0; i<next->arraylength; i++) {
263:         PetscPrintf(PETSC_COMM_WORLD,"%g",valr[i]);
264:         if (i < next->arraylength-1) {
265:           PetscPrintf(PETSC_COMM_WORLD,",");
266:         }
267:       }
268:       PetscPrintf(PETSC_COMM_WORLD,">: %s (%s) ",next->text,next->man);
269:       PetscScanString(PETSC_COMM_WORLD,512,str);
270:       if (str[0]) {
271:         PetscToken token;
272:         PetscInt   n = 0,nmax = next->arraylength;
273:         PetscReal  *dvalue = (PetscReal*)next->data;
274:         char       *value;

276:         next->set = PETSC_TRUE;
277:         value     = str;
278:         PetscTokenCreate(value,',',&token);
279:         PetscTokenFind(token,&value);
280:         while (n < nmax) {
281:           if (!value) break;
282:           PetscOptionsStringToReal(value,dvalue);
283:           dvalue++;
284:           n++;
285:           PetscTokenFind(token,&value);
286:         }
287:         PetscTokenDestroy(&token);
288:       }
289:       break;
290:     case OPTION_INT:
291:       PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%d>: %s (%s) ",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1,*(int*)next->data,next->text,next->man);
292:       PetscScanString(PETSC_COMM_WORLD,512,str);
293:       if (str[0]) {
294: #if defined(PETSC_SIZEOF_LONG_LONG)
295:         long long lid;
296:         sscanf(str,"%lld",&lid);
297:         if (lid > PETSC_MAX_INT || lid < PETSC_MIN_INT) SETERRQ3(PETSC_COMM_WORLD,PETSC_ERR_ARG_OUTOFRANGE,"Argument: -%s%s %lld",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1,lid);
298: #else
299:         long  lid;
300:         sscanf(str,"%ld",&lid);
301:         if (lid > PETSC_MAX_INT || lid < PETSC_MIN_INT) SETERRQ3(PETSC_COMM_WORLD,PETSC_ERR_ARG_OUTOFRANGE,"Argument: -%s%s %ld",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1,lid);
302: #endif

304:         next->set = PETSC_TRUE;
305:         *((PetscInt*)next->data) = (PetscInt)lid;
306:       }
307:       break;
308:     case OPTION_REAL:
309:       PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%g>: %s (%s) ",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1,*(double*)next->data,next->text,next->man);
310:       PetscScanString(PETSC_COMM_WORLD,512,str);
311:       if (str[0]) {
312: #if defined(PETSC_USE_REAL_SINGLE)
313:         sscanf(str,"%e",&ir);
314: #elif defined(PETSC_USE_REAL___FP16)
315:         float irtemp;
316:         sscanf(str,"%e",&irtemp);
317:         ir = irtemp;
318: #elif defined(PETSC_USE_REAL_DOUBLE)
319:         sscanf(str,"%le",&ir);
320: #elif defined(PETSC_USE_REAL___FLOAT128)
321:         ir = strtoflt128(str,0);
322: #else
323:         SETERRQ(PETSC_COMM_SELF,PETSC_ERR_LIB,"Unknown scalar type");
324: #endif
325:         next->set                 = PETSC_TRUE;
326:         *((PetscReal*)next->data) = ir;
327:       }
328:       break;
329:     case OPTION_BOOL:
330:       PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%s>: %s (%s) ",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1,*(PetscBool*)next->data ? "true": "false",next->text,next->man);
331:       PetscScanString(PETSC_COMM_WORLD,512,str);
332:       if (str[0]) {
333:         PetscOptionsStringToBool(str,&bid);
334:         next->set = PETSC_TRUE;
335:         *((PetscBool*)next->data) = bid;
336:       }
337:       break;
338:     case OPTION_STRING:
339:       PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%s>: %s (%s) ",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1,(char*)next->data,next->text,next->man);
340:       PetscScanString(PETSC_COMM_WORLD,512,str);
341:       if (str[0]) {
342:         next->set = PETSC_TRUE;
343:         /* must use system malloc since SAWs may free this */
344:         PetscStrdup(str,(char**)&next->data);
345:       }
346:       break;
347:     case OPTION_FLIST:
348:       PetscFunctionListPrintTypes(PETSC_COMM_WORLD,stdout,PetscOptionsObject->prefix,next->option,next->text,next->man,next->flist,(char*)next->data,(char*)next->data);
349:       PetscScanString(PETSC_COMM_WORLD,512,str);
350:       if (str[0]) {
351:         PetscOptionsObject->changedmethod = PETSC_TRUE;
352:         next->set = PETSC_TRUE;
353:         /* must use system malloc since SAWs may free this */
354:         PetscStrdup(str,(char**)&next->data);
355:       }
356:       break;
357:     default:
358:       break;
359:     }
360:     next = next->next;
361:   }
362:   return(0);
363: }

365: #if defined(PETSC_HAVE_SAWS)
366: #include <petscviewersaws.h>

368: static int count = 0;

370: PetscErrorCode PetscOptionsSAWsDestroy(void)
371: {
373:   return(0);
374: }

376: static const char *OptionsHeader = "<head>\n"
377:                                    "<script type=\"text/javascript\" src=\"https://www.mcs.anl.gov/research/projects/saws/js/jquery-1.9.1.js\"></script>\n"
378:                                    "<script type=\"text/javascript\" src=\"https://www.mcs.anl.gov/research/projects/saws/js/SAWs.js\"></script>\n"
379:                                    "<script type=\"text/javascript\" src=\"js/PETSc.js\"></script>\n"
380:                                    "<script>\n"
381:                                       "jQuery(document).ready(function() {\n"
382:                                          "PETSc.getAndDisplayDirectory(null,\"#variablesInfo\")\n"
383:                                       "})\n"
384:                                   "</script>\n"
385:                                   "</head>\n";

387: /*  Determines the size and style of the scroll region where PETSc options selectable from users are displayed */
388: static const char *OptionsBodyBottom = "<div id=\"variablesInfo\" style=\"background-color:lightblue;height:auto;max-height:500px;overflow:scroll;\"></div>\n<br>\n</body>";

390: /*
391:     PetscOptionsSAWsInput - Presents all the PETSc Options processed by the program so the user may change them at runtime using the SAWs

393:     Bugs:
394: +    All processes must traverse through the exact same set of option queries do to the call to PetscScanString()
395: .    Internal strings have arbitrary length and string copies are not checked that they fit into string space
396: -    Only works for PetscInt == int, PetscReal == double etc


399: */
400: PetscErrorCode PetscOptionsSAWsInput(PetscOptionItems *PetscOptionsObject)
401: {
402:   PetscErrorCode  ierr;
403:   PetscOptionItem next     = PetscOptionsObject->next;
404:   static int      mancount = 0;
405:   char            options[16];
406:   PetscBool       changedmethod = PETSC_FALSE;
407:   PetscBool       stopasking    = PETSC_FALSE;
408:   char            manname[16],textname[16];
409:   char            dir[1024];

412:   /* the next line is a bug, this will only work if all processors are here, the comm passed in is ignored!!! */
413:   sprintf(options,"Options_%d",count++);

415:   PetscOptionsObject->pprefix = PetscOptionsObject->prefix; /* SAWs will change this, so cannot pass prefix directly */

417:   PetscSNPrintf(dir,1024,"/PETSc/Options/%s","_title");
418:   PetscStackCallSAWs(SAWs_Register,(dir,&PetscOptionsObject->title,1,SAWs_READ,SAWs_STRING));
419:   PetscSNPrintf(dir,1024,"/PETSc/Options/%s","prefix");
420:   PetscStackCallSAWs(SAWs_Register,(dir,&PetscOptionsObject->pprefix,1,SAWs_READ,SAWs_STRING));
421:   PetscStackCallSAWs(SAWs_Register,("/PETSc/Options/ChangedMethod",&changedmethod,1,SAWs_WRITE,SAWs_BOOLEAN));
422:   PetscStackCallSAWs(SAWs_Register,("/PETSc/Options/StopAsking",&stopasking,1,SAWs_WRITE,SAWs_BOOLEAN));

424:   while (next) {
425:     sprintf(manname,"_man_%d",mancount);
426:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",manname);
427:     PetscStackCallSAWs(SAWs_Register,(dir,&next->man,1,SAWs_READ,SAWs_STRING));
428:     sprintf(textname,"_text_%d",mancount++);
429:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",textname);
430:     PetscStackCallSAWs(SAWs_Register,(dir,&next->text,1,SAWs_READ,SAWs_STRING));

432:     switch (next->type) {
433:     case OPTION_HEAD:
434:       break;
435:     case OPTION_INT_ARRAY:
436:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
437:       PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_INT));
438:       break;
439:     case OPTION_REAL_ARRAY:
440:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
441:       PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_DOUBLE));
442:       break;
443:     case OPTION_INT:
444:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
445:       PetscStackCallSAWs(SAWs_Register,(dir,next->data,1,SAWs_WRITE,SAWs_INT));
446:       break;
447:     case OPTION_REAL:
448:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
449:       PetscStackCallSAWs(SAWs_Register,(dir,next->data,1,SAWs_WRITE,SAWs_DOUBLE));
450:       break;
451:     case OPTION_BOOL:
452:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
453:       PetscStackCallSAWs(SAWs_Register,(dir,next->data,1,SAWs_WRITE,SAWs_BOOLEAN));
454:       break;
455:     case OPTION_BOOL_ARRAY:
456:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
457:       PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_BOOLEAN));
458:       break;
459:     case OPTION_STRING:
460:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
461:       PetscStackCallSAWs(SAWs_Register,(dir,&next->data,1,SAWs_WRITE,SAWs_STRING));
462:       break;
463:     case OPTION_STRING_ARRAY:
464:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
465:       PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_STRING));
466:       break;
467:     case OPTION_FLIST:
468:       {
469:       PetscInt ntext;
470:       PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
471:       PetscStackCallSAWs(SAWs_Register,(dir,&next->data,1,SAWs_WRITE,SAWs_STRING));
472:       PetscFunctionListGet(next->flist,(const char***)&next->edata,&ntext);
473:       PetscStackCallSAWs(SAWs_Set_Legal_Variable_Values,(dir,ntext,next->edata));
474:       }
475:       break;
476:     case OPTION_ELIST:
477:       {
478:       PetscInt ntext = next->nlist;
479:       PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
480:       PetscStackCallSAWs(SAWs_Register,(dir,&next->data,1,SAWs_WRITE,SAWs_STRING));
481:       PetscMalloc1((ntext+1),(char***)&next->edata);
482:       PetscMemcpy(next->edata,next->list,ntext*sizeof(char*));
483:       PetscStackCallSAWs(SAWs_Set_Legal_Variable_Values,(dir,ntext,next->edata));
484:       }
485:       break;
486:     default:
487:       break;
488:     }
489:     next = next->next;
490:   }

492:   /* wait until accessor has unlocked the memory */
493:   PetscStackCallSAWs(SAWs_Push_Header,("index.html",OptionsHeader));
494:   PetscStackCallSAWs(SAWs_Push_Body,("index.html",2,OptionsBodyBottom));
495:   PetscSAWsBlock();
496:   PetscStackCallSAWs(SAWs_Pop_Header,("index.html"));
497:   PetscStackCallSAWs(SAWs_Pop_Body,("index.html",2));

499:   /* determine if any values have been set in GUI */
500:   next = PetscOptionsObject->next;
501:   while (next) {
502:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
503:     PetscStackCallSAWs(SAWs_Selected,(dir,(int*)&next->set));
504:     next = next->next;
505:   }

507:   /* reset counter to -2; this updates the screen with the new options for the selected method */
508:   if (changedmethod) PetscOptionsObject->count = -2;

510:   if (stopasking) {
511:     PetscOptionsPublish      = PETSC_FALSE;
512:     PetscOptionsObject->count = 0;//do not ask for same thing again
513:   }

515:   PetscStackCallSAWs(SAWs_Delete,("/PETSc/Options"));
516:   return(0);
517: }
518: #endif

520: PetscErrorCode PetscOptionsEnd_Private(PetscOptionItems *PetscOptionsObject)
521: {
522:   PetscErrorCode  ierr;
523:   PetscOptionItem last;
524:   char            option[256],value[1024],tmp[32];
525:   size_t          j;

528:   if (PetscOptionsObject->next) {
529:     if (!PetscOptionsObject->count) {
530: #if defined(PETSC_HAVE_SAWS)
531:       PetscOptionsSAWsInput(PetscOptionsObject);
532: #else
533:       PetscOptionsGetFromTextInput(PetscOptionsObject);
534: #endif
535:     }
536:   }

538:   PetscFree(PetscOptionsObject->title);

540:   /* reset counter to -2; this updates the screen with the new options for the selected method */
541:   if (PetscOptionsObject->changedmethod) PetscOptionsObject->count = -2;
542:   /* reset alreadyprinted flag */
543:   PetscOptionsObject->alreadyprinted = PETSC_FALSE;
544:   if (PetscOptionsObject->object) PetscOptionsObject->object->optionsprinted = PETSC_TRUE;
545:   PetscOptionsObject->object = NULL;

547:   while (PetscOptionsObject->next) {
548:     if (PetscOptionsObject->next->set) {
549:       if (PetscOptionsObject->prefix) {
550:         PetscStrcpy(option,"-");
551:         PetscStrcat(option,PetscOptionsObject->prefix);
552:         PetscStrcat(option,PetscOptionsObject->next->option+1);
553:       } else {
554:         PetscStrcpy(option,PetscOptionsObject->next->option);
555:       }

557:       switch (PetscOptionsObject->next->type) {
558:       case OPTION_HEAD:
559:         break;
560:       case OPTION_INT_ARRAY:
561:         sprintf(value,"%d",(int)((PetscInt*)PetscOptionsObject->next->data)[0]);
562:         for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
563:           sprintf(tmp,"%d",(int)((PetscInt*)PetscOptionsObject->next->data)[j]);
564:           PetscStrcat(value,",");
565:           PetscStrcat(value,tmp);
566:         }
567:         break;
568:       case OPTION_INT:
569:         sprintf(value,"%d",(int) *(PetscInt*)PetscOptionsObject->next->data);
570:         break;
571:       case OPTION_REAL:
572:         sprintf(value,"%g",(double) *(PetscReal*)PetscOptionsObject->next->data);
573:         break;
574:       case OPTION_REAL_ARRAY:
575:         sprintf(value,"%g",(double)((PetscReal*)PetscOptionsObject->next->data)[0]);
576:         for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
577:           sprintf(tmp,"%g",(double)((PetscReal*)PetscOptionsObject->next->data)[j]);
578:           PetscStrcat(value,",");
579:           PetscStrcat(value,tmp);
580:         }
581:         break;
582:       case OPTION_SCALAR_ARRAY:
583:         sprintf(value,"%g+%gi",(double)PetscRealPart(((PetscScalar*)PetscOptionsObject->next->data)[0]),(double)PetscImaginaryPart(((PetscScalar*)PetscOptionsObject->next->data)[0]));
584:         for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
585:           sprintf(tmp,"%g+%gi",(double)PetscRealPart(((PetscScalar*)PetscOptionsObject->next->data)[j]),(double)PetscImaginaryPart(((PetscScalar*)PetscOptionsObject->next->data)[j]));
586:           PetscStrcat(value,",");
587:           PetscStrcat(value,tmp);
588:         }
589:         break;
590:       case OPTION_BOOL:
591:         sprintf(value,"%d",*(int*)PetscOptionsObject->next->data);
592:         break;
593:       case OPTION_BOOL_ARRAY:
594:         sprintf(value,"%d",(int)((PetscBool*)PetscOptionsObject->next->data)[0]);
595:         for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
596:           sprintf(tmp,"%d",(int)((PetscBool*)PetscOptionsObject->next->data)[j]);
597:           PetscStrcat(value,",");
598:           PetscStrcat(value,tmp);
599:         }
600:         break;
601:       case OPTION_FLIST:
602:         PetscStrcpy(value,(char*)PetscOptionsObject->next->data);
603:         break;
604:       case OPTION_ELIST:
605:         PetscStrcpy(value,(char*)PetscOptionsObject->next->data);
606:         break;
607:       case OPTION_STRING:
608:         PetscStrcpy(value,(char*)PetscOptionsObject->next->data);
609:         break;
610:       case OPTION_STRING_ARRAY:
611:         sprintf(value,"%s",((char**)PetscOptionsObject->next->data)[0]);
612:         for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
613:           sprintf(tmp,"%s",((char**)PetscOptionsObject->next->data)[j]);
614:           PetscStrcat(value,",");
615:           PetscStrcat(value,tmp);
616:         }
617:         break;
618:       }
619:       PetscOptionsSetValue(PetscOptionsObject->options,option,value);
620:     }
621:     if (PetscOptionsObject->next->type == OPTION_ELIST) {
622:       PetscStrNArrayDestroy(PetscOptionsObject->next->nlist,(char ***)&PetscOptionsObject->next->list);
623:     }
624:     PetscFree(PetscOptionsObject->next->text);
625:     PetscFree(PetscOptionsObject->next->option);
626:     PetscFree(PetscOptionsObject->next->man);
627:     PetscFree(PetscOptionsObject->next->edata);

629:     if ((PetscOptionsObject->next->type == OPTION_STRING) || (PetscOptionsObject->next->type == OPTION_FLIST) || (PetscOptionsObject->next->type == OPTION_ELIST)){
630:       free(PetscOptionsObject->next->data);
631:     } else {
632:       PetscFree(PetscOptionsObject->next->data);
633:     }

635:     last                    = PetscOptionsObject->next;
636:     PetscOptionsObject->next = PetscOptionsObject->next->next;
637:     PetscFree(last);
638:   }
639:   PetscFree(PetscOptionsObject->prefix);
640:   PetscOptionsObject->next = NULL;
641:   return(0);
642: }

644: /*MC
645:    PetscOptionsEnum - Gets the enum value for a particular option in the database.

647:    Logically Collective on the communicator passed in PetscOptionsBegin()

649:    Synopsis:
650:    #include "petscsys.h"
651:    PetscErrorCode  PetscOptionsEnum(const char opt[],const char text[],const char man[],const char *const *list,PetscEnum currentvalue,PetscEnum *value,PetscBool  *set)

653:    Input Parameters:
654: +  opt - option name
655: .  text - short string that describes the option
656: .  man - manual page with additional information on option
657: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
658: -  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
659: $                 PetscOptionsEnum(..., obj->value,&object->value,...) or
660: $                 value = defaultvalue
661: $                 PetscOptionsEnum(..., value,&value,&flg);
662: $                 if (flg) {

664:    Output Parameter:
665: +  value - the  value to return
666: -  set - PETSC_TRUE if found, else PETSC_FALSE

668:    Level: beginner

670:    Notes:
671:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

673:           list is usually something like PCASMTypes or some other predefined list of enum names

675:           If the user does not supply the option at all value is NOT changed. Thus
676:           you should ALWAYS initialize value if you access it without first checking if the set flag is true.

678:           The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.

680: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
681:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
682:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
683:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
684:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
685:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
686:           PetscOptionsFList(), PetscOptionsEList()
687: M*/

689: PetscErrorCode  PetscOptionsEnum_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum currentvalue,PetscEnum *value,PetscBool  *set)
690: {
692:   PetscInt       ntext = 0;
693:   PetscInt       tval;
694:   PetscBool      tflg;

697:   while (list[ntext++]) {
698:     if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
699:   }
700:   if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
701:   ntext -= 3;
702:   PetscOptionsEList_Private(PetscOptionsObject,opt,text,man,list,ntext,list[currentvalue],&tval,&tflg);
703:   /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
704:   if (tflg) *value = (PetscEnum)tval;
705:   if (set)  *set   = tflg;
706:   return(0);
707: }

709: /*MC
710:    PetscOptionsEnumArray - Gets an array of enum values for a particular
711:    option in the database.

713:    Logically Collective on the communicator passed in PetscOptionsBegin()

715:    Synopsis:
716:    #include "petscsys.h"
717:    PetscErrorCode  PetscOptionsEnumArray(const char opt[],const char text[],const char man[],const char *const *list,PetscEnum value[],PetscInt *n,PetscBool  *set)

719:    Input Parameters:
720: +  opt - the option one is seeking
721: .  text - short string describing option
722: .  man - manual page for option
723: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
724: -  n - maximum number of values

726:    Output Parameter:
727: +  value - location to copy values
728: .  n - actual number of values found
729: -  set - PETSC_TRUE if found, else PETSC_FALSE

731:    Level: beginner

733:    Notes:
734:    The array must be passed as a comma separated list.

736:    There must be no intervening spaces between the values.

738:    Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

740: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
741:           PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
742:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
743:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
744:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
745:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
746: M*/

748: PetscErrorCode  PetscOptionsEnumArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum value[],PetscInt *n,PetscBool  *set)
749: {
750:   PetscInt        i,nlist = 0;
751:   PetscOptionItem amsopt;
752:   PetscErrorCode  ierr;

755:   while (list[nlist++]) if (nlist > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
756:   if (nlist < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
757:   nlist -= 3; /* drop enum name, prefix, and null termination */
758:   if (0 && !PetscOptionsObject->count) { /* XXX Requires additional support */
759:     PetscEnum *vals;
760:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT_ARRAY/*XXX OPTION_ENUM_ARRAY*/,&amsopt);
761:     PetscStrNArrayallocpy(nlist,list,(char***)&amsopt->list);
762:     amsopt->nlist = nlist;
763:     PetscMalloc1(*n,(PetscEnum**)&amsopt->data);
764:     amsopt->arraylength = *n;
765:     vals = (PetscEnum*)amsopt->data;
766:     for (i=0; i<*n; i++) vals[i] = value[i];
767:   }
768:   PetscOptionsGetEnumArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,list,value,n,set);
769:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
770:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%s",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,list[value[0]]);
771:     for (i=1; i<*n; i++) {(*PetscHelpPrintf)(PetscOptionsObject->comm,",%s",list[value[i]]);}
772:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (choose from)",text);
773:     for (i=0; i<nlist; i++) {(*PetscHelpPrintf)(PetscOptionsObject->comm," %s",list[i]);}
774:     (*PetscHelpPrintf)(PetscOptionsObject->comm," (%s)\n",ManSection(man));
775:   }
776:   return(0);
777: }

779: /*MC
780:    PetscOptionsBoundedInt - Gets an integer value greater than or equal a given bound for a particular option in the database.

782:    Logically Collective on the communicator passed in PetscOptionsBegin()

784:    Synopsis:
785:    #include "petscsys.h"
786:    PetscErrorCode  PetscOptionsBoundInt(const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *flg,PetscInt bound)

788:    Input Parameters:
789: +  opt - option name
790: .  text - short string that describes the option
791: .  man - manual page with additional information on option
792: .  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
793: $                 PetscOptionsInt(..., obj->value,&obj->value,...) or
794: $                 value = defaultvalue
795: $                 PetscOptionsInt(..., value,&value,&flg);
796: $                 if (flg) {
797: -  bound - the requested value should be greater than or equal this bound or an error is generated

799:    Output Parameter:
800: +  value - the integer value to return
801: -  flg - PETSC_TRUE if found, else PETSC_FALSE

803:    Notes:
804:     If the user does not supply the option at all value is NOT changed. Thus
805:     you should ALWAYS initialize value if you access it without first checking if the set flag is true.

807:     The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.

809:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

811:    Level: beginner

813: .seealso: PetscOptionsInt(), PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
814:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(), PetscOptionsRangeInt()
815:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
816:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
817:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
818:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
819:           PetscOptionsFList(), PetscOptionsEList()
820: M*/

822: /*MC
823:    PetscOptionsRangeInt - Gets an integer value within a range of values for a particular option in the database.

825:    Logically Collective on the communicator passed in PetscOptionsBegin()

827:    Synopsis:
828:    #include "petscsys.h"
829: PetscErrorCode  PetscOptionsRangeInt(const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *flg,PetscInt lb,PetscInt ub)

831:    Input Parameters:
832: +  opt - option name
833: .  text - short string that describes the option
834: .  man - manual page with additional information on option
835: .  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
836: $                 PetscOptionsInt(..., obj->value,&obj->value,...) or
837: $                 value = defaultvalue
838: $                 PetscOptionsInt(..., value,&value,&flg);
839: $                 if (flg) {
840: .  lb - the lower bound, provided value must be greater than or equal to this value or an error is generated
841: -  ub - the upper bound, provided value must be less than or equal to this value or an error is generated

843:    Output Parameter:
844: +  value - the integer value to return
845: -  flg - PETSC_TRUE if found, else PETSC_FALSE

847:    Notes:
848:     If the user does not supply the option at all value is NOT changed. Thus
849:     you should ALWAYS initialize value if you access it without first checking if the set flag is true.

851:     The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.

853:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

855:    Level: beginner

857: .seealso: PetscOptionsInt(), PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
858:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(), PetscOptionsBoundedInt()
859:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
860:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
861:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
862:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
863:           PetscOptionsFList(), PetscOptionsEList()
864: M*/

866: /*MC
867:    PetscOptionsInt - Gets the integer value for a particular option in the database.

869:    Logically Collective on the communicator passed in PetscOptionsBegin()

871:    Synopsis:
872:    #include "petscsys.h"
873: PetscErrorCode  PetscOptionsInt(const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *flg))


876:    Input Parameters:
877: +  opt - option name
878: .  text - short string that describes the option
879: .  man - manual page with additional information on option
880: -  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
881: $                 PetscOptionsInt(..., obj->value,&obj->value,...) or
882: $                 value = defaultvalue
883: $                 PetscOptionsInt(..., value,&value,&flg);
884: $                 if (flg) {

886:    Output Parameter:
887: +  value - the integer value to return
888: -  flg - PETSC_TRUE if found, else PETSC_FALSE

890:    Notes:
891:     If the user does not supply the option at all value is NOT changed. Thus
892:     you should ALWAYS initialize value if you access it without first checking if the set flag is true.

894:     The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.

896:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

898:    Level: beginner

900: .seealso: PetscOptionsBoundedInt(), PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
901:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(), PetscOptionsRangeInt()
902:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
903:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
904:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
905:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
906:           PetscOptionsFList(), PetscOptionsEList()
907: M*/

909: PetscErrorCode  PetscOptionsInt_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool  *set,PetscInt lb,PetscInt ub)
910: {
911:   PetscErrorCode  ierr;
912:   PetscOptionItem amsopt;
913:   PetscBool       wasset;

916:   if (currentvalue < lb) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Current value %D less than allowed bound %D",currentvalue,lb);
917:   if (currentvalue > ub) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Current value %D greater than allowed bound %D",currentvalue,ub);
918:      if (!PetscOptionsObject->count) {
919:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT,&amsopt);
920:     PetscMalloc(sizeof(PetscInt),&amsopt->data);
921:     *(PetscInt*)amsopt->data = currentvalue;

923:     PetscOptionsGetInt(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,&currentvalue,&wasset);
924:     if (wasset) {
925:       *(PetscInt*)amsopt->data = currentvalue;
926:     }
927:   }
928:   PetscOptionsGetInt(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,&wasset);
929:   if (wasset && *value < lb) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Newly set value %D less than allowed bound %D",*value,lb);
930:   if (wasset && *value > ub) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Newly set value %D greater than allowed bound %D",*value,ub);
931:   if (set) *set = wasset;
932:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
933:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <now %D : formerly %D>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,wasset && value ? *value : currentvalue,currentvalue,text,ManSection(man));
934:   }
935:   return(0);
936: }

938: /*MC
939:    PetscOptionsString - Gets the string value for a particular option in the database.

941:    Logically Collective on the communicator passed in PetscOptionsBegin()

943:    Synopsis:
944:    #include "petscsys.h"
945:    PetscErrorCode  PetscOptionsString(const char opt[],const char text[],const char man[],const char currentvalue[],char value[],size_t len,PetscBool  *set)

947:    Input Parameters:
948: +  opt - option name
949: .  text - short string that describes the option
950: .  man - manual page with additional information on option
951: .  currentvalue - the current value; caller is responsible for setting this value correctly. This is not used to set value
952: -  len - length of the result string including null terminator

954:    Output Parameter:
955: +  value - the value to return
956: -  flg - PETSC_TRUE if found, else PETSC_FALSE

958:    Level: beginner

960:    Notes:
961:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

963:    Even if the user provided no string (for example -optionname -someotheroption) the flag is set to PETSC_TRUE (and the string is fulled with nulls).

965:           If the user does not supply the option at all value is NOT changed. Thus
966:           you should ALWAYS initialize value if you access it without first checking if the set flag is true.

968:           The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.


971: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
972:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
973:           PetscOptionsInt(), PetscOptionsReal(), PetscOptionsBool(),
974:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
975:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
976:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
977:           PetscOptionsFList(), PetscOptionsEList()
978: M*/

980: PetscErrorCode  PetscOptionsString_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char currentvalue[],char value[],size_t len,PetscBool  *set)
981: {
982:   PetscErrorCode  ierr;
983:   PetscOptionItem amsopt;
984:   PetscBool       lset;

987:   if (!PetscOptionsObject->count) {
988:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
989:     /* must use system malloc since SAWs may free this */
990:     PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
991:   }
992:   PetscOptionsGetString(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,len,&lset);
993:   if (set) *set = lset;
994:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
995:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <now %s : formerly %s>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,lset && value ? value : currentvalue,currentvalue,text,ManSection(man));
996:   }
997:   return(0);
998: }

1000: /*MC
1001:    PetscOptionsReal - Gets the PetscReal value for a particular option in the database.

1003:    Logically Collective on the communicator passed in PetscOptionsBegin()

1005:    Synopsis:
1006:    #include "petscsys.h"
1007:    PetscErrorCode  PetscOptionsReal(const char opt[],const char text[],const char man[],PetscReal currentvalue,PetscReal *value,PetscBool  *set)

1009:    Input Parameters:
1010: +  opt - option name
1011: .  text - short string that describes the option
1012: .  man - manual page with additional information on option
1013: -  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
1014: $                 PetscOptionsReal(..., obj->value,&obj->value,...) or
1015: $                 value = defaultvalue
1016: $                 PetscOptionsReal(..., value,&value,&flg);
1017: $                 if (flg) {

1019:    Output Parameter:
1020: +  value - the value to return
1021: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1023:    Notes:
1024:     If the user does not supply the option at all value is NOT changed. Thus
1025:     you should ALWAYS initialize value if you access it without first checking if the set flag is true.

1027:     The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.

1029:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

1031:    Level: beginner

1033: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1034:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1035:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1036:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1037:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1038:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1039:           PetscOptionsFList(), PetscOptionsEList()
1040: M*/

1042: PetscErrorCode  PetscOptionsReal_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal currentvalue,PetscReal *value,PetscBool  *set)
1043: {
1044:   PetscErrorCode  ierr;
1045:   PetscOptionItem amsopt;
1046:   PetscBool       lset;

1049:   if (!PetscOptionsObject->count) {
1050:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL,&amsopt);
1051:     PetscMalloc(sizeof(PetscReal),&amsopt->data);

1053:     *(PetscReal*)amsopt->data = currentvalue;
1054:   }
1055:   PetscOptionsGetReal(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,&lset);
1056:   if (set) *set = lset;
1057:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1058:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%g : %g>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,lset && value ? (double)*value : (double) currentvalue,(double)currentvalue,text,ManSection(man));
1059:   }
1060:   return(0);
1061: }

1063: /*MC
1064:    PetscOptionsScalar - Gets the scalar value for a particular option in the database.

1066:    Logically Collective on the communicator passed in PetscOptionsBegin()

1068:    Synopsis:
1069:    #include "petscsys.h"
1070:    PetscErrorCode PetscOptionsScalar(const char opt[],const char text[],const char man[],PetscScalar currentvalue,PetscScalar *value,PetscBool  *set)

1072:    Input Parameters:
1073: +  opt - option name
1074: .  text - short string that describes the option
1075: .  man - manual page with additional information on option
1076: -  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
1077: $                 PetscOptionsScalar(..., obj->value,&obj->value,...) or
1078: $                 value = defaultvalue
1079: $                 PetscOptionsScalar(..., value,&value,&flg);
1080: $                 if (flg) {


1083:    Output Parameter:
1084: +  value - the value to return
1085: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1087:    Notes:
1088:     If the user does not supply the option at all value is NOT changed. Thus
1089:     you should ALWAYS initialize value if you access it without first checking if the set flag is true.

1091:     The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.

1093:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

1095:    Level: beginner

1097: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1098:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1099:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1100:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1101:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1102:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1103:           PetscOptionsFList(), PetscOptionsEList()
1104: M*/

1106: PetscErrorCode  PetscOptionsScalar_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar currentvalue,PetscScalar *value,PetscBool  *set)
1107: {

1111: #if !defined(PETSC_USE_COMPLEX)
1112:   PetscOptionsReal(opt,text,man,currentvalue,value,set);
1113: #else
1114:   PetscOptionsGetScalar(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,set);
1115: #endif
1116:   return(0);
1117: }

1119: /*MC
1120:    PetscOptionsName - Determines if a particular option has been set in the database. This returns true whether the option is a number, string or boolean, even
1121:                       its value is set to false.

1123:    Logically Collective on the communicator passed in PetscOptionsBegin()

1125:    Synopsis:
1126:    #include "petscsys.h"
1127:    PetscErrorCode PetscOptionsName(const char opt[],const char text[],const char man[],PetscBool  *flg)

1129:    Input Parameters:
1130: +  opt - option name
1131: .  text - short string that describes the option
1132: -  man - manual page with additional information on option

1134:    Output Parameter:
1135: .  flg - PETSC_TRUE if found, else PETSC_FALSE

1137:    Level: beginner

1139:    Notes:
1140:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

1142: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1143:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1144:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1145:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1146:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1147:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1148:           PetscOptionsFList(), PetscOptionsEList()
1149: M*/

1151: PetscErrorCode  PetscOptionsName_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
1152: {
1153:   PetscErrorCode  ierr;
1154:   PetscOptionItem amsopt;

1157:   if (!PetscOptionsObject->count) {
1158:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1159:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1161:     *(PetscBool*)amsopt->data = PETSC_FALSE;
1162:   }
1163:   PetscOptionsHasName(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg);
1164:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1165:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1166:   }
1167:   return(0);
1168: }

1170: /*MC
1171:      PetscOptionsFList - Puts a list of option values that a single one may be selected from

1173:    Logically Collective on the communicator passed in PetscOptionsBegin()

1175:    Synopsis:
1176:    #include "petscsys.h"
1177:    PetscErrorCode  PetscOptionsFList(const char opt[],const char ltext[],const char man[],PetscFunctionList list,const char currentvalue[],char value[],size_t len,PetscBool  *set)

1179:    Input Parameters:
1180: +  opt - option name
1181: .  text - short string that describes the option
1182: .  man - manual page with additional information on option
1183: .  list - the possible choices
1184: .  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1185: $                 PetscOptionsFlist(..., obj->value,value,len,&flg);
1186: $                 if (flg) {
1187: -  len - the length of the character array value

1189:    Output Parameter:
1190: +  value - the value to return
1191: -  set - PETSC_TRUE if found, else PETSC_FALSE

1193:    Level: intermediate

1195:    Notes:
1196:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

1198:           If the user does not supply the option at all value is NOT changed. Thus
1199:           you should ALWAYS initialize value if you access it without first checking if the set flag is true.

1201:           The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.

1203:    See PetscOptionsEList() for when the choices are given in a string array

1205:    To get a listing of all currently specified options,
1206:     see PetscOptionsView() or PetscOptionsGetAll()

1208:    Developer Note: This cannot check for invalid selection because of things like MATAIJ that are not included in the list

1210: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1211:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1212:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1213:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1214:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1215:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsEnum()
1216: M*/

1218: PetscErrorCode  PetscOptionsFList_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char ltext[],const char man[],PetscFunctionList list,const char currentvalue[],char value[],size_t len,PetscBool  *set)
1219: {
1220:   PetscErrorCode  ierr;
1221:   PetscOptionItem amsopt;
1222:   PetscBool       lset;

1225:   if (!PetscOptionsObject->count) {
1226:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_FLIST,&amsopt);
1227:     /* must use system malloc since SAWs may free this */
1228:     PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
1229:     amsopt->flist = list;
1230:   }
1231:   PetscOptionsGetString(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,len,&lset);
1232:   if (set) *set = lset;
1233:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1234:     PetscFunctionListPrintTypes(PetscOptionsObject->comm,stdout,PetscOptionsObject->prefix,opt,ltext,man,list,currentvalue,lset && value ? value : currentvalue);
1235:   }
1236:   return(0);
1237: }

1239: /*MC
1240:      PetscOptionsEList - Puts a list of option values that a single one may be selected from

1242:    Logically Collective on the communicator passed in PetscOptionsBegin()

1244:    Synopsis:
1245:    #include "petscsys.h"
1246:    PetscErrorCode  PetscOptionsEList(const char opt[],const char ltext[],const char man[],const char *const *list,PetscInt ntext,const char currentvalue[],PetscInt *value,PetscBool  *set)

1248:    Input Parameters:
1249: +  opt - option name
1250: .  ltext - short string that describes the option
1251: .  man - manual page with additional information on option
1252: .  list - the possible choices (one of these must be selected, anything else is invalid)
1253: .  ntext - number of choices
1254: -  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1255: $                 PetscOptionsElist(..., obj->value,&value,&flg);
1256: $                 if (flg) {


1259:    Output Parameter:
1260: +  value - the index of the value to return
1261: -  set - PETSC_TRUE if found, else PETSC_FALSE

1263:    Level: intermediate

1265:    Notes:
1266:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

1268:          If the user does not supply the option at all value is NOT changed. Thus
1269:           you should ALWAYS initialize value if you access it without first checking if the set flag is true.

1271:    See PetscOptionsFList() for when the choices are given in a PetscFunctionList()

1273: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1274:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1275:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1276:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1277:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1278:           PetscOptionsFList(), PetscOptionsEnum()
1279: M*/

1281: PetscErrorCode  PetscOptionsEList_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char ltext[],const char man[],const char *const *list,PetscInt ntext,const char currentvalue[],PetscInt *value,PetscBool  *set)
1282: {
1283:   PetscErrorCode  ierr;
1284:   PetscInt        i;
1285:   PetscOptionItem amsopt;
1286:   PetscBool       lset;

1289:   if (!PetscOptionsObject->count) {
1290:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_ELIST,&amsopt);
1291:     /* must use system malloc since SAWs may free this */
1292:     PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
1293:     PetscStrNArrayallocpy(ntext,list,(char***)&amsopt->list);
1294:     amsopt->nlist = ntext;
1295:   }
1296:   PetscOptionsGetEList(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,list,ntext,value,&lset);
1297:   if (set) *set = lset;
1298:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1299:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <now %s : formerly %s> %s (choose one of)",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,lset && value ? list[*value] : currentvalue,currentvalue,ltext);
1300:     for (i=0; i<ntext; i++) {
1301:       (*PetscHelpPrintf)(PetscOptionsObject->comm," %s",list[i]);
1302:     }
1303:     (*PetscHelpPrintf)(PetscOptionsObject->comm," (%s)\n",ManSection(man));
1304:   }
1305:   return(0);
1306: }

1308: /*MC
1309:      PetscOptionsBoolGroupBegin - First in a series of logical queries on the options database for
1310:        which at most a single value can be true.

1312:    Logically Collective on the communicator passed in PetscOptionsBegin()

1314:    Synopsis:
1315:    #include "petscsys.h"
1316:    PetscErrorCode PetscOptionsBoolGroupBegin(const char opt[],const char text[],const char man[],PetscBool  *flg)

1318:    Input Parameters:
1319: +  opt - option name
1320: .  text - short string that describes the option
1321: -  man - manual page with additional information on option

1323:    Output Parameter:
1324: .  flg - whether that option was set or not

1326:    Level: intermediate

1328:    Notes:
1329:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

1331:    Must be followed by 0 or more PetscOptionsBoolGroup()s and PetscOptionsBoolGroupEnd()

1333: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1334:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1335:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1336:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1337:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1338:           PetscOptionsFList(), PetscOptionsEList()
1339: M*/

1341: PetscErrorCode  PetscOptionsBoolGroupBegin_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
1342: {
1343:   PetscErrorCode  ierr;
1344:   PetscOptionItem amsopt;

1347:   if (!PetscOptionsObject->count) {
1348:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1349:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1351:     *(PetscBool*)amsopt->data = PETSC_FALSE;
1352:   }
1353:   *flg = PETSC_FALSE;
1354:   PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1355:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1356:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  Pick at most one of -------------\n");
1357:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"    -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1358:   }
1359:   return(0);
1360: }

1362: /*MC
1363:      PetscOptionsBoolGroup - One in a series of logical queries on the options database for
1364:        which at most a single value can be true.

1366:    Logically Collective on the communicator passed in PetscOptionsBegin()

1368:    Synopsis:
1369:    #include "petscsys.h"
1370:    PetscErrorCode PetscOptionsBoolGroup(const char opt[],const char text[],const char man[],PetscBool  *flg)

1372:    Input Parameters:
1373: +  opt - option name
1374: .  text - short string that describes the option
1375: -  man - manual page with additional information on option

1377:    Output Parameter:
1378: .  flg - PETSC_TRUE if found, else PETSC_FALSE

1380:    Level: intermediate

1382:    Notes:
1383:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

1385:    Must follow a PetscOptionsBoolGroupBegin() and preceded a PetscOptionsBoolGroupEnd()

1387: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1388:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1389:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1390:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1391:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1392:           PetscOptionsFList(), PetscOptionsEList()
1393: M*/

1395: PetscErrorCode  PetscOptionsBoolGroup_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
1396: {
1397:   PetscErrorCode  ierr;
1398:   PetscOptionItem amsopt;

1401:   if (!PetscOptionsObject->count) {
1402:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1403:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1405:     *(PetscBool*)amsopt->data = PETSC_FALSE;
1406:   }
1407:   *flg = PETSC_FALSE;
1408:   PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1409:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1410:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"    -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1411:   }
1412:   return(0);
1413: }

1415: /*MC
1416:      PetscOptionsBoolGroupEnd - Last in a series of logical queries on the options database for
1417:        which at most a single value can be true.

1419:    Logically Collective on the communicator passed in PetscOptionsBegin()

1421:    Synopsis:
1422:    #include "petscsys.h"
1423:    PetscErrorCode PetscOptionsBoolGroupEnd(const char opt[],const char text[],const char man[],PetscBool  *flg)

1425:    Input Parameters:
1426: +  opt - option name
1427: .  text - short string that describes the option
1428: -  man - manual page with additional information on option

1430:    Output Parameter:
1431: .  flg - PETSC_TRUE if found, else PETSC_FALSE

1433:    Level: intermediate

1435:    Notes:
1436:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

1438:    Must follow a PetscOptionsBoolGroupBegin()

1440: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1441:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1442:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1443:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1444:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1445:           PetscOptionsFList(), PetscOptionsEList()
1446: M*/

1448: PetscErrorCode  PetscOptionsBoolGroupEnd_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
1449: {
1450:   PetscErrorCode  ierr;
1451:   PetscOptionItem amsopt;

1454:   if (!PetscOptionsObject->count) {
1455:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1456:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1458:     *(PetscBool*)amsopt->data = PETSC_FALSE;
1459:   }
1460:   *flg = PETSC_FALSE;
1461:   PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1462:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1463:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"    -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1464:   }
1465:   return(0);
1466: }

1468: /*MC
1469:    PetscOptionsBool - Determines if a particular option is in the database with a true or false

1471:    Logically Collective on the communicator passed in PetscOptionsBegin()

1473:    Synopsis:
1474:    #include "petscsys.h"
1475:    PetscErrorCode PetscOptionsBool(const char opt[],const char text[],const char man[],PetscBool currentvalue,PetscBool  *flg,PetscBool  *set)

1477:    Input Parameters:
1478: +  opt - option name
1479: .  text - short string that describes the option
1480: .  man - manual page with additional information on option
1481: -  currentvalue - the current value

1483:    Output Parameter:
1484: +  flg - PETSC_TRUE or PETSC_FALSE
1485: -  set - PETSC_TRUE if found, else PETSC_FALSE

1487:    Notes:
1488:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1489:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

1491:       If the option is given, but no value is provided, then flg and set are both given the value PETSC_TRUE. That is -requested_bool
1492:      is equivalent to -requested_bool true

1494:        If the user does not supply the option at all flg is NOT changed. Thus
1495:      you should ALWAYS initialize the flg if you access it without first checking if the set flag is true.

1497:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

1499:    Level: beginner

1501: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1502:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1503:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1504:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1505:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1506:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1507:           PetscOptionsFList(), PetscOptionsEList()
1508: M*/

1510: PetscErrorCode  PetscOptionsBool_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool currentvalue,PetscBool  *flg,PetscBool  *set)
1511: {
1512:   PetscErrorCode  ierr;
1513:   PetscBool       iset;
1514:   PetscOptionItem amsopt;

1517:   if (!PetscOptionsObject->count) {
1518:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1519:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1521:     *(PetscBool*)amsopt->data = currentvalue;
1522:   }
1523:   PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,&iset);
1524:   if (set) *set = iset;
1525:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1526:     const char *v = PetscBools[currentvalue], *vn = PetscBools[iset && flg ? *flg : currentvalue];
1527:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s: <%s : %s> %s (%s)\n",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,v,vn,text,ManSection(man));
1528:   }
1529:   return(0);
1530: }

1532: /*MC
1533:    PetscOptionsRealArray - Gets an array of double values for a particular
1534:    option in the database. The values must be separated with commas with
1535:    no intervening spaces.

1537:    Logically Collective on the communicator passed in PetscOptionsBegin()

1539:    Synopsis:
1540:    #include "petscsys.h"
1541:    PetscErrorCode PetscOptionsRealArray(const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool  *set)

1543:    Input Parameters:
1544: +  opt - the option one is seeking
1545: .  text - short string describing option
1546: .  man - manual page for option
1547: -  nmax - maximum number of values

1549:    Output Parameter:
1550: +  value - location to copy values
1551: .  nmax - actual number of values found
1552: -  set - PETSC_TRUE if found, else PETSC_FALSE

1554:    Level: beginner

1556:    Notes:
1557:    The user should pass in an array of doubles

1559:    Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

1561: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1562:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1563:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1564:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1565:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1566:           PetscOptionsFList(), PetscOptionsEList()
1567: M*/

1569: PetscErrorCode PetscOptionsRealArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool  *set)
1570: {
1571:   PetscErrorCode  ierr;
1572:   PetscInt        i;
1573:   PetscOptionItem amsopt;

1576:   if (!PetscOptionsObject->count) {
1577:     PetscReal *vals;

1579:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL_ARRAY,&amsopt);
1580:     PetscMalloc((*n)*sizeof(PetscReal),&amsopt->data);
1581:     vals = (PetscReal*)amsopt->data;
1582:     for (i=0; i<*n; i++) vals[i] = value[i];
1583:     amsopt->arraylength = *n;
1584:   }
1585:   PetscOptionsGetRealArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1586:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1587:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%g",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)value[0]);
1588:     for (i=1; i<*n; i++) {
1589:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g",(double)value[i]);
1590:     }
1591:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1592:   }
1593:   return(0);
1594: }

1596: /*MC
1597:    PetscOptionsScalarArray - Gets an array of Scalar values for a particular
1598:    option in the database. The values must be separated with commas with
1599:    no intervening spaces.

1601:    Logically Collective on the communicator passed in PetscOptionsBegin()

1603:    Synopsis:
1604:    #include "petscsys.h"
1605:    PetscErrorCode PetscOptionsScalarArray(const char opt[],const char text[],const char man[],PetscScalar value[],PetscInt *n,PetscBool  *set)

1607:    Input Parameters:
1608: +  opt - the option one is seeking
1609: .  text - short string describing option
1610: .  man - manual page for option
1611: -  nmax - maximum number of values

1613:    Output Parameter:
1614: +  value - location to copy values
1615: .  nmax - actual number of values found
1616: -  set - PETSC_TRUE if found, else PETSC_FALSE

1618:    Level: beginner

1620:    Notes:
1621:    The user should pass in an array of doubles

1623:    Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

1625: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1626:           PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1627:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1628:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1629:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1630:           PetscOptionsFList(), PetscOptionsEList()
1631: M*/

1633: PetscErrorCode PetscOptionsScalarArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar value[],PetscInt *n,PetscBool  *set)
1634: {
1635:   PetscErrorCode  ierr;
1636:   PetscInt        i;
1637:   PetscOptionItem amsopt;

1640:   if (!PetscOptionsObject->count) {
1641:     PetscScalar *vals;

1643:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_SCALAR_ARRAY,&amsopt);
1644:     PetscMalloc((*n)*sizeof(PetscScalar),&amsopt->data);
1645:     vals = (PetscScalar*)amsopt->data;
1646:     for (i=0; i<*n; i++) vals[i] = value[i];
1647:     amsopt->arraylength = *n;
1648:   }
1649:   PetscOptionsGetScalarArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1650:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1651:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%g+%gi",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)PetscRealPart(value[0]),(double)PetscImaginaryPart(value[0]));
1652:     for (i=1; i<*n; i++) {
1653:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g+%gi",(double)PetscRealPart(value[i]),(double)PetscImaginaryPart(value[i]));
1654:     }
1655:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1656:   }
1657:   return(0);
1658: }

1660: /*MC
1661:    PetscOptionsIntArray - Gets an array of integers for a particular
1662:    option in the database.

1664:    Logically Collective on the communicator passed in PetscOptionsBegin()

1666:    Synopsis:
1667:    #include "petscsys.h"
1668:    PetscErrorCode PetscOptionsIntArray(const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool  *set)

1670:    Input Parameters:
1671: +  opt - the option one is seeking
1672: .  text - short string describing option
1673: .  man - manual page for option
1674: -  n - maximum number of values

1676:    Output Parameter:
1677: +  value - location to copy values
1678: .  n - actual number of values found
1679: -  set - PETSC_TRUE if found, else PETSC_FALSE

1681:    Level: beginner

1683:    Notes:
1684:    The array can be passed as
1685:    a comma separated list:                                 0,1,2,3,4,5,6,7
1686:    a range (start-end+1):                                  0-8
1687:    a range with given increment (start-end+1:inc):         0-7:2
1688:    a combination of values and ranges separated by commas: 0,1-8,8-15:2

1690:    There must be no intervening spaces between the values.

1692:    Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

1694: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1695:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1696:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1697:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1698:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1699:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
1700: M*/

1702: PetscErrorCode  PetscOptionsIntArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool  *set)
1703: {
1705:   PetscInt        i;
1706:   PetscOptionItem amsopt;

1709:   if (!PetscOptionsObject->count) {
1710:     PetscInt *vals;

1712:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT_ARRAY,&amsopt);
1713:     PetscMalloc1(*n,(PetscInt**)&amsopt->data);
1714:     vals = (PetscInt*)amsopt->data;
1715:     for (i=0; i<*n; i++) vals[i] = value[i];
1716:     amsopt->arraylength = *n;
1717:   }
1718:   PetscOptionsGetIntArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1719:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1720:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%d",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
1721:     for (i=1; i<*n; i++) {
1722:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%d",value[i]);
1723:     }
1724:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1725:   }
1726:   return(0);
1727: }

1729: /*MC
1730:    PetscOptionsStringArray - Gets an array of string values for a particular
1731:    option in the database. The values must be separated with commas with
1732:    no intervening spaces.

1734:    Logically Collective on the communicator passed in PetscOptionsBegin()

1736:    Synopsis:
1737:    #include "petscsys.h"
1738:    PetscErrorCode PetscOptionsStringArray(const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool  *set)

1740:    Input Parameters:
1741: +  opt - the option one is seeking
1742: .  text - short string describing option
1743: .  man - manual page for option
1744: -  nmax - maximum number of strings

1746:    Output Parameter:
1747: +  value - location to copy strings
1748: .  nmax - actual number of strings found
1749: -  set - PETSC_TRUE if found, else PETSC_FALSE

1751:    Level: beginner

1753:    Notes:
1754:    The user should pass in an array of pointers to char, to hold all the
1755:    strings returned by this function.

1757:    The user is responsible for deallocating the strings that are
1758:    returned. The Fortran interface for this routine is not supported.

1760:    Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

1762: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1763:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1764:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1765:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1766:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1767:           PetscOptionsFList(), PetscOptionsEList()
1768: M*/

1770: PetscErrorCode  PetscOptionsStringArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool  *set)
1771: {
1772:   PetscErrorCode  ierr;
1773:   PetscOptionItem amsopt;

1776:   if (!PetscOptionsObject->count) {
1777:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING_ARRAY,&amsopt);
1778:     PetscMalloc1(*nmax,(char**)&amsopt->data);

1780:     amsopt->arraylength = *nmax;
1781:   }
1782:   PetscOptionsGetStringArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,nmax,set);
1783:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1784:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1785:   }
1786:   return(0);
1787: }

1789: /*MC
1790:    PetscOptionsBoolArray - Gets an array of logical values (true or false) for a particular
1791:    option in the database. The values must be separated with commas with
1792:    no intervening spaces.

1794:    Logically Collective on the communicator passed in PetscOptionsBegin()

1796:    Synopsis:
1797:    #include "petscsys.h"
1798:    PetscErrorCode PetscOptionsBoolArray(const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)

1800:    Input Parameters:
1801: +  opt - the option one is seeking
1802: .  text - short string describing option
1803: .  man - manual page for option
1804: -  nmax - maximum number of values

1806:    Output Parameter:
1807: +  value - location to copy values
1808: .  nmax - actual number of values found
1809: -  set - PETSC_TRUE if found, else PETSC_FALSE

1811:    Level: beginner

1813:    Notes:
1814:    The user should pass in an array of doubles

1816:    Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

1818: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1819:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1820:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1821:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1822:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1823:           PetscOptionsFList(), PetscOptionsEList()
1824: M*/

1826: PetscErrorCode  PetscOptionsBoolArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)
1827: {
1828:   PetscErrorCode   ierr;
1829:   PetscInt         i;
1830:   PetscOptionItem  amsopt;

1833:   if (!PetscOptionsObject->count) {
1834:     PetscBool *vals;

1836:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL_ARRAY,&amsopt);
1837:     PetscMalloc1(*n,(PetscBool**)&amsopt->data);
1838:     vals = (PetscBool*)amsopt->data;
1839:     for (i=0; i<*n; i++) vals[i] = value[i];
1840:     amsopt->arraylength = *n;
1841:   }
1842:   PetscOptionsGetBoolArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1843:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1844:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%d",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
1845:     for (i=1; i<*n; i++) {
1846:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%d",value[i]);
1847:     }
1848:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1849:   }
1850:   return(0);
1851: }

1853: /*MC
1854:    PetscOptionsViewer - Gets a viewer appropriate for the type indicated by the user

1856:    Logically Collective on the communicator passed in PetscOptionsBegin()

1858:    Synopsis:
1859:    #include "petscsys.h"
1860:    PetscErrorCode PetscOptionsViewer(const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool  *set)

1862:    Input Parameters:
1863: +  opt - option name
1864: .  text - short string that describes the option
1865: -  man - manual page with additional information on option

1867:    Output Parameter:
1868: +  viewer - the viewer
1869: -  set - PETSC_TRUE if found, else PETSC_FALSE

1871:    Level: beginner

1873:    Notes:
1874:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

1876:    See PetscOptionsGetViewer() for the format of the supplied viewer and its options

1878: .seealso: PetscOptionsGetViewer(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1879:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1880:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1881:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1882:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1883:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1884:           PetscOptionsFList(), PetscOptionsEList()
1885: M*/

1887: PetscErrorCode  PetscOptionsViewer_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool  *set)
1888: {
1889:   PetscErrorCode  ierr;
1890:   PetscOptionItem amsopt;

1893:   if (!PetscOptionsObject->count) {
1894:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
1895:     /* must use system malloc since SAWs may free this */
1896:     PetscStrdup("",(char**)&amsopt->data);
1897:   }
1898:   PetscOptionsGetViewer(PetscOptionsObject->comm,PetscOptionsObject->options,PetscOptionsObject->prefix,opt,viewer,format,set);
1899:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1900:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%s>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,"",text,ManSection(man));
1901:   }
1902:   return(0);
1903: }

1905: /*@C
1906:      PetscOptionsHead - Puts a heading before listing any more published options. Used, for example,
1907:             in KSPSetFromOptions_GMRES().

1909:    Logically Collective on the communicator passed in PetscOptionsBegin()

1911:    Input Parameter:
1912: .   head - the heading text


1915:    Level: intermediate

1917:    Notes:
1918:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd(), and PetscOptionsObject created in PetscOptionsBegin() should be the first argument

1920:           Can be followed by a call to PetscOptionsTail() in the same function.

1922: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1923:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1924:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1925:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1926:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1927:           PetscOptionsFList(), PetscOptionsEList()
1928: @*/
1929: PetscErrorCode  PetscOptionsHead(PetscOptionItems *PetscOptionsObject,const char head[])
1930: {

1934:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1935:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  %s\n",head);
1936:   }
1937:   return(0);
1938: }