Actual source code: aoptions.c

  1: #define PETSC_DLL
  2: /*
  3:    These routines simplify the use of command line, file options, etc.,
  4:    and are used to manipulate the options database.

  6:   This file uses regular malloc and free because it cannot know 
  7:   what malloc is being used until it has already processed the input.
  8: */

 10:  #include petsc.h
 11:  #include petscsys.h
 12: #if defined(PETSC_HAVE_STDLIB_H)
 13: #include <stdlib.h>
 14: #endif

 16: /*
 17:     Keep a linked list of options that have been posted and we are waiting for 
 18:    user selection

 20:     Eventually we'll attach this beast to a MPI_Comm
 21: */
 22: typedef enum {OPTION_INT,OPTION_LOGICAL,OPTION_REAL,OPTION_LIST,OPTION_STRING,OPTION_REAL_ARRAY,OPTION_HEAD} OptionType;
 23: typedef struct _p_Options* PetscOptions;
 24: struct _p_Options {
 25:   char         *option;
 26:   char         *text;
 27:   void         *data;
 28:   void         *edata;
 29:   char         *man;
 30:   int          arraylength;
 31:   PetscTruth   set;
 32:   OptionType   type;
 33:   PetscOptions next;
 34: };

 36: typedef struct _p_OptionsHelp* OptionsHelp;
 37: struct _p_OptionsHelp {
 38:   char        *prefix;
 39:   char        *title;
 40:   char        *mansec;
 41:   OptionsHelp next;
 42: };

 44: static struct {
 45:   PetscOptions    next;
 46:   char            *prefix,*mprefix;
 47:   char            *title;
 48:   MPI_Comm        comm;
 49:   PetscTruth      printhelp,changedmethod,alreadyprinted;
 50:   OptionsHelp     help;
 51: }                                   PetscOptionsObject;
 52: PetscInt                            PetscOptionsPublishCount = 0;


 57: PetscErrorCode PetscOptionsHelpAddList(const char prefix[],const char title[],const char mansec[])
 58: {
 59:   int          ierr;
 60:   OptionsHelp  newhelp;
 62:   PetscNew(struct _p_OptionsHelp,&newhelp);
 63:   PetscStrallocpy(prefix,&newhelp->prefix);
 64:   PetscStrallocpy(title,&newhelp->title);
 65:   PetscStrallocpy(mansec,&newhelp->mansec);
 66:   newhelp->next = 0;

 68:   if (!PetscOptionsObject.help) {
 69:     PetscOptionsObject.help = newhelp;
 70:   } else {
 71:     newhelp->next = PetscOptionsObject.help;
 72:     PetscOptionsObject.help = newhelp;
 73:   }
 74:   return(0);
 75: }

 79: PetscErrorCode PetscOptionsHelpDestroyList(void)
 80: {
 82:   OptionsHelp    help = PetscOptionsObject.help, next;

 85:   while (help) {
 86:     next = help->next;
 87:     PetscStrfree(help->prefix);
 88:     PetscStrfree(help->title);
 89:     PetscStrfree(help->mansec);
 90:     PetscFree(help);
 91:     help = next;
 92:   }
 93:   return(0);
 94: }
 95: 

 99: PetscErrorCode PetscOptionsHelpFindList(const char prefix[],const char title[],const char mansec[],PetscTruth *flg)
100: {
102:   PetscTruth     flg1,flg2,flg3;
103:   OptionsHelp help = PetscOptionsObject.help;
105:   while (help) {
106:     PetscStrcmp(help->prefix,prefix,&flg1);
107:     PetscStrcmp(help->title,title,&flg2);
108:     PetscStrcmp(help->mansec,mansec,&flg3);
109:     if (flg1 && flg2 && flg3) {
110:       *flg = PETSC_TRUE;
111:       break;
112:     }
113:     help = help->next;
114:   }
115:   return(0);

117: }

121: PetscErrorCode PetscOptionsHelpCheckAddList(const char prefix[],const char title[],const char mansec[],PetscTruth *flg)
122: {
124:   PetscOptionsHelpFindList(prefix,title,mansec,flg);
125:   if (!(*flg)) PetscOptionsHelpAddList(prefix,title,mansec);
126:   return(0);
127: }

