Actual source code: aoptions.c


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

  6: */

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

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

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

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

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

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

 41:   PetscStrallocpy(prefix,&PetscOptionsObject->prefix);
 42:   PetscStrallocpy(title,&PetscOptionsObject->title);

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

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

 64:   PetscOptionsObject->object         = obj;
 65:   PetscOptionsObject->alreadyprinted = obj->optionsprinted;

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

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

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

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

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

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

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

112:     Collective

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

119:     Bugs:
120: .   Assumes process 0 of the given communicator has access to stdin

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

362: #if defined(PETSC_HAVE_SAWS)
363: #include <petscviewersaws.h>

365: static int count = 0;

367: PetscErrorCode PetscOptionsSAWsDestroy(void)
368: {
370:   return(0);
371: }

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

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

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

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

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

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

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

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

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

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

488:   /* wait until accessor has unlocked the memory */
489:   PetscStackCallSAWs(SAWs_Push_Header,("index.html",OptionsHeader));
490:   PetscStackCallSAWs(SAWs_Push_Body,("index.html",2,OptionsBodyBottom));
491:   PetscSAWsBlock();
492:   PetscStackCallSAWs(SAWs_Pop_Header,("index.html"));
493:   PetscStackCallSAWs(SAWs_Pop_Body,("index.html",2));

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

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

506:   if (stopasking) {
507:     PetscOptionsPublish      = PETSC_FALSE;
508:     PetscOptionsObject->count = 0;//do not ask for same thing again
509:   }

511:   PetscStackCallSAWs(SAWs_Delete,("/PETSc/Options"));
512:   return(0);
513: }
514: #endif

516: PetscErrorCode PetscOptionsEnd_Private(PetscOptionItems *PetscOptionsObject)
517: {
518:   PetscErrorCode  ierr;
519:   PetscOptionItem last;
520:   char            option[256],value[1024],tmp[32];
521:   size_t          j;

524:   if (PetscOptionsObject->next) {
525:     if (!PetscOptionsObject->count) {
526: #if defined(PETSC_HAVE_SAWS)
527:       PetscOptionsSAWsInput(PetscOptionsObject);
528: #else
529:       PetscOptionsGetFromTextInput(PetscOptionsObject);
530: #endif
531:     }
532:   }

534:   PetscFree(PetscOptionsObject->title);

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

543:   while (PetscOptionsObject->next) {
544:     if (PetscOptionsObject->next->set) {
545:       if (PetscOptionsObject->prefix) {
546:         PetscStrcpy(option,"-");
547:         PetscStrcat(option,PetscOptionsObject->prefix);
548:         PetscStrcat(option,PetscOptionsObject->next->option+1);
549:       } else {
550:         PetscStrcpy(option,PetscOptionsObject->next->option);
551:       }

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

625:     if ((PetscOptionsObject->next->type == OPTION_STRING) || (PetscOptionsObject->next->type == OPTION_FLIST) || (PetscOptionsObject->next->type == OPTION_ELIST)) {
626:       free(PetscOptionsObject->next->data);
627:     } else {
628:       PetscFree(PetscOptionsObject->next->data);
629:     }

631:     last                    = PetscOptionsObject->next;
632:     PetscOptionsObject->next = PetscOptionsObject->next->next;
633:     PetscFree(last);
634:   }
635:   PetscFree(PetscOptionsObject->prefix);
636:   PetscOptionsObject->next = NULL;
637:   return(0);
638: }

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

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

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

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

660:    Output Parameter:
661: +  value - the  value to return
662: -  set - PETSC_TRUE if found, else PETSC_FALSE

664:    Level: beginner

666:    Notes:
667:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

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

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

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

676: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
677:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
678:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
679:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
680:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
681:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
682:           PetscOptionsFList(), PetscOptionsEList()
683: M*/

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

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

705: /*MC
706:    PetscOptionsEnumArray - Gets an array of enum values for a particular
707:    option in the database.

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

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

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

722:    Output Parameter:
723: +  value - location to copy values
724: .  n - actual number of values found
725: -  set - PETSC_TRUE if found, else PETSC_FALSE

727:    Level: beginner

729:    Notes:
730:    The array must be passed as a comma separated list.

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

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

736: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
737:           PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
738:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
739:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
740:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
741:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
742: M*/

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

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

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

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

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

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

795:    Output Parameter:
796: +  value - the integer value to return
797: -  flg - PETSC_TRUE if found, else PETSC_FALSE

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

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

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

807:    Level: beginner

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

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

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

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

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

839:    Output Parameter:
840: +  value - the integer value to return
841: -  flg - PETSC_TRUE if found, else PETSC_FALSE

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

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

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

851:    Level: beginner

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

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

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

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

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

881:    Output Parameter:
882: +  value - the integer value to return
883: -  flg - PETSC_TRUE if found, else PETSC_FALSE

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

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

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

893:    Level: beginner

895: .seealso: PetscOptionsBoundedInt(), PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
896:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(), PetscOptionsRangeInt()
897:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
898:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
899:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
900:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
901:           PetscOptionsFList(), PetscOptionsEList()
902: M*/

904: PetscErrorCode  PetscOptionsInt_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool  *set,PetscInt lb,PetscInt ub)
905: {
906:   PetscErrorCode  ierr;
907:   PetscOptionItem amsopt;
908:   PetscBool       wasset;

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

918:     PetscOptionsGetInt(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,&currentvalue,&wasset);
919:     if (wasset) {
920:       *(PetscInt*)amsopt->data = currentvalue;
921:     }
922:   }
923:   PetscOptionsGetInt(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,&wasset);
924:   if (wasset && *value < lb) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Newly set value %D less than allowed bound %D",*value,lb);
925:   if (wasset && *value > ub) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Newly set value %D greater than allowed bound %D",*value,ub);
926:   if (set) *set = wasset;
927:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
928:     (*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));
929:   }
930:   return(0);
931: }

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

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

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

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

