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: PetscOptionsObjectType PetscOptionsObject;
 23: PetscInt               PetscOptionsPublishCount = 0;


 28: PetscErrorCode PetscOptionsHelpAddList(const char prefix[],const char title[],const char mansec[])
 29: {
 30:   int          ierr;
 31:   OptionsHelp  newhelp;
 33:   PetscNew(struct _p_OptionsHelp,&newhelp);
 34:   PetscStrallocpy(prefix,&newhelp->prefix);
 35:   PetscStrallocpy(title,&newhelp->title);
 36:   PetscStrallocpy(mansec,&newhelp->mansec);
 37:   newhelp->next = 0;

 39:   if (!PetscOptionsObject.help) {
 40:     PetscOptionsObject.help = newhelp;
 41:   } else {
 42:     newhelp->next = PetscOptionsObject.help;
 43:     PetscOptionsObject.help = newhelp;
 44:   }
 45:   return(0);
 46: }

 50: PetscErrorCode PetscOptionsHelpDestroyList(void)
 51: {
 53:   OptionsHelp    help = PetscOptionsObject.help, next;

 56:   while (help) {
 57:     next = help->next;
 58:     PetscStrfree(help->prefix);
 59:     PetscStrfree(help->title);
 60:     PetscStrfree(help->mansec);
 61:     PetscFree(help);
 62:     help = next;
 63:   }
 64:   return(0);
 65: }
 66: 

 70: PetscErrorCode PetscOptionsHelpFindList(const char prefix[],const char title[],const char mansec[],PetscTruth *flg)
 71: {
 73:   PetscTruth     flg1,flg2,flg3;
 74:   OptionsHelp help = PetscOptionsObject.help;
 76:   while (help) {
 77:     PetscStrcmp(help->prefix,prefix,&flg1);
 78:     PetscStrcmp(help->title,title,&flg2);
 79:     PetscStrcmp(help->mansec,mansec,&flg3);
 80:     if (flg1 && flg2 && flg3) {
 81:       *flg = PETSC_TRUE;
 82:       break;
 83:     }
 84:     help = help->next;
 85:   }
 86:   return(0);

 88: }

 92: PetscErrorCode PetscOptionsHelpCheckAddList(const char prefix[],const char title[],const char mansec[],PetscTruth *flg)
 93: {
 95:   PetscOptionsHelpFindList(prefix,title,mansec,flg);
 96:   if (!(*flg)) PetscOptionsHelpAddList(prefix,title,mansec);
 97:   return(0);
 98: }

102: /*
103:     Handles setting up the data structure in a call to PetscOptionsBegin()
104: */
105: PetscErrorCode PetscOptionsBegin_Private(MPI_Comm comm,const char prefix[],const char title[],const char mansec[])
106: {

110:   PetscOptionsObject.next          = 0;
111:   PetscOptionsObject.comm          = comm;
112:   PetscOptionsObject.changedmethod = PETSC_FALSE;
113:   if (PetscOptionsObject.prefix) {
114:     PetscStrfree(PetscOptionsObject.prefix); PetscOptionsObject.prefix = 0;
115:   }
116:   PetscStrallocpy(prefix,&PetscOptionsObject.prefix);
117:   if (PetscOptionsObject.title) {
118:     PetscStrfree(PetscOptionsObject.title); PetscOptionsObject.title  = 0;
119:   }
120:   PetscStrallocpy(title,&PetscOptionsObject.title);

122:   PetscOptionsHasName(PETSC_NULL,"-help",&PetscOptionsObject.printhelp);
123:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
124:     PetscOptionsHelpCheckAddList(prefix,title,mansec,&PetscOptionsObject.alreadyprinted);
125:     if (!PetscOptionsObject.alreadyprinted) {
126:       (*PetscHelpPrintf)(comm,"%s -------------------------------------------------\n",title);
127:     }
128:   }
129:   return(0);
130: }