131: /*
132:     Handles setting up the data structure in a call to PetscOptionsBegin()
133: */
134: PetscErrorCode PetscOptionsBegin_Private(MPI_Comm comm,const char prefix[],const char title[],const char mansec[])
135: {

139:   PetscOptionsObject.next          = 0;
140:   PetscOptionsObject.comm          = comm;
141:   PetscOptionsObject.changedmethod = PETSC_FALSE;
142:   PetscStrallocpy(prefix,&PetscOptionsObject.prefix);
143:   PetscStrallocpy(title,&PetscOptionsObject.title);

145:   PetscOptionsHasName(PETSC_NULL,"-help",&PetscOptionsObject.printhelp);
146:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
147:     PetscOptionsHelpCheckAddList(prefix,title,mansec,&PetscOptionsObject.alreadyprinted);
148:     if (!PetscOptionsObject.alreadyprinted) {
149:       (*PetscHelpPrintf)(comm,"%s -------------------------------------------------\n",title);
150:     }
151:   }
152:   return(0);
153: }

155: /*
156:      Handles adding another option to the list of options within this particular PetscOptionsBegin() PetscOptionsEnd()
157: */
160: static int PetscOptionsCreate_Private(const char opt[],const char text[],const char man[],OptionType t,PetscOptions *amsopt)
161: {
162:   int          ierr;
163:   PetscOptions next;

166:   PetscNew(struct _p_Options,amsopt);
167:   (*amsopt)->next  = 0;
168:   (*amsopt)->set   = PETSC_FALSE;
169:   (*amsopt)->type  = t;
170:   (*amsopt)->data  = 0;
171:   (*amsopt)->edata = 0;

173:   PetscStrallocpy(text,&(*amsopt)->text);
174:   PetscStrallocpy(opt,&(*amsopt)->option);
175:   PetscStrallocpy(man,&(*amsopt)->man);

177:   if (!PetscOptionsObject.next) {
178:     PetscOptionsObject.next = *amsopt;
179:   } else {
180:     next = PetscOptionsObject.next;
181:     while (next->next) next = next->next;
182:     next->next = *amsopt;
183:   }
184:   return(0);
185: }

189: PetscErrorCode PetscOptionsGetFromGUI()
190: {
192:   PetscOptions   next = PetscOptionsObject.next;
193:   char           str[512];

195:   (*PetscPrintf)(PetscOptionsObject.comm,"%s -------------------------------------------------\n",PetscOptionsObject.title);
196:   while (next) {
197:     switch (next->type) {
198:       case OPTION_HEAD:
199:         break;
200:       case OPTION_INT:
201:         PetscPrintf(PetscOptionsObject.comm,"-%s%s <%d>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",next->option,*(int*)next->data,next->text,next->man);
202:         scanf("%s\n",str);
203:         if (str[0] != '\n') {
204:           printf("changing value\n");
205:         }
206:         break;
207:     default:
208:       break;
209:     }
210:     next = next->next;
211:   }
212:   return(0);
213: }