949:    Output Parameter:
950: +  value - the value to return
951: -  flg - PETSC_TRUE if found, else PETSC_FALSE

953:    Level: beginner

955:    Notes:
956:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

958:    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).

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

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

965: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
966:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
967:           PetscOptionsInt(), PetscOptionsReal(), PetscOptionsBool(),
968:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
969:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
970:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
971:           PetscOptionsFList(), PetscOptionsEList()
972: M*/

974: PetscErrorCode  PetscOptionsString_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char currentvalue[],char value[],size_t len,PetscBool  *set)
975: {
976:   PetscErrorCode  ierr;
977:   PetscOptionItem amsopt;
978:   PetscBool       lset;

981:   if (!PetscOptionsObject->count) {
982:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
983:     /* must use system malloc since SAWs may free this */
984:     PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
985:   }
986:   PetscOptionsGetString(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,len,&lset);
987:   if (set) *set = lset;
988:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
989:     (*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));
990:   }
991:   return(0);
992: }

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

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

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

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

1013:    Output Parameter:
1014: +  value - the value to return
1015: -  flg - PETSC_TRUE if found, else PETSC_FALSE

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

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

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

1025:    Level: beginner

1027: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1028:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
1029:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1030:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1031:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1032:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1033:           PetscOptionsFList(), PetscOptionsEList()
1034: M*/

1036: PetscErrorCode  PetscOptionsReal_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal currentvalue,PetscReal *value,PetscBool  *set)
1037: {
1038:   PetscErrorCode  ierr;
1039:   PetscOptionItem amsopt;
1040:   PetscBool       lset;

1043:   if (!PetscOptionsObject->count) {
1044:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL,&amsopt);
1045:     PetscMalloc(sizeof(PetscReal),&amsopt->data);

1047:     *(PetscReal*)amsopt->data = currentvalue;
1048:   }
1049:   PetscOptionsGetReal(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,&lset);
1050:   if (set) *set = lset;
1051:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1052:     (*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));
1053:   }
1054:   return(0);
1055: }

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

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

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

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

1076:    Output Parameter:
1077: +  value - the value to return
1078: -  flg - PETSC_TRUE if found, else PETSC_FALSE

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

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

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

1088:    Level: beginner

1090: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1091:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
1092:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1093:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1094:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1095:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1096:           PetscOptionsFList(), PetscOptionsEList()
1097: M*/

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

1104: #if !defined(PETSC_USE_COMPLEX)
1105:   PetscOptionsReal(opt,text,man,currentvalue,value,set);
1106: #else
1107:   PetscOptionsGetScalar(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,set);
1108: #endif
1109:   return(0);
1110: }