132: /*
133:      Handles adding another option to the list of options within this particular PetscOptionsBegin() PetscOptionsEnd()
134: */
137: static int PetscOptionsCreate_Private(const char opt[],const char text[],const char man[],OptionType t,PetscOptions *amsopt)
138: {
139:   int          ierr;
140:   PetscOptions next;

143:   PetscNew(struct _p_Options,amsopt);
144:   (*amsopt)->next  = 0;
145:   (*amsopt)->set   = PETSC_FALSE;
146:   (*amsopt)->type  = t;
147:   (*amsopt)->data  = 0;
148:   (*amsopt)->edata = 0;

150:   PetscStrallocpy(text,&(*amsopt)->text);
151:   PetscStrallocpy(opt,&(*amsopt)->option);
152:   PetscStrallocpy(man,&(*amsopt)->man);

154:   if (!PetscOptionsObject.next) {
155:     PetscOptionsObject.next = *amsopt;
156:   } else {
157:     next = PetscOptionsObject.next;
158:     while (next->next) next = next->next;
159:     next->next = *amsopt;
160:   }
161:   return(0);
162: }

166: PetscErrorCode PetscOptionsGetFromGUI()
167: {
169:   PetscOptions   next = PetscOptionsObject.next;
170:   char           str[512];

172:   (*PetscPrintf)(PetscOptionsObject.comm,"%s -------------------------------------------------\n",PetscOptionsObject.title);
173:   while (next) {
174:     switch (next->type) {
175:       case OPTION_HEAD:
176:         break;
177:       case OPTION_INT:
178:         PetscPrintf(PetscOptionsObject.comm,"-%s%s <%d>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",next->option,*(int*)next->data,next->text,next->man);
179:         scanf("%s\n",str);
180:         if (str[0] != '\n') {
181:           printf("changing value\n");
182:         }
183:         break;
184:     default:
185:       break;
186:     }
187:     next = next->next;
188:   }
189:   return(0);
190: }

194: PetscErrorCode PetscOptionsEnd_Private(void)
195: {
197:   PetscOptions   last;
198:   char           option[256],value[1024],tmp[32];
199:   PetscInt       j;


203:   /*  if (PetscOptionsObject.next) { 
204:     PetscOptionsGetFromGUI();
205:     }*/

207:   PetscStrfree(PetscOptionsObject.title); PetscOptionsObject.title  = 0;
208:   PetscStrfree(PetscOptionsObject.prefix); PetscOptionsObject.prefix = 0;

210:   /* reset counter to -2; this updates the screen with the new options for the selected method */
211:   if (PetscOptionsObject.changedmethod) PetscOptionsPublishCount = -2;
212:   /* reset alreadyprinted flag */
213:   PetscOptionsObject.alreadyprinted = PETSC_FALSE;

215:   while (PetscOptionsObject.next) {
216:     if (PetscOptionsObject.next->set) {
217:       if (PetscOptionsObject.prefix) {
218:         PetscStrcpy(option,"-");
219:         PetscStrcat(option,PetscOptionsObject.prefix);
220:         PetscStrcat(option,PetscOptionsObject.next->option+1);
221:       } else {
222:         PetscStrcpy(option,PetscOptionsObject.next->option);
223:       }

225:       switch (PetscOptionsObject.next->type) {
226:         case OPTION_HEAD:
227:           break;
228:         case OPTION_INT:
229:           sprintf(value,"%d",*(PetscInt*)PetscOptionsObject.next->data);
230:           break;
231:         case OPTION_REAL:
232:           sprintf(value,"%g",*(PetscReal*)PetscOptionsObject.next->data);
233:           break;
234:         case OPTION_REAL_ARRAY:
235:           sprintf(value,"%g",((PetscReal*)PetscOptionsObject.next->data)[0]);
236:           for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
237:             sprintf(tmp,"%g",((PetscReal*)PetscOptionsObject.next->data)[j]);
238:             PetscStrcat(value,",");
239:             PetscStrcat(value,tmp);
240:           }
241:           break;
242:         case OPTION_LOGICAL:
243:           sprintf(value,"%d",*(PetscInt*)PetscOptionsObject.next->data);
244:           break;
245:         case OPTION_LIST:
246:           PetscStrcpy(value,*(char**)PetscOptionsObject.next->data);
247:           break;
248:         case OPTION_STRING: /* also handles string arrays */
249:           PetscStrcpy(value,*(char**)PetscOptionsObject.next->data);
250:           break;
251:       }
252:       PetscOptionsSetValue(option,value);
253:     }
254:     PetscStrfree(PetscOptionsObject.next->text);
255:     PetscStrfree(PetscOptionsObject.next->option);
256:     PetscFree(PetscOptionsObject.next->man);
257:     PetscFree(PetscOptionsObject.next->data);
258:     PetscFree(PetscOptionsObject.next->edata);
259:     last                    = PetscOptionsObject.next;
260:     PetscOptionsObject.next = PetscOptionsObject.next->next;
261:     PetscFree(last);
262:   }
263:   PetscOptionsObject.next = 0;
264:   return(0);
265: }

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