217: PetscErrorCode PetscOptionsEnd_Private(void)
218: {
220:   PetscOptions   last;
221:   char           option[256],value[1024],tmp[32];
222:   PetscInt       j;


226:   /*  if (PetscOptionsObject.next) { 
227:     PetscOptionsGetFromGUI();
228:     }*/

230:   PetscStrfree(PetscOptionsObject.title); PetscOptionsObject.title  = 0;
231:   PetscStrfree(PetscOptionsObject.prefix); PetscOptionsObject.prefix = 0;

233:   /* reset counter to -2; this updates the screen with the new options for the selected method */
234:   if (PetscOptionsObject.changedmethod) PetscOptionsPublishCount = -2;
235:   /* reset alreadyprinted flag */
236:   PetscOptionsObject.alreadyprinted = PETSC_FALSE;

238:   while (PetscOptionsObject.next) {
239:     if (PetscOptionsObject.next->set) {
240:       if (PetscOptionsObject.prefix) {
241:         PetscStrcpy(option,"-");
242:         PetscStrcat(option,PetscOptionsObject.prefix);
243:         PetscStrcat(option,PetscOptionsObject.next->option+1);
244:       } else {
245:         PetscStrcpy(option,PetscOptionsObject.next->option);
246:       }

248:       switch (PetscOptionsObject.next->type) {
249:         case OPTION_HEAD:
250:           break;
251:         case OPTION_INT:
252:           sprintf(value,"%d",*(PetscInt*)PetscOptionsObject.next->data);
253:           break;
254:         case OPTION_REAL:
255:           sprintf(value,"%g",*(PetscReal*)PetscOptionsObject.next->data);
256:           break;
257:         case OPTION_REAL_ARRAY:
258:           sprintf(value,"%g",((PetscReal*)PetscOptionsObject.next->data)[0]);
259:           for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
260:             sprintf(tmp,"%g",((PetscReal*)PetscOptionsObject.next->data)[j]);
261:             PetscStrcat(value,",");
262:             PetscStrcat(value,tmp);
263:           }
264:           break;
265:         case OPTION_LOGICAL:
266:           sprintf(value,"%d",*(PetscInt*)PetscOptionsObject.next->data);
267:           break;
268:         case OPTION_LIST:
269:           PetscStrcpy(value,*(char**)PetscOptionsObject.next->data);
270:           break;
271:         case OPTION_STRING: /* also handles string arrays */
272:           PetscStrcpy(value,*(char**)PetscOptionsObject.next->data);
273:           break;
274:       }
275:       PetscOptionsSetValue(option,value);
276:     }
277:     PetscStrfree(PetscOptionsObject.next->text);
278:     PetscStrfree(PetscOptionsObject.next->option);
279:     PetscFree(PetscOptionsObject.next->man);
280:     PetscFree(PetscOptionsObject.next->data);
281:     PetscFree(PetscOptionsObject.next->edata);
282:     last                    = PetscOptionsObject.next;
283:     PetscOptionsObject.next = PetscOptionsObject.next->next;
284:     PetscFree(last);
285:   }
286:   PetscOptionsObject.next = 0;
287:   return(0);
288: }

292: /*@C
293:    PetscOptionsEnum - Gets the enum value for a particular option in the database.

295:    Collective on the communicator passed in PetscOptionsBegin()

297:    Input Parameters:
298: +  opt - option name
299: .  text - short string that describes the option
300: .  man - manual page with additional information on option
301: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
302: -  defaultv - the default (current) value

304:    Output Parameter:
305: +  value - the  value to return
306: -  flg - PETSC_TRUE if found, else PETSC_FALSE

308:    Level: beginner

310:    Concepts: options database

312:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

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

316: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
317:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
318:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
319:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
320:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
321:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
322:           PetscOptionsList(), PetscOptionsEList()
323: @*/
324: PetscErrorCode  PetscOptionsEnum(const char opt[],const char text[],const char man[],const char **list,PetscEnum defaultv,PetscEnum *value,PetscTruth *set)
325: {
327:   PetscInt       ntext = 0;

330:   while (list[ntext++]) {
331:     if (ntext > 50) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
332:   }
333:   if (ntext < 3) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
334:   ntext -= 3;
335:   PetscOptionsEList(opt,text,man,list,ntext,list[defaultv],(PetscInt*)value,set);
336:   return(0);
337: }