1112: /*MC
1113:    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
1114:                       its value is set to false.

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

1118:    Synopsis:
1119:    #include "petscsys.h"
1120:    PetscErrorCode PetscOptionsName(const char opt[],const char text[],const char man[],PetscBool  *flg)

1122:    Input Parameters:
1123: +  opt - option name
1124: .  text - short string that describes the option
1125: -  man - manual page with additional information on option

1127:    Output Parameter:
1128: .  flg - PETSC_TRUE if found, else PETSC_FALSE

1130:    Level: beginner

1132:    Notes:
1133:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

1135: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1136:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
1137:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1138:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1139:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1140:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1141:           PetscOptionsFList(), PetscOptionsEList()
1142: M*/

1144: PetscErrorCode  PetscOptionsName_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
1145: {
1146:   PetscErrorCode  ierr;
1147:   PetscOptionItem amsopt;

1150:   if (!PetscOptionsObject->count) {
1151:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1152:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1154:     *(PetscBool*)amsopt->data = PETSC_FALSE;
1155:   }
1156:   PetscOptionsHasName(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg);
1157:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1158:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1159:   }
1160:   return(0);
1161: }

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

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

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

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

1182:    Output Parameter:
1183: +  value - the value to return
1184: -  set - PETSC_TRUE if found, else PETSC_FALSE

1186:    Level: intermediate

1188:    Notes:
1189:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

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

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

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

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

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

1203: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1204:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1205:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1206:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1207:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1208:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsEnum()
1209: M*/

1211: 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)
1212: {
1213:   PetscErrorCode  ierr;
1214:   PetscOptionItem amsopt;
1215:   PetscBool       lset;

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

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

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

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

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

1251:    Output Parameter:
1252: +  value - the index of the value to return
1253: -  set - PETSC_TRUE if found, else PETSC_FALSE

1255:    Level: intermediate

1257:    Notes:
1258:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

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

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

1265: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1266:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1267:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1268:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1269:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1270:           PetscOptionsFList(), PetscOptionsEnum()
1271: M*/

1273: 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)
1274: {
1275:   PetscErrorCode  ierr;
1276:   PetscInt        i;
1277:   PetscOptionItem amsopt;
1278:   PetscBool       lset;

1281:   if (!PetscOptionsObject->count) {
1282:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_ELIST,&amsopt);
1283:     /* must use system malloc since SAWs may free this */
1284:     PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
1285:     PetscStrNArrayallocpy(ntext,list,(char***)&amsopt->list);
1286:     amsopt->nlist = ntext;
1287:   }
1288:   PetscOptionsGetEList(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,list,ntext,value,&lset);
1289:   if (set) *set = lset;
1290:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1291:     (*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);
1292:     for (i=0; i<ntext; i++) {
1293:       (*PetscHelpPrintf)(PetscOptionsObject->comm," %s",list[i]);
1294:     }
1295:     (*PetscHelpPrintf)(PetscOptionsObject->comm," (%s)\n",ManSection(man));
1296:   }
1297:   return(0);
1298: }

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

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

1306:    Synopsis:
1307:    #include "petscsys.h"
1308:    PetscErrorCode PetscOptionsBoolGroupBegin(const char opt[],const char text[],const char man[],PetscBool  *flg)

1310:    Input Parameters:
1311: +  opt - option name
1312: .  text - short string that describes the option
1313: -  man - manual page with additional information on option

1315:    Output Parameter:
1316: .  flg - whether that option was set or not

1318:    Level: intermediate

1320:    Notes:
1321:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

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

1325: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1326:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1327:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1328:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1329:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1330:           PetscOptionsFList(), PetscOptionsEList()
1331: M*/

1333: PetscErrorCode  PetscOptionsBoolGroupBegin_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
1334: {
1335:   PetscErrorCode  ierr;
1336:   PetscOptionItem amsopt;

1339:   if (!PetscOptionsObject->count) {
1340:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1341:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1343:     *(PetscBool*)amsopt->data = PETSC_FALSE;
1344:   }
1345:   *flg = PETSC_FALSE;
1346:   PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1347:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1348:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  Pick at most one of -------------\n");
1349:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"    -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1350:   }
1351:   return(0);
1352: }

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

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