272:    Collective on the communicator passed in PetscOptionsBegin()

274:    Input Parameters:
275: +  opt - option name
276: .  text - short string that describes the option
277: .  man - manual page with additional information on option
278: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
279: -  defaultv - the default (current) value

281:    Output Parameter:
282: +  value - the  value to return
283: -  flg - PETSC_TRUE if found, else PETSC_FALSE

285:    Level: beginner

287:    Concepts: options database

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

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

293: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
294:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
295:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
296:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
297:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
298:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
299:           PetscOptionsList(), PetscOptionsEList()
300: @*/
301: PetscErrorCode  PetscOptionsEnum(const char opt[],const char text[],const char man[],const char **list,PetscEnum defaultv,PetscEnum *value,PetscTruth *set)
302: {
304:   PetscInt       ntext = 0;

307:   while (list[ntext++]) {
308:     if (ntext > 50) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
309:   }
310:   if (ntext < 3) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
311:   ntext -= 3;
312:   PetscOptionsEList(opt,text,man,list,ntext,list[defaultv],(PetscInt*)value,set);
313:   return(0);
314: }

316: /* -------------------------------------------------------------------------------------------------------------*/
319: /*@C
320:    PetscOptionsInt - Gets the integer value for a particular option in the database.

322:    Collective on the communicator passed in PetscOptionsBegin()

324:    Input Parameters:
325: +  opt - option name
326: .  text - short string that describes the option
327: .  man - manual page with additional information on option
328: -  defaultv - the default (current) value

330:    Output Parameter:
331: +  value - the integer value to return
332: -  flg - PETSC_TRUE if found, else PETSC_FALSE

334:    Level: beginner

336:    Concepts: options database^has int

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

340: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
341:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
342:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
343:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
344:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
345:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
346:           PetscOptionsList(), PetscOptionsEList()
347: @*/
348: PetscErrorCode  PetscOptionsInt(const char opt[],const char text[],const char man[],PetscInt defaultv,PetscInt *value,PetscTruth *set)
349: {
351:   PetscOptions   amsopt;

354:   if (PetscOptionsPublishCount == 1) {
355:     PetscOptionsCreate_Private(opt,text,man,OPTION_INT,&amsopt);
356:     PetscMalloc(sizeof(PetscInt),&amsopt->data);
357:     *(PetscInt*)amsopt->data = defaultv;
358:   }
359:   PetscOptionsGetInt(PetscOptionsObject.prefix,opt,value,set);
360:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
361:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%d>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,man);
362:   }
363:   return(0);
364: }

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

371:    Collective on the communicator passed in PetscOptionsBegin()

373:    Input Parameters:
374: +  opt - option name
375: .  text - short string that describes the option
376: .  man - manual page with additional information on option
377: -  defaultv - the default (current) value

379:    Output Parameter:
380: +  value - the value to return
381: -  flg - PETSC_TRUE if found, else PETSC_FALSE

383:    Level: beginner

385:    Concepts: options database^has int

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

389: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
390:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
391:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
392:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
393:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
394:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
395:           PetscOptionsList(), PetscOptionsEList()
396: @*/
397: PetscErrorCode  PetscOptionsString(const char opt[],const char text[],const char man[],const char defaultv[],char value[],size_t len,PetscTruth *set)
398: {

402:   PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
403:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
404:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%s>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,man);
405:   }
406:   return(0);
407: }