339: /* -------------------------------------------------------------------------------------------------------------*/
342: /*@C
343:    PetscOptionsInt - Gets the integer value for a particular option in the database.

345:    Collective on the communicator passed in PetscOptionsBegin()

347:    Input Parameters:
348: +  opt - option name
349: .  text - short string that describes the option
350: .  man - manual page with additional information on option
351: -  defaultv - the default (current) value

353:    Output Parameter:
354: +  value - the integer value to return
355: -  flg - PETSC_TRUE if found, else PETSC_FALSE

357:    Level: beginner

359:    Concepts: options database^has int

361:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

363: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
364:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
365:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
366:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
367:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
368:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
369:           PetscOptionsList(), PetscOptionsEList()
370: @*/
371: PetscErrorCode  PetscOptionsInt(const char opt[],const char text[],const char man[],PetscInt defaultv,PetscInt *value,PetscTruth *set)
372: {
374:   PetscOptions   amsopt;

377:   if (PetscOptionsPublishCount == 1) {
378:     PetscOptionsCreate_Private(opt,text,man,OPTION_INT,&amsopt);
379:     PetscMalloc(sizeof(PetscInt),&amsopt->data);
380:     *(PetscInt*)amsopt->data = defaultv;
381:   }
382:   PetscOptionsGetInt(PetscOptionsObject.prefix,opt,value,set);
383:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
384:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%d>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,man);
385:   }
386:   return(0);
387: }

391: /*@C
392:    PetscOptionsString - Gets the string value for a particular option in the database.

394:    Collective on the communicator passed in PetscOptionsBegin()

396:    Input Parameters:
397: +  opt - option name
398: .  text - short string that describes the option
399: .  man - manual page with additional information on option
400: -  defaultv - the default (current) value

402:    Output Parameter:
403: +  value - the value to return
404: -  flg - PETSC_TRUE if found, else PETSC_FALSE

406:    Level: beginner

408:    Concepts: options database^has int

410:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

412: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
413:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
414:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
415:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
416:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
417:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
418:           PetscOptionsList(), PetscOptionsEList()
419: @*/
420: PetscErrorCode  PetscOptionsString(const char opt[],const char text[],const char man[],const char defaultv[],char value[],size_t len,PetscTruth *set)
421: {

425:   PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
426:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
427:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%s>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,man);
428:   }
429:   return(0);
430: }

432: /*
433:      Publishes an AMS double field (with the default value in it) and with a name
434:    given by the text string
435: */
438: /*@C
439:    PetscOptionsReal - Gets the PetscReal value for a particular option in the database.

441:    Collective on the communicator passed in PetscOptionsBegin()

443:    Input Parameters:
444: +  opt - option name
445: .  text - short string that describes the option
446: .  man - manual page with additional information on option
447: -  defaultv - the default (current) value

449:    Output Parameter:
450: +  value - the value to return
451: -  flg - PETSC_TRUE if found, else PETSC_FALSE

453:    Level: beginner

455:    Concepts: options database^has int

457:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

459: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
460:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
461:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
462:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
463:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
464:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
465:           PetscOptionsList(), PetscOptionsEList()
466: @*/
467: PetscErrorCode  PetscOptionsReal(const char opt[],const char text[],const char man[],PetscReal defaultv,PetscReal *value,PetscTruth *set)
468: {

472:   PetscOptionsGetReal(PetscOptionsObject.prefix,opt,value,set);
473:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
474:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%G>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,man);
475:   }
476:   return(0);
477: }

481: /*@C
482:    PetscOptionsScalar - Gets the scalar value for a particular option in the database.

484:    Collective on the communicator passed in PetscOptionsBegin()

486:    Input Parameters:
487: +  opt - option name
488: .  text - short string that describes the option
489: .  man - manual page with additional information on option
490: -  defaultv - the default (current) value

492:    Output Parameter:
493: +  value - the value to return
494: -  flg - PETSC_TRUE if found, else PETSC_FALSE

496:    Level: beginner

498:    Concepts: options database^has int

500:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

502: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
503:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
504:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
505:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
506:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
507:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
508:           PetscOptionsList(), PetscOptionsEList()
509: @*/
510: PetscErrorCode  PetscOptionsScalar(const char opt[],const char text[],const char man[],PetscScalar defaultv,PetscScalar *value,PetscTruth *set)
511: {

515: #if !defined(PETSC_USE_COMPLEX)
516:   PetscOptionsReal(opt,text,man,defaultv,value,set);
517: #else
518:   PetscOptionsGetScalar(PetscOptionsObject.prefix,opt,value,set);
519: #endif
520:   return(0);
521: }