1360:    Synopsis:
1361:    #include "petscsys.h"
1362:    PetscErrorCode PetscOptionsBoolGroup(const char opt[],const char text[],const char man[],PetscBool  *flg)

1364:    Input Parameters:
1365: +  opt - option name
1366: .  text - short string that describes the option
1367: -  man - manual page with additional information on option

1369:    Output Parameter:
1370: .  flg - PETSC_TRUE if found, else PETSC_FALSE

1372:    Level: intermediate

1374:    Notes:
1375:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

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

1379: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1380:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1381:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1382:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1383:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1384:           PetscOptionsFList(), PetscOptionsEList()
1385: M*/

1387: PetscErrorCode  PetscOptionsBoolGroup_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
1388: {
1389:   PetscErrorCode  ierr;
1390:   PetscOptionItem amsopt;

1393:   if (!PetscOptionsObject->count) {
1394:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1395:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1397:     *(PetscBool*)amsopt->data = PETSC_FALSE;
1398:   }
1399:   *flg = PETSC_FALSE;
1400:   PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1401:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1402:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"    -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1403:   }
1404:   return(0);
1405: }

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

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

1413:    Synopsis:
1414:    #include "petscsys.h"
1415:    PetscErrorCode PetscOptionsBoolGroupEnd(const char opt[],const char text[],const char man[],PetscBool  *flg)

1417:    Input Parameters:
1418: +  opt - option name
1419: .  text - short string that describes the option
1420: -  man - manual page with additional information on option

1422:    Output Parameter:
1423: .  flg - PETSC_TRUE if found, else PETSC_FALSE

1425:    Level: intermediate

1427:    Notes:
1428:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

1430:    Must follow a PetscOptionsBoolGroupBegin()

1432: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1433:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1434:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1435:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1436:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1437:           PetscOptionsFList(), PetscOptionsEList()
1438: M*/

1440: PetscErrorCode  PetscOptionsBoolGroupEnd_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
1441: {
1442:   PetscErrorCode  ierr;
1443:   PetscOptionItem amsopt;

1446:   if (!PetscOptionsObject->count) {
1447:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1448:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1450:     *(PetscBool*)amsopt->data = PETSC_FALSE;
1451:   }
1452:   *flg = PETSC_FALSE;
1453:   PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1454:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1455:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"    -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1456:   }
1457:   return(0);
1458: }

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

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

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

1469:    Input Parameters:
1470: +  opt - option name
1471: .  text - short string that describes the option
1472: .  man - manual page with additional information on option
1473: -  currentvalue - the current value

1475:    Output Parameter:
1476: +  flg - PETSC_TRUE or PETSC_FALSE
1477: -  set - PETSC_TRUE if found, else PETSC_FALSE

1479:    Notes:
1480:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1481:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

1483:       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
1484:      is equivalent to -requested_bool true

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

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

1491:    Level: beginner

1493: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1494:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
1495:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(),
1496:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1497:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1498:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1499:           PetscOptionsFList(), PetscOptionsEList()
1500: M*/

1502: PetscErrorCode  PetscOptionsBool_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool currentvalue,PetscBool  *flg,PetscBool  *set)
1503: {
1504:   PetscErrorCode  ierr;
1505:   PetscBool       iset;
1506:   PetscOptionItem amsopt;

1509:   if (!PetscOptionsObject->count) {
1510:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1511:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1513:     *(PetscBool*)amsopt->data = currentvalue;
1514:   }
1515:   PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,&iset);
1516:   if (set) *set = iset;
1517:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1518:     const char *v = PetscBools[currentvalue], *vn = PetscBools[iset && flg ? *flg : currentvalue];
1519:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s: <%s : %s> %s (%s)\n",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,v,vn,text,ManSection(man));
1520:   }
1521:   return(0);
1522: }

1524: /*MC
1525:    PetscOptionsRealArray - Gets an array of double values for a particular
1526:    option in the database. The values must be separated with commas with
1527:    no intervening spaces.

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

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

1535:    Input Parameters:
1536: +  opt - the option one is seeking
1537: .  text - short string describing option
1538: .  man - manual page for option
1539: -  nmax - maximum number of values

1541:    Output Parameter:
1542: +  value - location to copy values
1543: .  nmax - actual number of values found
1544: -  set - PETSC_TRUE if found, else PETSC_FALSE

1546:    Level: beginner

1548:    Notes:
1549:    The user should pass in an array of doubles

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

1553: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1554:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1555:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1556:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1557:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1558:           PetscOptionsFList(), PetscOptionsEList()
1559: M*/