409: /*
410:      Publishes an AMS double field (with the default value in it) and with a name
411:    given by the text string
412: */
415: /*@C
416:    PetscOptionsReal - Gets the PetscReal value for a particular option in the database.

418:    Collective on the communicator passed in PetscOptionsBegin()

420:    Input Parameters:
421: +  opt - option name
422: .  text - short string that describes the option
423: .  man - manual page with additional information on option
424: -  defaultv - the default (current) value

426:    Output Parameter:
427: +  value - the value to return
428: -  flg - PETSC_TRUE if found, else PETSC_FALSE

430:    Level: beginner

432:    Concepts: options database^has int

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

436: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
437:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
438:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
439:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
440:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
441:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
442:           PetscOptionsList(), PetscOptionsEList()
443: @*/
444: PetscErrorCode  PetscOptionsReal(const char opt[],const char text[],const char man[],PetscReal defaultv,PetscReal *value,PetscTruth *set)
445: {

449:   PetscOptionsGetReal(PetscOptionsObject.prefix,opt,value,set);
450:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
451:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%G>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,man);
452:   }
453:   return(0);
454: }

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

461:    Collective on the communicator passed in PetscOptionsBegin()

463:    Input Parameters:
464: +  opt - option name
465: .  text - short string that describes the option
466: .  man - manual page with additional information on option
467: -  defaultv - the default (current) value

469:    Output Parameter:
470: +  value - the value to return
471: -  flg - PETSC_TRUE if found, else PETSC_FALSE

473:    Level: beginner

475:    Concepts: options database^has int

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

479: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
480:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
481:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
482:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
483:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
484:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
485:           PetscOptionsList(), PetscOptionsEList()
486: @*/
487: PetscErrorCode  PetscOptionsScalar(const char opt[],const char text[],const char man[],PetscScalar defaultv,PetscScalar *value,PetscTruth *set)
488: {

492: #if !defined(PETSC_USE_COMPLEX)
493:   PetscOptionsReal(opt,text,man,defaultv,value,set);
494: #else
495:   PetscOptionsGetScalar(PetscOptionsObject.prefix,opt,value,set);
496: #endif
497:   return(0);
498: }

500: /*
501:      Publishes an AMS logical field (with the default value in it) and with a name
502:    given by the text string
503: */
506: /*@C
507:    PetscOptionsName - Determines if a particular option is in the database

509:    Collective on the communicator passed in PetscOptionsBegin()

511:    Input Parameters:
512: +  opt - option name
513: .  text - short string that describes the option
514: -  man - manual page with additional information on option

516:    Output Parameter:
517: .  flg - PETSC_TRUE if found, else PETSC_FALSE

519:    Level: beginner

521:    Concepts: options database^has int

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

525: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
526:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
527:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
528:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
529:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
530:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
531:           PetscOptionsList(), PetscOptionsEList()
532: @*/
533: PetscErrorCode  PetscOptionsName(const char opt[],const char text[],const char man[],PetscTruth *flg)
534: {

538:   PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
539:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
540:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
541:   }
542:   return(0);
543: }

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

550:    Collective on the communicator passed in PetscOptionsBegin()

552:    Input Parameters:
553: +  opt - option name
554: .  text - short string that describes the option
555: .  man - manual page with additional information on option
556: .  list - the possible choices
557: -  defaultv - the default (current) value

559:    Output Parameter:
560: +  value - the value to return
561: -  set - PETSC_TRUE if found, else PETSC_FALSE

563:    Level: intermediate
564:    
565:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

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

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

572:    Concepts: options database^list

574: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
575:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
576:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
577:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
578:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
579:           PetscOptionsList(), PetscOptionsEList()
580: @*/
581: PetscErrorCode  PetscOptionsList(const char opt[],const char ltext[],const char man[],PetscFList list,const char defaultv[],char value[],PetscInt len,PetscTruth *set)
582: {

586:   PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
587:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
588:     PetscFListPrintTypes(list,PetscOptionsObject.comm,stdout,PetscOptionsObject.prefix,opt,ltext,man);
589:   }
590:   return(0);
591: }

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

598:    Collective on the communicator passed in PetscOptionsBegin()

600:    Input Parameters:
601: +  opt - option name
602: .  ltext - short string that describes the option
603: .  man - manual page with additional information on option
604: .  list - the possible choices
605: .  ntext - number of choices
606: -  defaultv - the default (current) value

608:    Output Parameter:
609: +  value - the index of the value to return
610: -  set - PETSC_TRUE if found, else PETSC_FALSE
611:    
612:    Level: intermediate

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

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

618:    Concepts: options database^list