523: /*
524:      Publishes an AMS logical field (with the default value in it) and with a name
525:    given by the text string
526: */
529: /*@C
530:    PetscOptionsName - Determines if a particular option is in the database

532:    Collective on the communicator passed in PetscOptionsBegin()

534:    Input Parameters:
535: +  opt - option name
536: .  text - short string that describes the option
537: -  man - manual page with additional information on option

539:    Output Parameter:
540: .  flg - PETSC_TRUE if found, else PETSC_FALSE

542:    Level: beginner

544:    Concepts: options database^has int

546:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

548: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
549:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
550:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
551:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
552:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
553:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
554:           PetscOptionsList(), PetscOptionsEList()
555: @*/
556: PetscErrorCode  PetscOptionsName(const char opt[],const char text[],const char man[],PetscTruth *flg)
557: {

561:   PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
562:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
563:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
564:   }
565:   return(0);
566: }

570: /*@C
571:      PetscOptionsList - Puts a list of option values that a single one may be selected from

573:    Collective on the communicator passed in PetscOptionsBegin()

575:    Input Parameters:
576: +  opt - option name
577: .  text - short string that describes the option
578: .  man - manual page with additional information on option
579: .  list - the possible choices
580: -  defaultv - the default (current) value

582:    Output Parameter:
583: +  value - the value to return
584: -  set - PETSC_TRUE if found, else PETSC_FALSE

586:    Level: intermediate
587:    
588:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

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

592:    To get a listing of all currently specified options,
593:     see PetscOptionsPrint() or PetscOptionsGetAll()

595:    Concepts: options database^list

597: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
598:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
599:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
600:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
601:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
602:           PetscOptionsList(), PetscOptionsEList()
603: @*/
604: PetscErrorCode  PetscOptionsList(const char opt[],const char ltext[],const char man[],PetscFList list,const char defaultv[],char value[],PetscInt len,PetscTruth *set)
605: {

609:   PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
610:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
611:     PetscFListPrintTypes(PetscOptionsObject.comm,stdout,PetscOptionsObject.prefix,opt,ltext,man,list);
612:   }
613:   return(0);
614: }

618: /*@C
619:      PetscOptionsEList - Puts a list of option values that a single one may be selected from

621:    Collective on the communicator passed in PetscOptionsBegin()

623:    Input Parameters:
624: +  opt - option name
625: .  ltext - short string that describes the option
626: .  man - manual page with additional information on option
627: .  list - the possible choices
628: .  ntext - number of choices
629: -  defaultv - the default (current) value

631:    Output Parameter:
632: +  value - the index of the value to return
633: -  set - PETSC_TRUE if found, else PETSC_FALSE
634:    
635:    Level: intermediate

637:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

639:    See PetscOptionsList() for when the choices are given in a PetscFList()

641:    Concepts: options database^list

643: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
644:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
645:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
646:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
647:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
648:           PetscOptionsList(), PetscOptionsEList()
649: @*/
650: PetscErrorCode  PetscOptionsEList(const char opt[],const char ltext[],const char man[],const char **list,PetscInt ntext,const char defaultv[],PetscInt *value,PetscTruth *set)
651: {
653:   PetscInt       i;

656:   PetscOptionsGetEList(PetscOptionsObject.prefix,opt,list,ntext,value,set);
657:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
658:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%s> (choose one of)",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv);
659:     for (i=0; i<ntext; i++){
660:       (*PetscHelpPrintf)(PetscOptionsObject.comm," %s",list[i]);
661:     }
662:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"\n");
663:   }
664:   return(0);
665: }

669: /*@C
670:      PetscOptionsTruthGroupBegin - First in a series of logical queries on the options database for
671:        which only a single value can be true.

673:    Collective on the communicator passed in PetscOptionsBegin()

675:    Input Parameters:
676: +  opt - option name
677: .  text - short string that describes the option
678: -  man - manual page with additional information on option

680:    Output Parameter:
681: .  flg - whether that option was set or not
682:    
683:    Level: intermediate

685:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

687:    Must be followed by 0 or more PetscOptionsTruthGroup()s and PetscOptionsTruthGroupEnd()

689:     Concepts: options database^logical group

691: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
692:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
693:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
694:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
695:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
696:           PetscOptionsList(), PetscOptionsEList()
697: @*/
698: PetscErrorCode  PetscOptionsTruthGroupBegin(const char opt[],const char text[],const char man[],PetscTruth *flg)
699: {

703:   PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
704:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
705:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  Pick at most one of -------------\n");
706:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"    -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
707:   }
708:   return(0);
709: }