1561: PetscErrorCode PetscOptionsRealArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool  *set)
1562: {
1563:   PetscErrorCode  ierr;
1564:   PetscInt        i;
1565:   PetscOptionItem amsopt;

1568:   if (!PetscOptionsObject->count) {
1569:     PetscReal *vals;

1571:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL_ARRAY,&amsopt);
1572:     PetscMalloc((*n)*sizeof(PetscReal),&amsopt->data);
1573:     vals = (PetscReal*)amsopt->data;
1574:     for (i=0; i<*n; i++) vals[i] = value[i];
1575:     amsopt->arraylength = *n;
1576:   }
1577:   PetscOptionsGetRealArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1578:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1579:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%g",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)value[0]);
1580:     for (i=1; i<*n; i++) {
1581:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g",(double)value[i]);
1582:     }
1583:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1584:   }
1585:   return(0);
1586: }

1588: /*MC
1589:    PetscOptionsScalarArray - Gets an array of Scalar values for a particular
1590:    option in the database. The values must be separated with commas with
1591:    no intervening spaces.

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

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

1599:    Input Parameters:
1600: +  opt - the option one is seeking
1601: .  text - short string describing option
1602: .  man - manual page for option
1603: -  nmax - maximum number of values

1605:    Output Parameter:
1606: +  value - location to copy values
1607: .  nmax - actual number of values found
1608: -  set - PETSC_TRUE if found, else PETSC_FALSE

1610:    Level: beginner

1612:    Notes:
1613:    The user should pass in an array of doubles

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

1617: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1618:           PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1619:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1620:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1621:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1622:           PetscOptionsFList(), PetscOptionsEList()
1623: M*/

1625: PetscErrorCode PetscOptionsScalarArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar value[],PetscInt *n,PetscBool  *set)
1626: {
1627:   PetscErrorCode  ierr;
1628:   PetscInt        i;
1629:   PetscOptionItem amsopt;

1632:   if (!PetscOptionsObject->count) {
1633:     PetscScalar *vals;

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

1652: /*MC
1653:    PetscOptionsIntArray - Gets an array of integers for a particular
1654:    option in the database.

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

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

1662:    Input Parameters:
1663: +  opt - the option one is seeking
1664: .  text - short string describing option
1665: .  man - manual page for option
1666: -  n - maximum number of values

1668:    Output Parameter:
1669: +  value - location to copy values
1670: .  n - actual number of values found
1671: -  set - PETSC_TRUE if found, else PETSC_FALSE

1673:    Level: beginner

1675:    Notes:
1676:    The array can be passed as
1677:    a comma separated list:                                 0,1,2,3,4,5,6,7
1678:    a range (start-end+1):                                  0-8
1679:    a range with given increment (start-end+1:inc):         0-7:2
1680:    a combination of values and ranges separated by commas: 0,1-8,8-15:2

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

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

1686: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1687:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1688:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1689:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1690:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1691:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
1692: M*/

1694: PetscErrorCode  PetscOptionsIntArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool  *set)
1695: {
1697:   PetscInt        i;
1698:   PetscOptionItem amsopt;

1701:   if (!PetscOptionsObject->count) {
1702:     PetscInt *vals;

1704:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT_ARRAY,&amsopt);
1705:     PetscMalloc1(*n,(PetscInt**)&amsopt->data);
1706:     vals = (PetscInt*)amsopt->data;
1707:     for (i=0; i<*n; i++) vals[i] = value[i];
1708:     amsopt->arraylength = *n;
1709:   }
1710:   PetscOptionsGetIntArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1711:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1712:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%d",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
1713:     for (i=1; i<*n; i++) {
1714:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%d",value[i]);
1715:     }
1716:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1717:   }
1718:   return(0);
1719: }