620: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
621:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
622:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
623:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
624:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
625:           PetscOptionsList(), PetscOptionsEList()
626: @*/
627: PetscErrorCode  PetscOptionsEList(const char opt[],const char ltext[],const char man[],const char **list,PetscInt ntext,const char defaultv[],PetscInt *value,PetscTruth *set)
628: {
630:   PetscInt       i;

633:   PetscOptionsGetEList(PetscOptionsObject.prefix,opt,list,ntext,value,set);
634:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
635:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%s> (choose one of)",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv);
636:     for (i=0; i<ntext; i++){
637:       (*PetscHelpPrintf)(PetscOptionsObject.comm," %s",list[i]);
638:     }
639:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"\n");
640:   }
641:   return(0);
642: }

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

650:    Collective on the communicator passed in PetscOptionsBegin()

652:    Input Parameters:
653: +  opt - option name
654: .  text - short string that describes the option
655: -  man - manual page with additional information on option

657:    Output Parameter:
658: .  flg - whether that option was set or not
659:    
660:    Level: intermediate

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

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

666:     Concepts: options database^logical group

668: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
669:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
670:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
671:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
672:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
673:           PetscOptionsList(), PetscOptionsEList()
674: @*/
675: PetscErrorCode  PetscOptionsTruthGroupBegin(const char opt[],const char text[],const char man[],PetscTruth *flg)
676: {

680:   PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
681:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
682:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  Pick at most one of -------------\n");
683:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"    -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
684:   }
685:   return(0);
686: }

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

694:    Collective on the communicator passed in PetscOptionsBegin()

696:    Input Parameters:
697: +  opt - option name
698: .  text - short string that describes the option
699: -  man - manual page with additional information on option

701:    Output Parameter:
702: .  flg - PETSC_TRUE if found, else PETSC_FALSE
703:    
704:    Level: intermediate

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

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

710:     Concepts: options database^logical group

712: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
713:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
714:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
715:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
716:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
717:           PetscOptionsList(), PetscOptionsEList()
718: @*/
719: PetscErrorCode  PetscOptionsTruthGroup(const char opt[],const char text[],const char man[],PetscTruth *flg)
720: {

724:   PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
725:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
726:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"    -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
727:   }
728:   return(0);
729: }

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

737:    Collective on the communicator passed in PetscOptionsBegin()

739:    Input Parameters:
740: +  opt - option name
741: .  text - short string that describes the option
742: -  man - manual page with additional information on option

744:    Output Parameter:
745: .  flg - PETSC_TRUE if found, else PETSC_FALSE
746:    
747:    Level: intermediate

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

751:    Must follow a PetscOptionsTruthGroupBegin()

753:     Concepts: options database^logical group

755: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
756:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
757:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
758:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
759:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
760:           PetscOptionsList(), PetscOptionsEList()
761: @*/
762: PetscErrorCode  PetscOptionsTruthGroupEnd(const char opt[],const char text[],const char man[],PetscTruth *flg)
763: {

767:   PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
768:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
769:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"    -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
770:   }
771:   return(0);
772: }

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

779:    Collective on the communicator passed in PetscOptionsBegin()

781:    Input Parameters:
782: +  opt - option name
783: .  text - short string that describes the option
784: -  man - manual page with additional information on option

786:    Output Parameter:
787: .  flg - PETSC_TRUE or PETSC_FALSE
788: .  set - PETSC_TRUE if found, else PETSC_FALSE

790:    Level: beginner

792:    Concepts: options database^logical

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

796: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
797:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
798:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
799:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
800:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
801:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
802:           PetscOptionsList(), PetscOptionsEList()
803: @*/
804: PetscErrorCode  PetscOptionsTruth(const char opt[],const char text[],const char man[],PetscTruth deflt,PetscTruth *flg,PetscTruth *set)
805: {
807:   PetscTruth     iset;

810:   PetscOptionsGetTruth(PetscOptionsObject.prefix,opt,flg,&iset);
811:   if (!iset) {
812:     if (flg) *flg = deflt;
813:   }
814:   if (set) *set = iset;
815:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
816:     const char *v = PetscTruths[deflt];
817:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s: <%s> %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,v,text,man);
818:   }
819:   return(0);
820: }