713: /*@C
714:      PetscOptionsTruthGroup - One in a series of logical queries on the options database for
715:        which only a single value can be true.

717:    Collective on the communicator passed in PetscOptionsBegin()

719:    Input Parameters:
720: +  opt - option name
721: .  text - short string that describes the option
722: -  man - manual page with additional information on option

724:    Output Parameter:
725: .  flg - PETSC_TRUE if found, else PETSC_FALSE
726:    
727:    Level: intermediate

729:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

731:    Must follow a PetscOptionsTruthGroupBegin() and preceded a PetscOptionsTruthGroupEnd()

733:     Concepts: options database^logical group

735: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
736:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
737:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
738:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
739:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
740:           PetscOptionsList(), PetscOptionsEList()
741: @*/
742: PetscErrorCode  PetscOptionsTruthGroup(const char opt[],const char text[],const char man[],PetscTruth *flg)
743: {

747:   PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
748:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
749:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"    -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
750:   }
751:   return(0);
752: }

756: /*@C
757:      PetscOptionsTruthGroupEnd - Last in a series of logical queries on the options database for
758:        which only a single value can be true.

760:    Collective on the communicator passed in PetscOptionsBegin()

762:    Input Parameters:
763: +  opt - option name
764: .  text - short string that describes the option
765: -  man - manual page with additional information on option

767:    Output Parameter:
768: .  flg - PETSC_TRUE if found, else PETSC_FALSE
769:    
770:    Level: intermediate

772:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

774:    Must follow a PetscOptionsTruthGroupBegin()

776:     Concepts: options database^logical group

778: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
779:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
780:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
781:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
782:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
783:           PetscOptionsList(), PetscOptionsEList()
784: @*/
785: PetscErrorCode  PetscOptionsTruthGroupEnd(const char opt[],const char text[],const char man[],PetscTruth *flg)
786: {

790:   PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
791:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
792:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"    -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
793:   }
794:   return(0);
795: }

799: /*@C
800:    PetscOptionsTruth - Determines if a particular option is in the database with a true or false

802:    Collective on the communicator passed in PetscOptionsBegin()

804:    Input Parameters:
805: +  opt - option name
806: .  text - short string that describes the option
807: -  man - manual page with additional information on option

809:    Output Parameter:
810: .  flg - PETSC_TRUE or PETSC_FALSE
811: .  set - PETSC_TRUE if found, else PETSC_FALSE

813:    Level: beginner

815:    Concepts: options database^logical

817:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

819: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
820:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
821:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
822:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
823:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
824:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
825:           PetscOptionsList(), PetscOptionsEList()
826: @*/
827: PetscErrorCode  PetscOptionsTruth(const char opt[],const char text[],const char man[],PetscTruth deflt,PetscTruth *flg,PetscTruth *set)
828: {
830:   PetscTruth     iset;

833:   PetscOptionsGetTruth(PetscOptionsObject.prefix,opt,flg,&iset);
834:   if (!iset) {
835:     if (flg) *flg = deflt;
836:   }
837:   if (set) *set = iset;
838:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
839:     const char *v = PetscTruths[deflt];
840:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s: <%s> %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,v,text,man);
841:   }
842:   return(0);
843: }