1721: /*MC
1722:    PetscOptionsStringArray - Gets an array of string values for a particular
1723:    option in the database. The values must be separated with commas with
1724:    no intervening spaces.

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

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

1732:    Input Parameters:
1733: +  opt - the option one is seeking
1734: .  text - short string describing option
1735: .  man - manual page for option
1736: -  nmax - maximum number of strings

1738:    Output Parameter:
1739: +  value - location to copy strings
1740: .  nmax - actual number of strings found
1741: -  set - PETSC_TRUE if found, else PETSC_FALSE

1743:    Level: beginner

1745:    Notes:
1746:    The user should pass in an array of pointers to char, to hold all the
1747:    strings returned by this function.

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

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

1754: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1755:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1756:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1757:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1758:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1759:           PetscOptionsFList(), PetscOptionsEList()
1760: M*/

1762: PetscErrorCode  PetscOptionsStringArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool  *set)
1763: {
1764:   PetscErrorCode  ierr;
1765:   PetscOptionItem amsopt;

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

1772:     amsopt->arraylength = *nmax;
1773:   }
1774:   PetscOptionsGetStringArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,nmax,set);
1775:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1776:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1777:   }
1778:   return(0);
1779: }

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

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

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

1792:    Input Parameters:
1793: +  opt - the option one is seeking
1794: .  text - short string describing option
1795: .  man - manual page for option
1796: -  nmax - maximum number of values

1798:    Output Parameter:
1799: +  value - location to copy values
1800: .  nmax - actual number of values found
1801: -  set - PETSC_TRUE if found, else PETSC_FALSE

1803:    Level: beginner

1805:    Notes:
1806:    The user should pass in an array of doubles

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

1810: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1811:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1812:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1813:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1814:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1815:           PetscOptionsFList(), PetscOptionsEList()
1816: M*/

1818: PetscErrorCode  PetscOptionsBoolArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)
1819: {
1820:   PetscErrorCode   ierr;
1821:   PetscInt         i;
1822:   PetscOptionItem  amsopt;

1825:   if (!PetscOptionsObject->count) {
1826:     PetscBool *vals;

1828:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL_ARRAY,&amsopt);
1829:     PetscMalloc1(*n,(PetscBool**)&amsopt->data);
1830:     vals = (PetscBool*)amsopt->data;
1831:     for (i=0; i<*n; i++) vals[i] = value[i];
1832:     amsopt->arraylength = *n;
1833:   }
1834:   PetscOptionsGetBoolArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1835:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1836:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%d",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
1837:     for (i=1; i<*n; i++) {
1838:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%d",value[i]);
1839:     }
1840:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1841:   }
1842:   return(0);
1843: }

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

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

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

1854:    Input Parameters:
1855: +  opt - option name
1856: .  text - short string that describes the option
1857: -  man - manual page with additional information on option

1859:    Output Parameter:
1860: +  viewer - the viewer
1861: -  set - PETSC_TRUE if found, else PETSC_FALSE

1863:    Level: beginner

1865:    Notes:
1866:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

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

1870: .seealso: PetscOptionsGetViewer(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1871:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1872:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1873:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1874:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1875:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1876:           PetscOptionsFList(), PetscOptionsEList()
1877: M*/

1879: PetscErrorCode  PetscOptionsViewer_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool  *set)
1880: {
1881:   PetscErrorCode  ierr;
1882:   PetscOptionItem amsopt;

1885:   if (!PetscOptionsObject->count) {
1886:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
1887:     /* must use system malloc since SAWs may free this */
1888:     PetscStrdup("",(char**)&amsopt->data);
1889:   }
1890:   PetscOptionsGetViewer(PetscOptionsObject->comm,PetscOptionsObject->options,PetscOptionsObject->prefix,opt,viewer,format,set);
1891:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1892:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%s>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,"",text,ManSection(man));
1893:   }
1894:   return(0);
1895: }

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

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

1903:    Input Parameter:
1904: .   head - the heading text

1906:    Level: intermediate

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

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

1913: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1914:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1915:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1916:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1917:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1918:           PetscOptionsFList(), PetscOptionsEList()
1919: @*/
1920: PetscErrorCode  PetscOptionsHead(PetscOptionItems *PetscOptionsObject,const char head[])
1921: {

1925:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1926:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  %s\n",head);
1927:   }
1928:   return(0);
1929: }