824: /*@C
825:    PetscOptionsRealArray - Gets an array of double values for a particular
826:    option in the database. The values must be separated with commas with 
827:    no intervening spaces. 

829:    Collective on the communicator passed in PetscOptionsBegin()

831:    Input Parameters:
832: +  opt - the option one is seeking
833: .  text - short string describing option
834: .  man - manual page for option
835: -  nmax - maximum number of values

837:    Output Parameter:
838: +  value - location to copy values
839: .  nmax - actual number of values found
840: -  set - PETSC_TRUE if found, else PETSC_FALSE

842:    Level: beginner

844:    Notes: 
845:    The user should pass in an array of doubles

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

849:    Concepts: options database^array of strings

851: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
852:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
853:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
854:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
855:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
856:           PetscOptionsList(), PetscOptionsEList()
857: @*/
858: PetscErrorCode  PetscOptionsRealArray(const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscTruth *set)
859: {
861:   PetscInt       i;

864:   PetscOptionsGetRealArray(PetscOptionsObject.prefix,opt,value,n,set);
865:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
866:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%G",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,value[0]);
867:     for (i=1; i<*n; i++) {
868:       (*PetscHelpPrintf)(PetscOptionsObject.comm,",%G",value[i]);
869:     }
870:     (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,man);
871:   }
872:   return(0);
873: }


878: /*@C
879:    PetscOptionsIntArray - Gets an array of integers for a particular
880:    option in the database. The values must be separated with commas with 
881:    no intervening spaces. 

883:    Collective on the communicator passed in PetscOptionsBegin()

885:    Input Parameters:
886: +  opt - the option one is seeking
887: .  text - short string describing option
888: .  man - manual page for option
889: -  nmax - maximum number of values

891:    Output Parameter:
892: +  value - location to copy values
893: .  nmax - actual number of values found
894: -  set - PETSC_TRUE if found, else PETSC_FALSE

896:    Level: beginner

898:    Notes: 
899:    The user should pass in an array of integers

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

903:    Concepts: options database^array of strings

905: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
906:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
907:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
908:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
909:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
910:           PetscOptionsList(), PetscOptionsEList(), PetscOptionsRealArray()
911: @*/
912: PetscErrorCode  PetscOptionsIntArray(const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscTruth *set)
913: {
915:   PetscInt       i;

918:   PetscOptionsGetIntArray(PetscOptionsObject.prefix,opt,value,n,set);
919:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
920:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%d",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,value[0]);
921:     for (i=1; i<*n; i++) {
922:       (*PetscHelpPrintf)(PetscOptionsObject.comm,",%d",value[i]);
923:     }
924:     (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,man);
925:   }
926:   return(0);
927: }

931: /*@C
932:    PetscOptionsStringArray - Gets an array of string values for a particular
933:    option in the database. The values must be separated with commas with 
934:    no intervening spaces. 

936:    Collective on the communicator passed in PetscOptionsBegin()

938:    Input Parameters:
939: +  opt - the option one is seeking
940: .  text - short string describing option
941: .  man - manual page for option
942: -  nmax - maximum number of strings

944:    Output Parameter:
945: +  value - location to copy strings
946: .  nmax - actual number of strings found
947: -  set - PETSC_TRUE if found, else PETSC_FALSE

949:    Level: beginner

951:    Notes: 
952:    The user should pass in an array of pointers to char, to hold all the
953:    strings returned by this function.

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

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

960:    Concepts: options database^array of strings

962: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
963:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
964:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
965:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
966:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
967:           PetscOptionsList(), PetscOptionsEList()
968: @*/
969: PetscErrorCode  PetscOptionsStringArray(const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscTruth *set)
970: {

974:   PetscOptionsGetStringArray(PetscOptionsObject.prefix,opt,value,nmax,set);
975:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
976:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
977:   }
978:   return(0);
979: }


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

988:    Collective on the communicator passed in PetscOptionsBegin()

990:    Input Parameter:
991: .   head - the heading text

993:    
994:    Level: intermediate

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

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

1000:    Concepts: options database^subheading

1002: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1003:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1004:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1005:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1006:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1007:           PetscOptionsList(), PetscOptionsEList()
1008: @*/
1009: PetscErrorCode  PetscOptionsHead(const char head[])
1010: {

1014:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1015:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  %s\n",head);
1016:   }
1017:   return(0);
1018: }