847: /*@C
848:    PetscOptionsRealArray - Gets an array of double values for a particular
849:    option in the database. The values must be separated with commas with 
850:    no intervening spaces. 

852:    Collective on the communicator passed in PetscOptionsBegin()

854:    Input Parameters:
855: +  opt - the option one is seeking
856: .  text - short string describing option
857: .  man - manual page for option
858: -  nmax - maximum number of values

860:    Output Parameter:
861: +  value - location to copy values
862: .  nmax - actual number of values found
863: -  set - PETSC_TRUE if found, else PETSC_FALSE

865:    Level: beginner

867:    Notes: 
868:    The user should pass in an array of doubles

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

872:    Concepts: options database^array of strings

874: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
875:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
876:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
877:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
878:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
879:           PetscOptionsList(), PetscOptionsEList()
880: @*/
881: PetscErrorCode  PetscOptionsRealArray(const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscTruth *set)
882: {
884:   PetscInt       i;

887:   PetscOptionsGetRealArray(PetscOptionsObject.prefix,opt,value,n,set);
888:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
889:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%G",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,value[0]);
890:     for (i=1; i<*n; i++) {
891:       (*PetscHelpPrintf)(PetscOptionsObject.comm,",%G",value[i]);
892:     }
893:     (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,man);
894:   }
895:   return(0);
896: }


901: /*@C
902:    PetscOptionsIntArray - Gets an array of integers for a particular
903:    option in the database. The values must be separated with commas with 
904:    no intervening spaces. 

906:    Collective on the communicator passed in PetscOptionsBegin()

908:    Input Parameters:
909: +  opt - the option one is seeking
910: .  text - short string describing option
911: .  man - manual page for option
912: -  nmax - maximum number of values

914:    Output Parameter:
915: +  value - location to copy values
916: .  nmax - actual number of values found
917: -  set - PETSC_TRUE if found, else PETSC_FALSE

919:    Level: beginner

921:    Notes: 
922:    The user should pass in an array of integers

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

926:    Concepts: options database^array of strings

928: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
929:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
930:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
931:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
932:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
933:           PetscOptionsList(), PetscOptionsEList(), PetscOptionsRealArray()
934: @*/
935: PetscErrorCode  PetscOptionsIntArray(const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscTruth *set)
936: {
938:   PetscInt       i;

941:   PetscOptionsGetIntArray(PetscOptionsObject.prefix,opt,value,n,set);
942:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
943:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%d",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,value[0]);
944:     for (i=1; i<*n; i++) {
945:       (*PetscHelpPrintf)(PetscOptionsObject.comm,",%d",value[i]);
946:     }
947:     (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,man);
948:   }
949:   return(0);
950: }

954: /*@C
955:    PetscOptionsStringArray - Gets an array of string values for a particular
956:    option in the database. The values must be separated with commas with 
957:    no intervening spaces. 

959:    Collective on the communicator passed in PetscOptionsBegin()

961:    Input Parameters:
962: +  opt - the option one is seeking
963: .  text - short string describing option
964: .  man - manual page for option
965: -  nmax - maximum number of strings

967:    Output Parameter:
968: +  value - location to copy strings
969: .  nmax - actual number of strings found
970: -  set - PETSC_TRUE if found, else PETSC_FALSE

972:    Level: beginner

974:    Notes: 
975:    The user should pass in an array of pointers to char, to hold all the
976:    strings returned by this function.

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

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

983:    Concepts: options database^array of strings

985: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
986:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
987:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
988:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
989:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
990:           PetscOptionsList(), PetscOptionsEList()
991: @*/
992: PetscErrorCode  PetscOptionsStringArray(const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscTruth *set)
993: {

997:   PetscOptionsGetStringArray(PetscOptionsObject.prefix,opt,value,nmax,set);
998:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
999:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
1000:   }
1001:   return(0);
1002: }


1007: /*@C
1008:      PetscOptionsHead - Puts a heading before list any more published options. Used, for example,
1009:             in KSPSetFromOptions_GMRES().

1011:    Collective on the communicator passed in PetscOptionsBegin()

1013:    Input Parameter:
1014: .   head - the heading text

1016:    
1017:    Level: intermediate

1019:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

1021:           Must be followed by a call to PetscOptionsTail() in the same function.

1023:    Concepts: options database^subheading

1025: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1026:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1027:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1028:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1029:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1030:           PetscOptionsList(), PetscOptionsEList()
1031: @*/
1032: PetscErrorCode  PetscOptionsHead(const char head[])
1033: {

1037:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1038:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  %s\n",head);
1039:   }
1040:   return(0);
1041: }