Actual source code: aoptions.c
  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(), PetscOptionsGetBool(),
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(), PetscOptionsGetBool(),
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(), PetscOptionsGetBool(), 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(), PetscOptionsGetBool(), 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(), PetscOptionsGetBool(), 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,¤tvalue,&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(), PetscOptionsGetBool(),
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(), PetscOptionsGetBool(),
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(), PetscOptionsGetBool(),
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(), PetscOptionsGetBool(),
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(), PetscOptionsGetBool(),
1503:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(),
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: }